Vérifier des fichiers téléchargés avec b2sum et la CLI

Tim Koschützki

Cofondateur · Berlin, Allemagne · Afficher la bio

Une vérification de somme de contrôle doit porter sur le fichier que vous comptez utiliser. GNU b2sum --check vérifie les noms de fichiers contenus dans un manifeste ; donner à ce manifeste le nom my-app.bin.b2 ne lui fait pas vérifier my-app.bin. Ce tutoriel crée une somme de contrôle de confiance, copie une version d’exemple dans un répertoire de téléchargement et utilise Bash pour vérifier l’artefact exact transmis à un script.

Utiliser le format BLAKE2 correspondant

GNU b2sum⁠ utilise BLAKE2b avec une longueur d’empreinte par défaut de 512 bits, affichée sous forme de 128 caractères hexadécimaux. BLAKE2s est une variante différente. Choisir b2sum --length=256 produit du BLAKE2b-256, et non du BLAKE2s-256 ; ce n’est pas non plus la première moitié d’une empreinte BLAKE2b-512. L’algorithme et la longueur doivent correspondre à la somme de contrôle de l’éditeur. La RFC 7693⁠ décrit comment BLAKE2 intègre la longueur d’empreinte demandée.

Les exemples ci-dessous utilisent l’empreinte BLAKE2b-512 par défaut. Une somme de contrôle concordante détecte les modifications par rapport à votre référence de confiance. Elle n’identifie pas l’éditeur et ne rend pas un téléchargement sûr à exécuter.

Vérifier les outils locaux

Utilisez Linux avec Bash, GNU coreutils (b2sum) et GNU diffutils (cmp). Vérifiez leur présence avant de commencer :

bash --version && b2sum --version && cmp --version

Si une commande est absente, installez le paquet bash, coreutils ou diffutils de votre distribution. Ce tutoriel a été testé avec GNU coreutils 9.11. Il utilise une copie locale pour illustrer les étapes du producteur et du consommateur ; il ne configure pas de service CI/CD hébergé et n’effectue aucun téléchargement réseau.

Créer une version d’exemple

Exécutez chaque extrait depuis le même répertoire parent. Les sous-shells limitent les changements de répertoire à chaque bloc. La configuration crée b2sum-demo et refuse de réutiliser un répertoire existant : relancer ce bloc n’écrasera donc pas une expérience précédente.

(
  set -eu
  mkdir -- b2sum-demo
  cd -- b2sum-demo
  mkdir -- release
  printf 'example release\n' > 'release/my app.bin'
)

L’artefact d’exemple contient du texte pour que les modifications soient faciles à repérer. Les mêmes commandes fonctionnent avec des fichiers binaires et des fichiers vides.

Générer un manifeste pour un seul fichier

Côté producteur, calculez l’empreinte de l’artefact final depuis le répertoire qui le contient :

(
  set -eu
  set -o noclobber
  cd -- b2sum-demo/release
  b2sum --binary -- './my app.bin' > './my app.bin.b2'
)

Conservez cette sortie telle quelle. Elle contient l’empreinte, un espace, le marqueur de mode binaire * et le nom de fichier relatif ./my app.bin, suivis d’un saut de ligne. GNU documente ce format d’enregistrement de somme de contrôle⁠. Le ./ fait partie du nom de fichier enregistré et empêche aussi qu’un tiret initial soit interprété comme une option.

noclobber refuse de remplacer un manifeste existant. Une commande de hachage qui échoue peut laisser un nouveau fichier annexe incomplet, car le shell ouvre d’abord le fichier de sortie ; ne publiez pas cette sortie en échec. Générez les sommes de contrôle à partir de la version de confiance, jamais à partir d’un téléchargement suspect dans le seul but de le faire passer.

Copier et vérifier la version

Copiez les deux fichiers dans un nouveau répertoire pour simuler leur téléchargement. Ce bloc refuse lui aussi de réutiliser son répertoire de destination :

(
  set -eu
  mkdir -- b2sum-demo/downloads
  cp -- 'b2sum-demo/release/my app.bin' 'b2sum-demo/release/my app.bin.b2' b2sum-demo/downloads/
)

Pour ce manifeste, la racine est le répertoire qui contient l’artefact. Placez-vous dans ce répertoire avant d’utiliser le vérificateur standard :

(
  cd -- b2sum-demo/downloads &&
    b2sum --check --strict -- './my app.bin.b2'
)

Sortie attendue avec coreutils 9.11 dans la locale C ; la mise entre guillemets des noms de fichiers peut varier selon la version et la locale :

'./my app.bin': OK

Les noms de fichiers relatifs d’un manifeste sont résolus depuis le répertoire de travail du vérificateur, et non depuis l’emplacement du manifeste. Exécuter b2sum --check b2sum-demo/downloads/my\ app.bin.b2 depuis le répertoire parent chercherait ./my app.bin dans le parent. Déplacer l’artefact et le manifeste ensemble fonctionne si vous lancez aussi la vérification depuis leur nouveau répertoire.

L’option --strict⁠ fait échouer les enregistrements mal formés. Elle ne vérifie pas que le manifeste désigne l’artefact que vous visez. Un enregistrement parfaitement valide pour other.bin peut réussir alors que my app.bin est corrompu ou absent. Utilisez le script suivant lorsqu’un appelant demande un fichier précis.

