Kanonische Anfragen

Kanonische Anfragen definieren die Elemente einer Anfrage, die ein Nutzer beim Senden von Anfragen mit V4-Signaturauthentifizierung wie signierten URLs an Cloud Storage einbinden muss.

Überblick

Eine kanonische Anfrage ist ein String, der eine bestimmte HTTP-Anfrage an Cloud Storage darstellt. Mit einer kanonischen Anfrage können Sie zusammen mit einem kryptografischen Schlüssel wie einem RSA-Schlüssel eine Signatur erstellen, die dann als Authentifizierung in die eigentliche Anfrage aufgenommen wird.

Eine kanonische Anfrage enthält Informationen wie das HTTP-Verb, Abfragestringparameter und Header, die voraussichtlich in der tatsächlichen Anfrage verwendet werden, sowie das Objekt, den Bucket oder eine andere Ressource, die angefragt werden soll.

Eine kanonische Anfrage gewährleistet, dass Cloud Storage beim Empfang der Anfrage dieselbe Signatur berechnen kann wie Sie. Wenn Ihre Version und die von Cloud Storage berechnete Version nicht übereinstimmen, schlägt die Anfrage fehl.

Struktur

Kanonische Anfragen haben die folgende Struktur, einschließlich der Verwendung von Zeilenumbrüchen zwischen den einzelnen Elementen:

HTTP_VERB
PATH_TO_RESOURCE
CANONICAL_QUERY_STRING
CANONICAL_HEADERS

SIGNED_HEADERS
PAYLOAD

HTTP-Verben

Signierte Anfragen können die folgenden HTTP-Verben verwenden, die als Teil der kanonischen Anfrage angegeben werden müssen:

  • DELETE
  • GET
  • HEAD
  • POST1
  • PUT

1 Signierte URLs können nur für POST-Anfragen verwendet werden, die einen fortsetzbaren Upload initiieren. Weitere Informationen finden Sie unter Signierte URLs mit fortsetzbaren Uploads verwenden.

Ressourcenpfad

Kanonische Anfragen enthalten den Pfad zu der Ressource, für die die Anfrage gilt. Der Pfad zur Ressource ist der gesamte Teil, der auf den Hostnamen folgt, steht aber immer vor dem Abfragestring.

Ist die Cloud Storage-URL beispielsweise https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg, lautet der Pfad zur Ressource /example-bucket/cat-pics/tabby.jpeg.

Wenn Sie eine alternative Cloud Storage-URL wie https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg verwenden, lautet der Pfad zur Ressource /cat-pics/tabby.jpeg.

Informationen zu weiteren URL-Endpunkten, die mit signierten URLs verwendet werden können, finden Sie unter Anfrageendpunkte.

Beim Definieren des Ressourcenpfads müssen Sie die folgenden reservierten Zeichen per URL-Encoding umwandeln: ?=!#$&'()*+,:;@[]" Sonstige per URL-Encoding umgewandelte Zeichen, die in der URL verwendet werden, sollten ebenfalls im Ressourcenpfad enthalten sein.

Kanonischer Abfragestring

Kanonische Anfragen umfassen alle Abfragestringparameter, die anschließend in signierte Anfragen mit relevanter Signatur aufgenommen werden müssen. Solche signierten Anfragen können jedoch zusätzliche Abfragestringparameter haben, die nicht in der kanonischen Anfrage angegeben sind. Der in der kanonischen Anfrage angegebene Abfragestring wird als kanonischer Abfragestring bezeichnet.

Der Abfragestring ist der gesamte Teil, der dem Fragezeichen (?) am Ende des Ressourcenpfads folgt.

Ist die Cloud Storage-URL beispielsweise https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project, ist der Abfragestring generation=1360887697105000&userProject=my-project.

Beachten Sie beim Erstellen des kanonischen Abfragestrings Folgendes:

  • Die Parameter im Abfragestring müssen lexikografisch nach dem Namen anhand des Codepunktwerts sortiert werden.

  • Jeder Parameter im Abfragestring muss durch & getrennt werden.

  • Wenn der kanonische Abfragestring leer ist, ist dieser Teil der kanonischen Gesamtanfrage einfach eine neue Zeile (\n).

Erforderliche Abfragestringparameter

Die meisten Abfragestringparameter werden nach Bedarf hinzugefügt. Die folgenden Parameter müssen jedoch in Ihrer kanonischen Anfrage enthalten sein, wenn Sie mit ihr eine signierte URL erstellen möchten:

  • X-Goog-Algorithm: Der Algorithmus, mit dem Sie die URL signieren. Gültige Werte sind GOOG4-RSA-SHA256 und GOOG4-HMAC-SHA256.
  • X-Goog-Credential: Die Anmeldedaten, mit denen Sie die URL signieren. Anmeldedaten bestehen aus einem Autorisierer und einem Anmeldedatenbereich im Format AUTHORIZER%2FCREDENTIAL_SCOPE. Der Autorisier kann ein Dienstkontoname oder eine HMAC-Schlüsselzugriffs-ID sein.
  • X-Goog-Date: Das Datum und die Uhrzeit, ab dem oder ab der die signierte URL verwendet werden kann, im ISO 8601-Basisformat YYYYMMDD'T'HHMMSS'Z'.
  • X-Goog-Expires: Die Lebensdauer der signierten URL, gemessen in Sekunden ab X-Goog-Date. Der längste Ablaufwert beträgt 604.800 Sekunden (7 Tage).
  • X-Goog-SignedHeaders: Eine durch Semikolons getrennte Liste mit Namen der in der kanonischen Anfrage definierten Header. Sie werden auch als signierte Header bezeichnet. host muss einer der Headernamen sein.

