Verifica archivos descargados con b2sum y la CLI

Tim Koschützki

Cofundador · Berlín, Alemania ·

La comprobación de una suma de verificación debe abarcar el archivo que pretendes usar. GNU b2sum --check comprueba los nombres de archivo que figuran en un manifiesto; llamar a ese manifiesto my-app.bin.b2 no hace que compruebe my-app.bin. Este tutorial crea una suma de verificación fiable, copia una versión de ejemplo a un directorio de descargas y usa Bash para verificar el artefacto exacto que se pasa a un script.

Usa el formato BLAKE2 correspondiente

GNU b2sum usa BLAKE2b con una longitud de resumen predeterminada de 512 bits, que se muestra como 128 caracteres hexadecimales. BLAKE2s es una variante distinta. Elegir b2sum --length=256 produce BLAKE2b-256, no BLAKE2s-256; tampoco es la primera mitad de un resumen BLAKE2b-512. El algoritmo y la longitud deben coincidir con la suma de verificación del distribuidor. RFC 7693 describe cómo BLAKE2 incorpora la longitud de resumen solicitada.

Los ejemplos siguientes usan el resumen BLAKE2b-512 predeterminado. Una suma de verificación coincidente detecta cambios respecto a tu referencia fiable. No identifica al distribuidor ni hace que una descarga sea segura de ejecutar.

Comprueba las herramientas locales

Usa Linux con Bash, GNU coreutils (b2sum) y GNU diffutils (cmp). Compruébalos antes de empezar:

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

Si falta un comando, instala el paquete bash, coreutils o diffutils de tu distribución. Este tutorial se probó con GNU coreutils 9.11. Usa una copia local para demostrar los pasos del productor y del consumidor; no configura un servicio de CI/CD alojado ni realiza una descarga por la red.

Crea una versión de ejemplo

Ejecuta cada fragmento desde el mismo directorio padre. Los subshells mantienen los cambios de directorio dentro de cada bloque. La preparación crea b2sum-demo y se niega a reutilizar un directorio existente, por lo que volver a ejecutarla no sobrescribirá un experimento anterior.

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

El artefacto de ejemplo contiene texto para que los cambios sean fáciles de ver. Los mismos comandos funcionan con archivos binarios y archivos vacíos.

Genera un manifiesto de un solo archivo

Del lado del productor, calcula el hash del artefacto terminado desde el directorio que lo contiene:

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

Conserva esta salida sin cambios. Contiene el resumen, un espacio, el marcador de modo binario * y el nombre de archivo relativo ./my app.bin, seguidos de un salto de línea. GNU documenta este formato de registro de suma de verificación. El ./ forma parte del nombre de archivo registrado y también evita que un guion inicial se interprete como una opción.

noclobber se niega a reemplazar un manifiesto existente. Un comando de hash fallido puede dejar un nuevo archivo auxiliar incompleto porque el shell abre primero la salida; no publiques esa salida fallida. Genera las sumas de verificación a partir de la versión fiable, nunca a partir de una descarga sospechosa solo para que pase la comprobación.

Copia y comprueba la versión

Copia ambos archivos a un directorio nuevo para simular su descarga. Este bloque también se niega a reutilizar su directorio de destino:

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

Para este manifiesto, la raíz es el directorio que contiene el artefacto. Cambia a ese directorio antes de usar el verificador estándar:

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

Salida esperada con coreutils 9.11 en la configuración regional C; las comillas de los nombres de archivo pueden variar según la versión y la configuración regional:

'./my app.bin': OK

Los nombres de archivo relativos de un manifiesto se resuelven desde el directorio de trabajo del verificador, no desde la ubicación del manifiesto. Ejecutar b2sum --check b2sum-demo/downloads/my\ app.bin.b2 desde el directorio padre buscaría ./my app.bin en ese directorio padre. Mover juntos el artefacto y el manifiesto funciona si también ejecutas la comprobación desde su nuevo directorio.