Automatiser les contrôles d’intégrité

Enregistrez ce script sous b2sum-demo/verify-integrity.sh. Il accepte un seul chemin d’artefact et lit le fichier .b2 adjacent. Son contrat de manifeste est volontairement restreint : exactement l’unique enregistrement produit par b2sum --binary -- './filename', avec le nom de base de l’artefact et la longueur d’empreinte par défaut. Les sorties balisées, les enregistrements supplémentaires, les espaces modifiés et les chemins écrits différemment sont rejetés.

#!/usr/bin/env bash
set -euo pipefail

if (( $# != 1 )) || [[ -z $1 ]]; then
  printf 'Usage: %s <artifact>\n' "$0" >&2
  exit 2
fi

artifact=$1
[[ $artifact == /* ]] || artifact="./$artifact"
if [[ ! -f $artifact || ! -f $artifact.b2 ]]; then
  printf 'Artifact or manifest missing: %s\n' "$1" >&2
  exit 1
fi

cd -P -- "${artifact%/*}/"
name=${artifact##*/}
if b2sum --binary -- "./$name" | cmp --silent -- "./$name.b2" -; then
  printf 'Verified: %s\n' "$1"
else
  printf 'Verification failed: %s\n' "$1" >&2
  exit 1
fi

Le script calcule l’empreinte du fichier demandé et compare l’intégralité de l’enregistrement nouvellement généré, y compris son nom de fichier, avec le manifeste de confiance. cmp⁠ ne renvoie un succès que si les octets sont identiques. Dans Bash, pipefail⁠ fait aussi échouer le pipeline lorsque le processus de hachage échoue. Les espaces et les tirets initiaux dans les noms de fichiers sont pris en charge.

Le script se place lui-même dans le répertoire de l’artefact : les appelants peuvent donc utiliser un chemin relatif ou absolu depuis un autre répertoire. La résolution physique des répertoires avec cd -P⁠ préserve la signification des chemins contenant des liens symboliques suivis de ... Le script n’écrit ni dans l’artefact ni dans son manifeste. Conservez les deux inchangés pendant la vérification et l’utilisation qui suit ; ce script ne verrouille pas les fichiers contre les modifications concurrentes.

Interrompre la suite en cas d’échec de la vérification

Exécutez le vérificateur avec Bash et conditionnez la commande suivante à son code de sortie :

bash b2sum-demo/verify-integrity.sh 'b2sum-demo/downloads/my app.bin' &&
  printf 'Ready to use the verified artifact\n'

Une exécution réussie affiche :

Verified: b2sum-demo/downloads/my app.bin
Ready to use the verified artifact

Pour provoquer un échec, modifiez uniquement la copie téléchargée jetable :

printf 'changed\n' >> 'b2sum-demo/downloads/my app.bin' &&
  bash b2sum-demo/verify-integrity.sh 'b2sum-demo/downloads/my app.bin'

Cela affiche Verification failed: b2sum-demo/downloads/my app.bin sur la sortie d’erreur standard et se termine avec le code de sortie 1. Dans une tâche CI/CD, l’étape de consommation ou de déploiement doit de même dépendre de la réussite de la vérification ; une commande shell ultérieure réussie ne doit pas masquer l’échec.

Résoudre les problèmes courants

• Le script rejette un manifeste que b2sum --check accepte : vérifiez son nom de fichier et son format. Ce script exige un seul enregistrement en mode binaire avec ./basename, y compris le saut de ligne final. Pour le manifeste multifichier d’un éditeur, respectez l’arborescence de répertoires documentée et examinez les fichiers qu’il couvre avant d’utiliser le vérificateur standard.
• Les octets diffèrent : vérifiez que vous avez téléchargé la version voulue. Téléchargez-la de nouveau depuis la source de confiance et examinez les incohérences répétées. Les changements de fin de ligne dans un texte modifient aussi une empreinte.
• Un fichier est absent ou illisible : vérifiez à la fois le chemin de l’artefact et son fichier annexe .b2, ainsi que les permissions des répertoires. Un artefact vide est valide si sa somme de contrôle correspond ; un manifeste vide est invalide.
• Une commande est absente : le vérificateur a besoin des outils GNU b2sum et cmp dans son chemin d’exécution. Un échec du hachage ou de la comparaison renvoie un code de sortie non nul.

Garantir la fiabilité de la somme de contrôle attendue

Obtenez la somme de contrôle attendue par un canal de publication de confiance, ou vérifiez un manifeste signé à l’aide d’une clé d’éditeur dont vous avez établi l’identité de manière indépendante. Un attaquant capable de remplacer à la fois l’artefact et sa somme de contrôle peut faire réussir cette vérification. Télécharger les deux depuis le même emplacement compromis n’offre aucune garantie d’authenticité.

Notre copie locale illustre la vérification d’intégrité après transfert. Générer une nouvelle somme de contrôle à partir des octets téléchargés ne ferait que décrire ce qui est arrivé. Conservez la somme de contrôle de confiance du producteur comme référence et vérifiez l’artefact avant de l’utiliser.