Signaturen

Signaturen sind eine Methode zur Authentifizierung von Anfragen, die an die Cloud Storage XML API gesendet werden. Sie werden beispielsweise bei der Arbeit mit signierten URLs oder HTML-Formularen verwendet. Die Erläuterungen auf dieser Seite beziehen sich auf Signaturen, die mit dem V4-Signaturprozess erstellt wurden. Dies ist der empfohlene Prozess zum Erstellen von Signaturen.

Signaturen sind spezifisch für die Cloud Storage XML API und unterscheiden sich von OAuth 2.0-Tokens. OAuth 2.0-Tokens können auch mit der XML API verwendet werden und sind allgemeiner für Google Cloud-Dienste anwendbar, einschließlich der Cloud Storage JSON API.

Übersicht

Signaturen bieten sowohl eine Identität als auch eine starke Authentifizierung, wodurch Anfragen an Cloud Storage mithilfe der Autorisierung eines bestimmten Kontos verarbeitet werden können. Mit Signaturen ist eine solche Authentifizierung möglich, ohne die mit diesem Konto verknüpften vertraulichen Schlüsselinformationen, die sogenannten Secrets oder privaten Schlüssel, preiszugeben.

Wenn Sie eine Anfrage mit einer Signatur senden, verwendet Cloud Storage seine Kopie der Schlüsselinformationen, um für die Anfrage eine äquivalente Signatur zu erstellen. Wenn die in der Anfrage enthaltene Signatur mit der von Cloud Storage erstellten Signatur übereinstimmt, weiß Cloud Storage, dass die Signatur in der Anfrage mit dem verknüpften Secret oder privaten Schlüssel erstellt wurde.

In Cloud Storage müssen Signaturen verwendet werden, wenn mit Folgendem gearbeitet wird:

• Signierte URLs
• HTML-Formulare

Außerdem können Signaturen im Authorization-Header von XML API-Anfragen verwendet werden.

Es bietet sich an, in direkten Anfragen Signaturen zu verwenden, wenn Sie einfache Migrationen aus Amazon S3 durchführen. Der empfohlene Authentifizierungsvorgang für direkte Anfragen ist jedoch die Verwendung von OAuth 2.0-Tokens.

Struktur

Die Komponenten und der Prozess zum Erstellen einer Signatur hängen davon ab, wofür Sie diese verwenden und mit welchem Authentifizierungsschlüssel Sie arbeiten. Im Allgemeinen besteht eine Signatur aus zwei Komponenten: Signierschlüssel und Anfrageinformationen. Sie wenden auf diese beiden Komponenten einen Signaturalgorithmus an, um die Signatur zu erstellen. In der folgenden Tabelle sind die verschiedenen Anwendungsfälle für Signaturen und die Komponenten aufgeführt, die Sie jeweils zum Erstellen der Signatur benötigen:

Zu signierender String

Ein zu signierender String enthält Metainformationen zu Ihrer Anfrage und einen Hash der kanonischen Anfrage, die Sie signieren möchten.

Struktur

Ein zu signierender String muss UTF-8-codiert sein und die folgende Struktur aufweisen, einschließlich der Verwendung von Zeilenumbrüchen zwischen den einzelnen Elementen:

SIGNING_ALGORITHM
ACTIVE_DATETIME
CREDENTIAL_SCOPE
HASHED_CANONICAL_REQUEST

Signaturalgorithmus

Der Wert, den Sie für SIGNING_ALGORITHM verwenden, hängt von der Art des verwendeten Schlüssels und den Erweiterungen ab, die Sie für Ihre Header oder Abfrageparameter verwenden:

Aktive Datumszeit

Das Datum und die Uhrzeit, an dem und zu der die Signatur verwendet werden kann, und zwar im ISO 8601-Basisformat YYYYMMDD'T'HHMMSS'Z'.

• Bei signierten URLs kann die Signatur 15 Minuten vor Beginn der aktiven Datumszeit bis zur von Ihnen angegebenen Ablaufzeit verwendet werden. Die aktive Datumszeit muss mit dem Abfragestringparameter X-Goog-Date der signierten URL übereinstimmen und muss denselben Tag verwenden, den Sie im Anmeldedatenbereich angegeben haben.

• Bei Anfragen mit signiertem Header kann die Signatur 15 Minuten vor der aktiven Datumszeit bis zu 15 Minuten nach der aktiven Datumszeit verwendet werden. Die aktive Datumszeit muss mit dem Header x-goog-date der Anfrage mit der Signatur übereinstimmen und die aktive Datumszeit muss denselben Tag verwenden, den Sie im Anmeldedatenbereich angegeben haben.

Anmeldedatenbereich

Der Anmeldedatenbereich für die Anfrage