La opción --strict hace que los registros con formato incorrecto provoquen un fallo. No comprueba que el manifiesto nombre el artefacto que pretendes usar. Un registro perfectamente válido para other.bin puede pasar la comprobación aunque my app.bin esté dañado o no exista. Usa el siguiente script cuando quien lo invoque solicite un archivo específico.

Automatización de las comprobaciones de integridad

Guarda esto como b2sum-demo/verify-integrity.sh. Acepta la ruta de un artefacto y lee el archivo .b2 adyacente. Su contrato de formato para el manifiesto es intencionadamente estricto: exactamente el único registro producido por b2sum --binary -- './filename', con el nombre base del artefacto y la longitud de resumen predeterminada. Se rechazan la salida etiquetada, los registros adicionales, los espacios en blanco modificados y las rutas escritas de otra manera.

#!/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

El script calcula el hash del archivo solicitado y compara todo el registro recién generado, incluido su nombre de archivo, con el manifiesto fiable. cmp indica éxito solo cuando los bytes coinciden. La opción de Bash pipefail también hace que un proceso de cálculo de hash fallido provoque el fallo del pipeline. Se admiten espacios y guiones iniciales en los nombres de archivo.

El propio script cambia al directorio del artefacto, por lo que quienes lo invoquen pueden usar una ruta relativa o absoluta desde otro directorio. La resolución física del directorio con cd -P conserva el significado de las rutas que contienen enlaces simbólicos seguidos de ... No escribe ni en el artefacto ni en su manifiesto. Mantén ambos sin cambios durante la verificación y el uso posterior; este script no bloquea los archivos contra cambios simultáneos.

Detén el trabajo posterior cuando falle la verificación

Ejecuta el verificador mediante Bash y condiciona el siguiente comando a su estado de salida:

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

Una ejecución correcta muestra:

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

Para probar un fallo, cambia solo la copia descargada desechable:

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

Esto muestra Verification failed: b2sum-demo/downloads/my app.bin en la salida de error estándar y termina con el estado 1. En una tarea de CI/CD, el paso que consume el artefacto o lo despliega también debe depender de una verificación correcta; un comando posterior del shell que se ejecute correctamente no debe ocultar el fallo.

Resolución de problemas comunes

El script rechaza un manifiesto que b2sum --check acepta: comprueba su nombre de archivo y su formato. Este script requiere un registro en modo binario con ./basename, incluido el salto de línea final. Para un manifiesto de varios archivos de un distribuidor, sigue su estructura de directorios documentada e inspecciona qué archivos abarca antes de usar el verificador estándar.
Los bytes difieren: comprueba que hayas descargado la versión deseada. Vuelve a descargarla desde la fuente fiable e investiga las discrepancias repetidas. Los cambios en los finales de línea del texto también cambian el hash.
Falta un archivo o no se puede leer: comprueba tanto la ruta del artefacto como su archivo auxiliar .b2, además de los permisos del directorio. Un artefacto vacío es válido si su suma de verificación coincide; un manifiesto vacío no es válido.
Falta un comando: el verificador necesita tanto GNU b2sum como cmp en su ruta de ejecución. Un fallo en el cálculo del hash o en la comparación devuelve un estado distinto de cero.

Mantén fiable la suma de verificación esperada

Obtén la suma de verificación esperada a través de un canal de distribución en el que confíes, o verifica un manifiesto firmado usando una clave del distribuidor cuya identidad hayas establecido de forma independiente. Un atacante que pueda reemplazar tanto el artefacto como su suma de verificación puede hacer que esta comprobación pase. Descargar ambos desde la misma ubicación comprometida no ofrece ninguna garantía de autenticidad.

Nuestra copia local demuestra la verificación de integridad después de la transferencia. Generar una nueva suma de verificación a partir de los bytes descargados solo describiría lo que llegó. Conserva la suma de verificación fiable del productor como referencia y verifica el artefacto antes de consumirlo.