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.
Übersicht
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
POST
1PUT
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 geben jeden Abfragestringparameter an, der anschließend in jede signierte Anfrage mit relevanter Signatur aufgenommen wird, mit Ausnahme des Abfragestringparameters X-Goog-Signature
oder X-Amz-Signature
.
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 sindGOOG4-RSA-SHA256
undGOOG4-HMAC-SHA256
.X-Goog-Credential
: Die Anmeldedaten, mit denen Sie die URL signieren. Anmeldedaten bestehen aus einem Autorisierer und einem Anmeldedatenbereich im FormatAUTHORIZER%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-BasisformatYYYYMMDD'T'HHMMSS'Z'
.X-Goog-Expires
: Die Lebensdauer der signierten URL, gemessen in Sekunden abX-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 Fehler403 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, istx-goog-content-sha256
. - Header mit dem Präfix
x-amz-
. Der einzige dieser Header, der optional als kanonischer Header eingefügt werden kann, istx-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 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 eine Anfrage für einen fortsetzbaren Upload initiieren, sollten Sie außerdemUNSIGNED-PAYLOAD
verwenden. Alle enthaltenen sha256-Werte werden bei fortsetzbaren Uploads ignoriert.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
- Weitere Informationen zu Signaturen und zur Verwendung kanonischer Anfragen
- Anfrage erstellen, die kanonische Anfragen verwendet
- V4-Signaturprozess mit Ihrem eigenen Programm
- Weitere Informationen zu signierten URLs