Hash der kanonischen Anfrage

Der hex-codierte SHA-256-Hash einer kanonischen Anfrage. Verwenden Sie eine SHA-256-Hash-Funktion, um einen Hashwert der kanonischen Anfrage zu erstellen. Ihre Programmiersprache sollte eine Bibliothek zum Erstellen von SHA-256-Hashwerten haben. Beispiel für einen Hashwert:

436b7ce722d03b17d3f790255dd57904f7ed61c02ac5127a0ca8063877e4e42c

Beispiel

Das folgende Beispiel zeigt einen korrekt formatierten zu signierenden String, wobei Zeilenumbrüche als neue Zeilen und nicht als \n dargestellt sind:

GOOG4-RSA-SHA256
20191201T190859Z
20191201/us-central1/storage/goog4_request
54f3076005db23fbecdb409d25c0ccb9fb8b5e24c59f12634654c0be13459af0

Richtliniendokument

In einem Richtliniendokument wird definiert, was Nutzer mit Zugriff auf das entsprechende HTML-Formular in Cloud Storage hochladen können. Ein Richtliniendokument stellt die nötige Autorisierung bereit, damit mit dem HTML-Formular Dateien in den Ziel-Bucket hochgeladen werden können. Mithilfe von Richtliniendokumenten können Sie Besuchern einer Website erlauben, Dateien in Cloud Storage hochzuladen.

Ein Richtliniendokument wird im Format "JavaScript Object Notation" (JSON) erstellt. Das Richtliniendokument muss sowohl UTF-8- als auch Base64-codiert sein. Ein Richtliniendokument enthält die folgenden Abschnitte:

Der Abschnitt conditions muss Folgendes enthalten:

• Eine Bedingungsanweisung für jedes Feld, das Sie in Ihrem HTML-Formular verwenden, mit Ausnahme der Felder x-goog-signature, file und policy.

• Eine "bucket"-Bedingungsanweisung, auch wenn Sie das Bucket-Feld im HTML-Formular nicht verwenden.

Wenn Sie mehrere Bedingungsanweisungen für dasselbe Feld verwenden möchten, sollten Sie für jede Anweisung ein separates HTML-Formular erstellen. In den Bedingungsanweisungen können drei Bedingungstypen verwendet werden:

• Genaue Übereinstimmung

  Führt eine genaue Übereinstimmung für ein Feld aus. Der im angegebenen Feld des HTML-Formulars verwendete Wert muss mit dem festgelegten Wert in dieser Bedingung übereinstimmen. Legen Sie diese Bedingung mit einem der folgenden Syntaxstile fest:

  {"field" : "value"}

  ["eq", "$field", "value"]

  Alle gültigen HTML-Formularfelder mit Ausnahme von Content-Length können die genaue Übereinstimmung verwenden.

• Beginnt mit

  Wenn der Wert eines Felds mit einem bestimmten Präfix beginnen muss, verwenden Sie die Bedingung starts-with mit der folgenden Syntax:

  ["starts-with", "$field", "value"]

  Wenn für den Wert eines Felds keine Einschränkungen gelten, verwenden Sie die Bedingung starts-with mit der folgenden Syntax:

  ["starts-with", "$field", ""]

  Alle gültigen HTML-Formularfelder außer Content-Length können die Bedingung starts-with verwenden.

• Content-Length-Bereich

  Gibt einen Bereich zulässiger Werte an, die im Feld Content-Length verwendet werden können. Geben Sie diese Bedingung mit der folgenden Syntax an:

  ["content-length-range", min_range, max_range]

Beispiel

Das folgende Beispiel zeigt ein Richtliniendokument:

{"expiration": "2020-06-16T11:11:11Z",
 "conditions": [
  ["starts-with", "$key", ""],
  {"bucket": "travel-maps"},
  {"success_action_redirect": "http://www.example.com/success_notification.html"},
  ["eq", "$Content-Type", "image/jpeg"],
  ["content-length-range", 0, 1000000],
  {"x-goog-algorithm": "GOOG4-RSA-SHA256"},
  {"x-goog-credential": "example_account@example_project.iam.gserviceaccount.com/20191102/us-central1/storage/goog4_request"},
  {"x-goog-date": "20191102T043530Z"}
  ]
}

In diesem Richtliniendokument werden die folgenden Bedingungen definiert:

• Das Formular läuft am 16. Juni 2020 um 11:11:11 Uhr (UTC) ab.
• Der Dateiname darf mit einem beliebigen gültigen Zeichen beginnen.
• Die Datei muss in den Bucket travel-maps hochgeladen werden.
• Wenn der Upload erfolgreich ist, wird der Nutzer zu http://www.example.com/success_notification.html weitergeleitet.
• Über das Formular können nur Bilder hochgeladen werden.
• Nutzer können keine Datei hochladen, die größer als 1 MB ist.

