Verificar arquivos baixados com b2sum e a CLI

Tim Koschützki

Cofundador · Berlim, Alemanha ·

Uma verificação de checksum precisa cobrir o arquivo que você pretende usar. O GNU b2sum --check verifica os nomes de arquivo dentro de um manifesto; nomear esse manifesto como my-app.bin.b2 não faz com que ele verifique my-app.bin. Este passo a passo cria um checksum confiável, copia uma release de exemplo para um diretório de download e usa o Bash para verificar o artefato exato passado a um script.

Usar o formato BLAKE2 correspondente

O GNU b2sum usa o BLAKE2b com um tamanho de digest padrão de 512 bits, exibido como 128 caracteres hexadecimais. O BLAKE2s é uma variante diferente. Escolher b2sum --length=256 produz BLAKE2b-256, não BLAKE2s-256; o resultado também não é a primeira metade de um digest BLAKE2b-512. O algoritmo e o tamanho precisam corresponder ao checksum do publicador. A RFC 7693 descreve como o BLAKE2 incorpora o tamanho de digest solicitado.

Os exemplos abaixo usam o digest BLAKE2b-512 padrão. Um checksum correspondente detecta alterações em relação à sua referência confiável. Ele não identifica o publicador nem torna um download seguro para executar.

Verificar as ferramentas locais

Use Linux com Bash, GNU coreutils (b2sum) e GNU diffutils (cmp). Verifique-os antes de começar:

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

Se algum comando estiver ausente, instale o pacote bash, coreutils ou diffutils da sua distribuição. Este passo a passo foi testado com o GNU coreutils 9.11. Ele usa uma cópia local para demonstrar as etapas do produtor e do consumidor; não configura um serviço de CI/CD hospedado nem faz um download pela rede.

Criar uma release de exemplo

Execute todos os trechos a partir do mesmo diretório pai. Os subshells mantêm as mudanças de diretório locais em cada bloco. A preparação cria b2sum-demo e se recusa a reutilizar um diretório existente, então executá-la novamente não sobrescreverá um experimento anterior.

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

O artefato de exemplo contém texto para facilitar a visualização das alterações. Os mesmos comandos funcionam com arquivos binários e arquivos vazios.

Gerar um manifesto de arquivo único

No lado do produtor, calcule o hash do artefato finalizado a partir do diretório que o contém:

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

Mantenha essa saída inalterada. Ela contém o digest, um espaço, o marcador de modo binário * e o nome de arquivo relativo ./my app.bin, seguido de uma quebra de linha. O GNU documenta esse formato de registro de checksum. O ./ faz parte do nome de arquivo registrado e também impede que um hífen inicial seja tratado como uma opção.

noclobber se recusa a substituir um manifesto existente. Um comando de hash que falhe pode deixar um novo arquivo auxiliar incompleto, porque o shell abre a saída primeiro; não publique essa saída com falha. Gere checksums a partir da release confiável, nunca de um download suspeito só para fazê-lo passar.

Copiar e verificar a release

Copie os dois arquivos para um novo diretório para simular o download deles. Este bloco também se recusa a reutilizar seu diretório 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 manifesto, a raiz é o diretório que contém o artefato. Entre nesse diretório antes de usar o verificador padrão:

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

Saída esperada com o coreutils 9.11 na localidade C; as aspas nos nomes de arquivo podem variar conforme a versão e a localidade:

'./my app.bin': OK

Nomes de arquivo relativos em um manifesto são resolvidos a partir do diretório de trabalho do verificador, não da localização do manifesto. Executar b2sum --check b2sum-demo/downloads/my\ app.bin.b2 a partir do diretório pai procuraria ./my app.bin no diretório pai. Mover o artefato e o manifesto juntos funciona quando você também executa a verificação a partir do novo diretório deles.

A opção --strict faz com que registros malformados falhem. Ela não verifica se o manifesto nomeia o artefato pretendido. Um registro perfeitamente válido para other.bin pode ser bem-sucedido enquanto my app.bin está corrompido ou ausente. Use o script a seguir quando quem faz a chamada solicitar um arquivo específico.

Automação de verificações de integridade

Salve isto como b2sum-demo/verify-integrity.sh. Ele aceita um caminho de artefato e lê o arquivo .b2 adjacente. Seu contrato de manifesto é deliberadamente restrito: exatamente o único registro produzido por b2sum --binary -- './filename', usando o nome base do artefato e o tamanho de digest padrão. Saída no formato com tags, registros extras, espaços em branco editados e grafias de caminho diferentes são rejeitados.

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

O script calcula o hash do arquivo solicitado e compara o registro recém-gerado inteiro, incluindo seu nome de arquivo, com o manifesto confiável. O cmp retorna sucesso somente quando os bytes coincidem. O pipefail do Bash também faz com que um processo de hash com falha faça o pipeline falhar. Espaços e hífens iniciais em nomes de arquivo são suportados.

O próprio script entra no diretório do artefato, então quem faz a chamada pode usar um caminho relativo ou absoluto a partir de outro diretório. A resolução física de diretórios com cd -P preserva o significado de caminhos que contêm symlinks seguidos de ... O script não grava nem o artefato nem o manifesto dele. Mantenha ambos inalterados durante a verificação e o uso posterior; este script não bloqueia arquivos contra alterações concorrentes.

Interromper o trabalho seguinte quando a verificação falhar

Execute o verificador pelo Bash e condicione o próximo comando ao status de saída dele:

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

Uma execução bem-sucedida imprime:

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

Para testar uma falha, altere apenas a cópia baixada descartável:

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

Isso imprime Verification failed: b2sum-demo/downloads/my app.bin na saída de erro padrão e termina com status 1. Em uma tarefa de CI/CD, a etapa de consumo ou de implantação também deve depender de uma verificação bem-sucedida; um comando de shell posterior bem-sucedido não deve ocultar a falha.

Solução de problemas comuns

O script rejeita um manifesto que o b2sum --check aceita: verifique o nome de arquivo e o formato dele. Este script exige um registro em modo binário com ./basename, incluindo a quebra de linha final. Para um manifesto de vários arquivos de um publicador, siga o layout de diretórios documentado e confira quais arquivos ele cobre antes de usar o verificador padrão.
Os bytes são diferentes: verifique se você baixou a release pretendida. Baixe novamente da fonte confiável e investigue divergências repetidas. Mudanças de fim de linha em texto também alteram um hash.
Um arquivo está ausente ou ilegível: verifique tanto o caminho do artefato quanto o arquivo auxiliar .b2 dele, além das permissões do diretório. Um artefato vazio é válido quando seu checksum corresponde; um manifesto vazio é inválido.
Um comando está ausente: o verificador precisa tanto do GNU b2sum quanto do cmp no seu caminho de execução. Uma falha de hash ou de comparação retorna um status diferente de zero.

Manter confiável o checksum esperado

Obtenha o checksum esperado por um canal de release em que você confie, ou verifique um manifesto assinado usando uma chave do publicador cuja identidade você tenha estabelecido de forma independente. Um invasor que consiga substituir tanto o artefato quanto o checksum dele pode fazer esta verificação passar. Baixar ambos do mesmo local comprometido não oferece nenhuma garantia de autenticidade.

Nossa cópia local demonstra a verificação de integridade após a transferência. Gerar um novo checksum a partir dos bytes baixados apenas descreveria o que chegou. Mantenha o checksum confiável do produtor como referência e verifique antes de consumir o artefato.