Requêtes canoniques

Les requêtes canoniques définissent les éléments d'une requête qu'un utilisateur doit inclure lorsqu'il envoie des requêtes authentifiées par signature V4, telles que des URL signées, à Cloud Storage.

Présentation

Une requête canonique est une chaîne qui représente une requête HTTP spécifique adressée à Cloud Storage. Utilisez-la avec une clé cryptographique, telle qu'une clé RSA, pour créer une signature qui est ensuite incluse dans la requête réelle à des fins d'authentification.

Une requête canonique inclut des informations telles que le verbe HTTP, les paramètres de chaîne de requête et les en-têtes censés être utilisés dans la requête, ainsi que l'objet, le bucket ou toute autre ressource faisant l'objet de la requête.

Une requête canonique garantit que, lorsque Cloud Storage reçoit la requête, il peut calculer la même signature que celle que vous avez calculée. Si votre version et la version calculée par Cloud Storage ne correspondent pas, la requête échoue.

Structure

Les requêtes canoniques ont la structure suivante et utilisent des sauts de ligne entre chaque élément :

HTTP_VERB
PATH_TO_RESOURCE
CANONICAL_QUERY_STRING
CANONICAL_HEADERS

SIGNED_HEADERS
PAYLOAD

Verbes HTTP

Les requêtes signées peuvent utiliser les verbes HTTP suivants, qui doivent être spécifiés dans le cadre de la requête canonique :

  • DELETE
  • GET
  • HEAD
  • POST1
  • PUT

1 Les URL signées ne peuvent être utilisées que pour des requêtes POST qui lancent une importation avec reprise. Pour en savoir plus, consultez la page Utiliser des URL signées pour les importations avec reprise.

Chemin d'accès à la ressource

Les requêtes canoniques incluent le chemin d'accès à la ressource à laquelle la requête s'applique. Le chemin d'accès à la ressource correspond à tout ce qui suit le nom d'hôte, mais précède toute chaîne de requête.

Par exemple, si l'URL Cloud Storage est https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg, le chemin d'accès à la ressource est /example-bucket/cat-pics/tabby.jpeg.

Si vous utilisez une autre URL Cloud Storage telle que https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg, le chemin d'accès à la ressource est /cat-pics/tabby.jpeg.

Pour connaître d'autres points de terminaison d'URL pouvant être utilisés avec des URL signées, consultez la section Points de terminaison de requêtes pour l'API XML.

Lors de la définition du chemin d'accès à la ressource, vous devez effectuer un encodage-pourcent des caractères réservés suivants : ?=!#$&'()*+,:;@[]" Tout autre encodage-pourcent utilisé dans l'URL doit également être inclus dans le chemin d'accès à la ressource.

Chaîne de requête canonique

Les requêtes canoniques incluent tous les paramètres de chaîne de requête qui doivent par la suite être inclus dans les requêtes signées qui utilisent la signature concernée. Toutefois, ces requêtes signées peuvent inclure des paramètres de chaîne de requête supplémentaires qui n'ont pas été spécifiés dans la requête canonique. La chaîne de requête spécifiée dans la requête canonique est appelée chaîne de requête canonique.

La chaîne de requête correspond à tout ce qui suit le point d'interrogation (?) à la fin du chemin d'accès à la ressource.

Par exemple, si l'URL Cloud Storage est https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project, la chaîne de requête est generation=1360887697105000&userProject=my-project.

Lors de la construction de la chaîne de requête canonique, les éléments suivants s'appliquent :

  • Il est nécessaire de classer les paramètres de la chaîne de requête par nom en appliquant un ordre de tri lexicographique aux valeurs de point de code.

  • Les paramètres de la chaîne de requête doivent être séparés par le caractère &.

  • Si votre chaîne de requête canonique est vide, cette partie de la requête canonique globale est simplement un saut de ligne (\n).

Paramètres de chaîne de requête obligatoires

La plupart des paramètres de chaîne de requête sont ajoutés en fonction des besoins. Toutefois, les paramètres suivants doivent être inclus dans votre requête canonique si vous souhaitez l'utiliser pour créer une URL signée :

  • X-Goog-Algorithm : algorithme que vous utiliserez pour signer l'URL. Les valeurs valides sont GOOG4-RSA-SHA256 et GOOG4-HMAC-SHA256.
  • X-Goog-Credential : identifiants que vous utiliserez pour signer l'URL. Les identifiants comprennent un agent d'autorisation et un champ d'application des identifiants au format AUTHORIZER%2FCREDENTIAL_SCOPE. L'agent d'autorisation peut être un nom de compte de service ou un ID d'accès de clé HMAC.
  • X-Goog-Date : date et heure auxquelles l'URL signée devient utilisable, au format de base ISO 8601 YYYYMMDD'T'HHMMSS'Z'.
  • X-Goog-Expires : durée de vie de l'URL signée, mesurée en secondes, à partir de X-Goog-Date. La valeur d'expiration la plus longue est de 604 800 secondes (sept jours).
  • X-Goog-SignedHeaders : liste des noms, séparés par des points-virgules, des en-têtes définis dans la requête canonique. Ceux-ci sont également appelés en-têtes signés. host doit être l'un des noms d'en-têtes.

