Signatures

Les signatures constituent une méthode d'authentification des requêtes envoyées à l'API XML de Cloud Storage. Vous y avez recours, par exemple, en cas d'utilisation d'URL signées ou de formulaires HTML. Cette page s'applique aux signatures créées à l'aide du processus de signature V4, qui est recommandé pour la création de signatures.

Les signatures sont spécifiques à l'API XML de Cloud Storage et sont distinctes des jetons OAuth 2.0. Les jetons OAuth 2.0 peuvent également être utilisés avec l'API XML et sont plus généralement applicables aux services Google Cloud, y compris l'API JSON Cloud Storage.

Présentation

Les signatures fournissent à la fois une identité et une authentification forte, ce qui garantit que les requêtes adressées à Cloud Storage sont traitées avec l'autorisation d'un compte spécifique. Les signatures permettent ce type d'authentification sans révéler les informations de clé sensibles, appelées secrets ou clés privées, associées à ce compte.

Lorsque vous effectuez une requête avec une signature, Cloud Storage utilise sa copie des informations de clé afin de calculer une signature équivalente pour la requête. Si la signature incluse dans la requête correspond à celle calculée par Cloud Storage, Cloud Storage sait que la signature a été créée à l'aide du secret ou de la clé privée approprié.

Dans Cloud Storage, vous devez vous servir de signatures en cas d'utilisation des éléments suivants :

En outre, les signatures peuvent être utilisées dans l'en-tête Authorization des requêtes de l'API XML.

Les signatures dans les requêtes directes sont utiles lors de l'exécution de migrations simples depuis Amazon S3. Toutefois, le processus d'authentification recommandé pour les requêtes directes consiste à utiliser des jetons OAuth 2.0.

Structure

Les composants et le processus de création d'une signature dépendent de ce que vous voulez en faire et de la clé d'authentification que vous utilisez. De manière générale, la signature comporte deux composants : la clé de signature et les informations sur la requête. Vous devez appliquer un algorithme de signature à ces deux composants pour créer la signature. Le tableau ci-dessous résume les différents cas d'utilisation des signatures et les composants nécessaires à la construction de la signature :

Cas d'utilisation Clé de signature Informations sur la requête
Formulaire HTML avec une clé RSA Utilise directement la clé privée RSA Document de stratégie encodé en base64
Formulaire HTML avec une clé HMAC Clé dérivée du secret de la clé HMAC Document de stratégie encodé en base64
URL signée ou requête signée avec une clé RSA Utilise directement la clé privée RSA Chaîne à signer
URL signée ou requête signée avec une clé HMAC Clé dérivée du secret de la clé HMAC Chaîne à signer

Chaîne à signer

Une chaîne à signer inclut des méta-informations sur votre requête et un hachage de la requête canonique que vous souhaitez signer.

Structure

Une chaîne à signer doit être encodée en UTF-8 et avoir la structure suivante, y compris utiliser des sauts de ligne entre chaque élément :

SIGNING_ALGORITHM
ACTIVE_DATETIME
CREDENTIAL_SCOPE
HASHED_CANONICAL_REQUEST

Algorithme de signature

La valeur de SIGNING_ALGORITHM dépend du type de clé utilisé et des extensions que vous utilisez pour vos en-têtes ou paramètres de requête :

Cas d'utilisation Valeur de SIGNING_ALGORITHM
Extensions x-goog-* et clé RSA GOOG4-RSA-SHA256
Extensions x-goog-* et clé HMAC GOOG4-HMAC-SHA256
Extensions x-amz-* et clé HMAC AWS4-HMAC-SHA256

Date et heure d'activation

