Hachages et ETags : bonnes pratiques

Cloud Storage vous encourage à valider les données que vous transférez vers et depuis vos buckets. Cette page décrit les bonnes pratiques à suivre pour effectuer des validations à l'aide de sommes de contrôle CRC32C ou MD5.

Se protéger contre la corruption des données à l'aide de hachages

Lorsque les données sont transférées depuis ou vers le cloud, elles peuvent être corrompues pour de multiples raisons :

  • Erreurs de mémoire sur les ordinateurs clients ou serveurs, ou sur les routeurs le long du chemin
  • Bugs logiciels (p.ex., dans une bibliothèque utilisée par les clients)
  • Modifications apportées au fichier source alors qu'une importation est en cours sur une période prolongée

Cloud Storage accepte deux types de hachages que vous pouvez utiliser pour vérifier l'intégrité de vos données : CRC32C et MD5. CRC32C est la méthode de validation recommandée pour effectuer des vérifications d'intégrité. Les clients qui préfèrent MD5 peuvent utiliser ce hachage, mais les hachages MD5 ne sont pas compatibles avec les objets composites ou les objets créés à partir d'une importation en plusieurs parties avec l'API XML.

CRC32C

Tous les objets Cloud Storage ont un hachage de type CRC32C. Les bibliothèques permettant de calculer un hachage CRC32C incluent :

Le CRC32C encodé en base64 est classé par ordre d'octets en mode big-endian.

MD5

Cloud Storage accepte le hachage MD5 pour les objets qui répondent aux critères suivants :

Ce hachage ne s'applique qu'à un objet complet. Il ne peut donc pas être utilisé pour vérifier l'intégrité des téléchargements partiels en cas d'exécution d'une plage GET.

ETags

L'en-tête ETag d'un objet renvoie la valeur MD5 de l'objet si toutes les conditions suivantes sont remplies :

Dans tous les autres cas, les utilisateurs ne doivent faire aucune hypothèse concernant la valeur utilisée dans un ETag, sauf qu'elle change chaque fois que les données ou métadonnées sous-jacentes sont modifiées, conformément à la spécification.

Le même objet peut avoir une valeur ETag différente lorsqu'elle est demandée par l'API XML plutôt que par l'API JSON.

Validation

Une vérification de l'intégrité du téléchargement peut être effectuée en hachant les données téléchargées à la volée et en comparant les résultats aux hachages fournis par le serveur. Vous devez supprimer les données téléchargées comportant des valeurs de hachage incorrectes et appliquer une logique de répétition des tentatives pour éviter des boucles à l'infini potentiellement coûteuses.

Cloud Storage procède à une validation côté serveur dans les cas suivants :

  • Lorsque vous effectuez une requête de copie ou de réécriture dans Cloud Storage.

  • Lorsque vous fournissez le hachage MD5 ou CRC32C attendu d'un objet dans une requête d'importation. Cloud Storage ne crée l'objet que si le hachage que vous fournissez correspond à la valeur calculée par Cloud Storage. Si ce n'est pas le cas, la requête est rejetée avec une erreur BadRequestException: 400.

Les utilisateurs peuvent également choisir d'effectuer une validation côté client de leurs importations. Ils doivent alors envoyer une requête de métadonnées pour l'objet importé, comparer la valeur de hachage indiquée et supprimer l'objet en cas de non-concordance. Cette méthode est utile si le hachage MD5 ou CRC32C de l'objet n'est pas connu au début de l'importation. Pour éviter les conditions de concurrence où des processus indépendants suppriment ou remplacent les données les uns des autres, utilisez les générations d'objet et conditions préalables.

Dans le cas d'importations composites parallèles, les utilisateurs doivent effectuer un contrôle d'intégrité pour chaque importation de composants, puis utiliser les conditions préalables de composant avec leurs requêtes de composition pour se protéger d'une condition de concurrence. La composition d'objets n'offrant aucune validation MD5 côté serveur, les utilisateurs qui souhaitent effectuer un contrôle d'intégrité de bout en bout doivent appliquer la validation côté client au nouvel objet composite.

API XML

Dans l'API XML, les hachages MD5 et CRC32C encodés en base64 sont exposés et acceptés via l'en-tête x-goog-hash. Auparavant, les MD5 étaient utilisés en tant qu'ETag d'objets, mais les utilisateurs doivent éviter cette situation car certains objets utilisent des valeurs ETag opaques qui n'offrent aucune garantie en dehors de leur changement à chaque modification de l'objet.

La validation de l'importation côté serveur peut être effectuée en fournissant des hachages calculés localement via l'en-tête de requête x-goog-hash. De plus, le MD5 peut être fourni en utilisant l'en-tête Content-MD5 HTTP standard (reportez-vous à la spécification).

API JSON

Dans l'API JSON, les propriétés md5Hash et crc32c des ressources d'objets contiennent respectivement des hachages MD5 et CRC32C encodés en base64. La provision de l'une ou l'autre des propriétés de métadonnées est facultative. Fournir l'une des deux propriétés dans le cadre d'une importation avec reprise ou d'une importation en plusieurs parties avec l'API JSON déclenche une validation côté serveur pour le nouvel objet. Si, pour l'une des propriétés, Cloud Storage calcule une valeur qui ne correspond pas à la valeur fournie, l'objet n'est pas créé. Si les propriétés ne sont pas fournies lors d'une importation, Cloud Storage calcule les valeurs et les écrit dans les métadonnées de l'objet.

Google Cloud CLI

Pour la Google Cloud CLI, les données copiées vers ou depuis un bucket Cloud Storage sont validées. Cela s'applique aux commandes cp, mv et rsync. Si la somme de contrôle des données sources ne correspond pas à celle des données de destination, la gcloud CLI supprime la copie non valide et affiche un message d'avertissement. Ceci arrive très rarement. Vous pouvez retenter l'opération si cela se produit.

Cette validation automatique a lieu une fois l'objet lui-même finalisé. Les objets non valides sont donc visibles pendant 1 à 3 secondes avant d'être identifiés et supprimés. De plus, la gcloud CLI peut être interrompue après la fin de l'importation, mais avant qu'il effectue la validation, laissant l'objet non valide en place. Ces problèmes peuvent être évités lors de l'importation de fichiers uniques dans Cloud Storage à l'aide de la validation côté serveur, qui se produit lorsque vous utilisez l'option --content-md5=MD5.

Étapes suivantes