Ces paramètres de chaîne de requête doivent par la suite être utilisés dans l'URL signée proprement dite, avec le paramètre de chaîne de requête X-Goog-Signature, qui contient la signature authentifiant la requête.

En-têtes canoniques

Les requêtes canoniques incluent tous les en-têtes qui doivent par la suite être inclus dans les requêtes signées qui utilisent la signature concernée. Toutefois, ces requêtes signées peuvent inclure des en-têtes supplémentaires qui n'ont pas été spécifiés dans la requête canonique, sauf dans les cas indiqués dans la section En-têtes obligatoires. Les en-têtes spécifiés dans la requête canonique sont appelés en-têtes canoniques.

Les en-têtes canoniques peuvent inclure des en-têtes personnalisés ainsi que des en-têtes d'extension commençant par x-goog-.

Lorsque vous spécifiez des en-têtes canoniques, tenez compte des points suivants :

  • Tous les noms d'en-têtes doivent apparaître en minuscules.
  • Tous les en-têtes doivent être classés par nom d'en-tête en appliquant un ordre de tri lexicographique aux valeurs de point de code.
  • Séparez chaque en-tête par un saut de ligne (\n).
  • Éliminez les en-têtes en double en créant un nom d'en-tête avec une liste de valeurs séparées par des virgules. Assurez-vous qu'il n'y a pas d'espace entre les valeurs, et que l'ordre de la liste de valeurs séparées par des virgules correspond à l'ordre dans lequel les en-têtes apparaissent dans votre requête. Pour en savoir plus, consultez la section 3.2 du document RFC 7230.
  • Remplacez les espaces de fin de ligne ou les nouvelles lignes (CRLF ou LF) par un seul espace. Pour plus d'informations sur les espaces de fin de ligne, consultez la section 3.2.4 du document RFC 7230.

  • Supprimez tous les espaces autour des deux points qui apparaissent après le nom de l'en-tête.

    Par exemple, le fait d'utiliser l'en-tête personnalisé x-goog-acl: private sans supprimer l'espace après le signe deux-points renvoie une erreur 403 Forbidden, car la signature de requête que vous avez calculée ne correspond pas à la signature calculée par Cloud Storage.

Exemple

Si vous disposez de l'ensemble d'en-têtes suivant :

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

Les en-têtes canoniques dans la requête canonique sont construits comme suit :

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

En-têtes canoniques obligatoires

La plupart des en-têtes, tels que content-type, sont ajoutés en fonction des besoins. Cependant, les en-têtes canoniques sont obligatoires dans chaque requête signée :

  • host : URI utilisé pour accéder à Cloud Storage.
  • En-têtes précédés du préfixe x-goog-. Le seul en-tête de ce type qu'il est facultatif d'inclure comme en-tête canonique est x-goog-content-sha256.
  • En-têtes précédés du préfixe x-amz-. Le seul en-tête de ce type qu'il est facultatif d'inclure comme en-tête canonique est x-amz-content-sha256.

En-têtes signés

Un en-tête signé correspond à la partie nom d'un en-tête canonique.

Pour créer la liste des en-têtes signés, convertissez tous les noms d'en-têtes en minuscules, triez-les par code de caractère et séparez-les à l'aide d'un point-virgule (;).

Exemple

Si vous disposez de l'ensemble d'en-têtes suivant :

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

Les en-têtes signés dans la requête canonique sont construits comme suit :

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

Charge utile

  • Si votre requête canonique sert à créer une URL signée, cette valeur doit simplement être la chaîne UNSIGNED-PAYLOAD.

  • Si votre requête canonique est utilisée dans le cadre d'une requête qui fait appel à un en-tête Authorization :

    • Utilisez UNSIGNED-PAYLOAD si vous souhaitez autoriser des charges utiles arbitraires dans le cadre de la requête.

    • Si vous souhaitez n'autoriser qu'une charge utile spécifique, cette valeur doit être un hachage SHA-256 de la charge utile souhaitée encodé en hexadécimal et en minuscules. Si la charge utile doit être vide, utilisez une chaîne vide comme entrée pour la fonction de hachage. Voici un exemple de charge utile hachée (dans ce cas, une charge utile vide) :

      e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Exemple

Voici un exemple de requête canonique correctement formatée, où les sauts de ligne s'affichent en tant que tels et non sous la forme \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

Étape suivante