Diese Abfragestringparameter müssen anschließend in der signierten URL selbst zusammen mit dem Abfragestringparameter X-Goog-Signature verwendet werden. Dieser enthält die Signatur, die die Anfrage authentifiziert.

Kanonische Header

Kanonische Anfragen umfassen alle Header, die anschließend in signierte Anfragen mit relevanter Signatur aufgenommen werden müssen. Solche signierten Anfragen können jedoch zusätzliche Header enthalten, die nicht in der kanonischen Anfrage angegeben wurden. Ausnahmen werden unter erforderliche Header beschrieben. Die in der kanonischen Anfrage angegebenen Header werden als kanonische Header bezeichnet.

Kanonische Header können benutzerdefinierte Header sowie Erweiterungsheader enthalten, die mit x-goog- beginnen.

Sie sollten beim Angeben kanonischer Header Folgendes beachten:

  • Wandeln Sie alle Headernamen in Kleinbuchstaben um.
  • Sortieren Sie alle benutzerdefinierten Headernamen lexikografisch nach Codepunktwerten.
  • Trennen Sie jeden Header durch einen Zeilenumbruch (\n).
  • Entfernen Sie doppelt vorkommende Headernamen, indem Sie einen Headernamen mit einer durch Komma getrennten Liste an Werten erstellen. Achten Sie darauf, dass zwischen den Werten kein Leerzeichen vorhanden ist und dass die Reihenfolge der durch Kommas getrennten Liste der Reihenfolge entspricht, in der die Header in Ihrer Anfrage aufgeführt sind. Weitere Informationen finden Sie unter RFC 7230, Abschnitt 3.2.
  • Ersetzen Sie aufeinanderfolgende Leerzeichen und Zeilenumbrüche (CRLF oder LF) durch ein einzelnes Leerzeichen. Weitere Informationen zu aufeinanderfolgenden Leerzeichen finden Sie unter RFC 7230, Abschnitt 3.2.4..

  • Entfernen Sie alle Leerzeichen vor und nach dem Doppelpunkt, der auf den Headernamen folgt.

    Beispiel: Wenn Sie den benutzerdefinierten Header x-goog-acl: private verwenden, ohne das Leerzeichen hinter dem Doppelpunkt zu entfernen, wird der Fehler 403 Forbidden zurückgegeben, weil die so generierte Anfragesignatur nicht der von Google generierten Signatur entspricht.

Beispiel

Angenommen, Sie haben die folgenden Header:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

Die Konstruktion der kanonischen Header in der kanonischen Anfrage würde so aussehen:

content-type:text/plain
host:storage.googleapis.com
x-goog-meta-reviewer:jane,john

Erforderliche kanonische Header

Die meisten Header wie content-type werden nach Bedarf hinzugefügt. Die folgenden Header müssen jedoch immer in den kanonischen Headern definiert werden, wenn Sie sie in der signierten Anfrage verwenden möchten:

  • host: Der URI für den Zugriff auf Cloud Storage.
  • Header mit dem Präfix x-goog-. Der einzige dieser Header, der optional als kanonischer Header eingefügt werden kann, ist x-goog-content-sha256.
  • Header mit dem Präfix x-amz-. Der einzige dieser Header, der optional als kanonischer Header eingefügt werden kann, ist x-amz-content-sha256.

Signierte Header

Ein signierter Header ist der Name eines kanonischen Headers.

Zum Erstellen der Liste mit den signierten Headern wandeln Sie alle Headernamen in Kleinbuchstaben um, sortieren sie nach Zeichencode und trennen sie durch Semikolons (;).

Beispiel

Angenommen, Sie haben die folgenden Header:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

Die Konstruktion der signierten Header in der kanonischen Anfrage würde so aussehen:

content-type;host;x-goog-meta-reviewer

Nutzlast

  • Wenn Sie mit der kanonischen Anfrage eine signierte URL erstellen möchten, muss dieser Wert einfach der String UNSIGNED-PAYLOAD sein.

  • Wenn Ihre kanonische Anfrage als Teil einer Anfrage verwendet wird, die einen Authorization-Header verwendet:

    • Verwenden Sie UNSIGNED-PAYLOAD, wenn Sie beliebige Nutzlasten als Teil der Anfrage zulassen möchten.

    • Wenn Sie nur eine bestimmte Nutzlast zulassen möchten, sollte dieser Wert ein SHA-256-Hash der gewünschten Nutzlast in Kleinbuchstaben sein. Wenn Sie eine leere Nutzlast benötigen, verwenden Sie einen leeren String als Eingabe für die Hash-Funktion. Ein Nutzlast-Hash (in diesem Fall eine leere Nutzlast) könnte so aussehen:

      e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Beispiel

Das folgende Beispiel zeigt eine kanonische Anfrage im korrekten Format, bei der Zeilenumbrüche als neue Zeilen angezeigt werden und nicht \n:

GET
/example-bucket/tabby.jpeg

host:storage.googleapis.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20190301T190859Z

host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Nächste Schritte