Date et heure auxquelles la signature peut être utilisée, au format de base ISO 8601 YYYYMMDD'T'HHMMSS'Z'.

  • Pour les URL signées, la signature est utilisable de 15 minutes avant les date et heure d'activation jusqu'à l'heure d'expiration spécifiée. Les date et heure d'activation doivent correspondre au paramètre de chaîne de requête X-Goog-Date de l'URL signée et doivent utiliser le jour spécifié dans le champ d'application des identifiants.

  • Pour les requêtes avec en-têtes signés, la signature est utilisable de 15 minutes avant les date et heure d'activation jusqu'à 15 minutes après celles-ci. Les date et heure d'activation doivent correspondre à l'en-tête x-goog-date de la requête à l'aide de la signature, et les date et heure d'activation doivent utiliser le jour spécifié dans le champ d'application des identifiants.

Niveau d'accès des identifiants

Champ d'application des identifiants pour la requête.

Hachage de la requête canonique

Hachage SHA-256 à encodage hexadécimal d'une requête canonique. Utilisez une fonction de hachage SHA-256 pour créer la valeur de hachage de la requête canonique. Votre langage de programmation doit disposer d'une bibliothèque permettant de créer des hachages SHA-256. Voici un exemple de valeur de hachage :

436b7ce722d03b17d3f790255dd57904f7ed61c02ac5127a0ca8063877e4e42c

Exemple

Voici un exemple de chaîne à signer correctement formatée, dont les sauts de ligne s'affichent en tant que tels et non sous la forme \n :

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

Document de stratégie

Un document de stratégie définit ce que les utilisateurs ayant accès au formulaire HTML correspondant peuvent importer dans Cloud Storage. Un document de stratégie fournit une autorisation pour s'assurer que le formulaire HTML peut importer des fichiers dans le bucket cible. Vous pouvez utiliser des documents de stratégie pour autoriser les visiteurs d'un site Web à importer des fichiers dans Cloud Storage.

Un document de stratégie est construit au format JSON (JavaScript Object Notation). Le document de stratégie doit être encodé en UTF-8 et en base64. Un document de stratégie contient les sections suivantes :

Entrée Description
expiration Heure d'expiration du document de stratégie, au format de base ISO 8601 YYYYMMDD'T'HHMMSS'Z'. Un document de stratégie arrivé à expiration interrompt le fonctionnement du formulaire HTML.
conditions Tableau des conditions que chaque importation doit remplir.

La section conditions doit inclure :

  • une instruction de condition pour chaque champ que vous utilisez dans votre formulaire HTML, à l'exception des champs x-goog-signature, file et policy ;

  • une instruction de condition "bucket", même si vous n'utilisez pas le champ "bucket" dans votre formulaire HTML.

Si vous souhaitez utiliser plusieurs instructions de condition pour le même champ, vous devez créer un formulaire HTML distinct pour chacune d'elles. Trois types de conditions peuvent être utilisés dans des instructions de condition :

  • Correspondance exacte

    Effectue une correspondance exacte pour un champ. La valeur utilisée dans le champ spécifié du formulaire HTML doit correspondre à la valeur définie dans cette condition. Définissez cette condition à l'aide de l'un des styles de syntaxe suivants :

    {"field" : "value"}
     
    ["eq", "$field", "value"]

    Tous les champs valides du formulaire HTML, à l'exception de Content-Length, peuvent utiliser la correspondance exacte.

  • Starts With

    Si la valeur d'un champ doit commencer par un certain préfixe, utilisez la condition starts-with avec la syntaxe suivante :

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

    Si la valeur d'un champ ne comporte aucune restriction, utilisez la condition starts-with avec la syntaxe suivante :

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

    Tous les champs valides du formulaire HTML, à l'exception de Content-Length, peuvent utiliser la condition starts-with.

  • Plage de longueur du contenu

    Spécifie une plage de valeurs acceptables pouvant être utilisées dans le champ Content-Length. Spécifiez cette condition à l'aide de la syntaxe suivante :

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

Exemple

Voici un exemple de document de stratégie :

{"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"}
  ]
}