Anmeldedatenbereich

Der Anmeldedatenbereich ist ein String, der sowohl bei den zu signierenden Strings als auch in Richtliniendokumenten vorkommt. Der Anmeldedatenbereich hat folgende Struktur:

DATE/LOCATION/SERVICE/REQUEST_TYPE

Der Anmeldedatenbereich umfasst folgende Komponenten:

• DATE: Das Datum, an dem die Signatur nutzbar wird, formatiert als JJJJMMTT.
• LOCATION: Für Cloud Storage-Ressourcen können Sie für LOCATION einen beliebigen Wert verwenden. Empfohlen wird der Speicherort, der mit der Ressource verknüpft ist, auf die sich die Signatur bezieht. Beispiel: us-central1 Dieser Parameter dient der Kompatibilität mit Amazon S3.
• SERVICE: Der Dienstname. Beim Zugriff auf Cloud Storage-Ressourcen lautet dieser Wert in den meisten Fällen storage. Wenn Sie Amazon S3-x-amz-Erweiterungen verwenden, ist dieser Wert s3.
• REQUEST_TYPE: Der Anfragetyp. Beim Zugriff auf Cloud Storage-Ressourcen lautet dieser Wert in den meisten Fällen goog4_request. Wenn Sie Amazon S3-x-amz-Erweiterungen verwenden, ist dieser Wert aws4_request.

Ein typischer Anmeldedatenbereich sieht beispielsweise so aus:

20191102/us-central1/storage/goog4_request

Beim Verwenden eines zu signierenden Strings mit x-amz-Erweiterungen sieht der Anmeldedatenbereich dagegen so aus:

20150830/us-east1/s3/aws4_request

Signatur

Zum Erstellen einer Signatur verwenden Sie einen Signaturalgorithmus, der auch als kryptografische Hash-Funktion bezeichnet wird, um den zu signierenden String oder das Richtliniendokument zu signieren. Der zu verwendende Signaturalgorithmus hängt vom Typ des Authentifizierungsschlüssels ab:

Unter Signaturen erstellen finden Sie eine Anleitung zum Signieren des zu signierenden Strings oder Richtliniendokuments mithilfe eines RSA-Schlüssels und der IAM-Methode signBlob.

Signierschlüssel vom HMAC-Schlüssel ableiten

Beim Signieren mit einem HMAC-Schlüssel müssen Sie einen UTF-8-codierten Signierschlüssel erstellen, der von dem HMAC-Schlüssel-Secret abgeleitet wurde. Der abgeleitete Schlüssel bezieht sich auf das Datum, die Region, den Dienst und den Typ Ihrer Anfrage. Der folgende Pseudocode zeigt, wie der Signierschlüssel abgeleitet wird:

key_date = HMAC-SHA256("PREFIX" + HMAC_KEY_SECRET, "DATE")
key_region = HMAC-SHA256(key_date, "LOCATION")
key_service = HMAC-SHA256(key_region, "SERVICE")
signing_key = HMAC-SHA256(key_service, "REQUEST_TYPE")

Der Pseudocode hat die folgenden Komponenten:

• PREFIX: Beim Zugriff auf Cloud Storage-Ressourcen lautet dieser Wert in den meisten Fällen GOOG4. Wenn Sie Amazon S3-x-amz-Erweiterungen verwenden, ist dieser Wert AWS4.
• HMAC_KEY_SECRET: Das Secret für den HMAC-Schlüssel, mit dem Sie die Anfrage senden und signieren.
• DATE, LOCATION, SERVICE, REQUEST_TYPE: Diese Werte müssen mit den Werten übereinstimmen, die im Anmeldedatenbereich angegeben sind.

Nach dem Signieren

Zum Fertigstellen der Signatur muss die Ausgabe des Signierprozesses, die als Nachrichten-Digest bezeichnet wird, hex-codiert sein.

Beispiel

Der folgende Pseudocode dient dem Signieren eines Richtliniendokuments:

EncodedPolicy = Base64Encode(PolicyDocument)
MessageDigest = SigningAlgorithm(SigningKey, EncodedPolicy)
Signature = HexEncode(MessageDigest)

Der folgende Pseudocode dient zum Signieren eines zu signierenden Strings:

MessageDigest = SigningAlgorithm(SigningKey, StringToSign)
Signature = HexEncode(MessageDigest)

Nächste Schritte

• Signatur in einer signierten URL verwenden
• Verwenden Sie Ihre Signatur in einer Anfrage mit einem Authorization-Header.
• Signatur in einem HTML-Formular verwenden