Ce document définit les conditions suivantes :

  • Le formulaire expire le 16 juin 2020 à 11:11:11 UTC.
  • Le nom du fichier peut commencer par n'importe quel caractère valide.
  • Le fichier doit être importé dans le bucket travel-maps.
  • Si l'importation réussit, l'utilisateur est redirigé vers http://www.example.com/success_notification.html.
  • Le formulaire permet d'importer seulement des images.
  • Un utilisateur ne peut pas importer un fichier d'une taille supérieure à 1 Mo.

Champ d'application des identifiants

Le champ d'application des identifiants est une chaîne qui apparaît à la fois dans les chaînes à signes et dans les documents de stratégie. La structure du champ d'application des identifiants est la suivante :

DATE/LOCATION/SERVICE/REQUEST_TYPE

Les composants du champ d'application des identifiants sont les suivants :

  • DATE : date à laquelle la signature devient utilisable, au format AAAAMMJJ.
  • LOCATION : pour les ressources Cloud Storage, vous pouvez utiliser n'importe quelle valeur pour LOCATION. La valeur recommandée est l'emplacement associé à la ressource à laquelle la signature s'applique. Par exemple, us-central1. Ce paramètre existe pour maintenir la compatibilité avec Amazon S3.
  • SERVICE : le nom du service. Dans la plupart des cas, lorsque vous accédez à des ressources Cloud Storage, cette valeur est storage. Lorsque vous utilisez des extensions x-amz Amazon S3, cette valeur est s3.
  • REQUEST_TYPE : le type de requête. Dans la plupart des cas, lorsque vous accédez à des ressources Cloud Storage, cette valeur est goog4_request. Lorsque vous utilisez des extensions x-amz Amazon S3, cette valeur est aws4_request.

Par exemple, un champ d'application des identifiants type ressemble à ceci :

20191102/us-central1/storage/goog4_request

En revanche, en cas d'utilisation d'une chaîne à signer avec des extensions x-amz, il ressemble à ceci :

20150830/us-east1/s3/aws4_request

Signature

Pour créer une signature, vous devez utiliser un algorithme de signature, également appelé fonction de hachage cryptographique, pour signer votre chaîne à signer ou votre document de stratégie. L'algorithme de signature que vous utilisez dépend du type de clé d'authentification dont vous disposez :

Clé d'authentification Algorithme de signature Clé de signature
Clé RSA RSA-SHA256 Utilise directement la clé privée RSA
Clé HMAC HMAC-SHA256 Clé dérivée du secret de la clé HMAC

Pour savoir comment signer votre chaîne à signer ou votre document de stratégie à l'aide d'une clé RSA et de la méthode IAM signBlob, consultez la page Créer des signatures.

Clé de signature dérivée de la clé HMAC

En cas de signature avec une clé HMAC, vous devez créer une clé de signature encodée en UTF-8 dérivée du secret de votre clé HMAC. La clé dérivée est propre à la date, à l'emplacement, au service et au type de requête associés à votre requête. Le pseudo-code suivant illustre comment dériver la clé de signature :

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")

Le pseudo-code comprend les composants suivants :

  • PREFIX : dans la plupart des cas, lorsque vous accédez à des ressources Cloud Storage, cette valeur est GOOG4. Lorsque vous utilisez des extensions x-amz Amazon S3, cette valeur est AWS4.
  • HMAC_KEY_SECRET : secret de la clé HMAC que vous utilisez pour envoyer et signer la requête.
  • DATE, LOCATION, SERVICE, REQUEST_TYPE : ces valeurs doivent correspondre à celles spécifiées dans le champ d'application des identifiants.

Après la signature

Pour terminer la signature, le résultat de la signature, appelé condensé du message, doit avoir un encodage hexadécimal.

Exemple

Voici un pseudo-code permettant de signer un document de stratégie :

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

Voici un pseudo-code permettant de signer une chaîne à signer :

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

Limites

Les signatures ne peuvent pas être utilisées pour authentifier une importation si celle-ci utilise un encodage de transfert fragmenté. Utilisez les jetons OAuth 2.0 si vous souhaitez utiliser l'encodage de transfert fragmenté dans vos importations.

Étapes suivantes