Verifique downloads com cURL e b2sum

Tim Koschützki

Cofundador · Berlim, Alemanha ·

Baixe para um arquivo temporário, compare o checksum BLAKE2b dele com o valor de um publicador confiável e crie o destino somente quando os bytes conferirem. O script Bash abaixo combina cURL e b2sum sem substituir um arquivo existente e depois demonstra o fluxo de trabalho com o checksum real de uma versão publicada.

Obtenha o checksum esperado com o publicador

Executar b2sum em um download informa o checksum atual dele. Isso não informa qual deveria ser o checksum. Obtenha o valor esperado para a versão, a arquitetura e o nome de arquivo exatos com um publicador em quem você confia, como a página oficial de versões dele via HTTPS ou um manifesto de checksums com assinatura verificada. Um checksum copiado do mesmo espelho não confiável do download não acrescenta nenhuma referência confiável.

GNU b2sum usa por padrão BLAKE2b-512: 64 bytes de digest escritos como 128 caracteres hexadecimais. Este script exige esse formato. BLAKE2s, um digest BLAKE2b mais curto e SHA-256 não são intercambiáveis com ele. Se o publicador fornecer apenas SHA-256, use um fluxo de trabalho de verificação com SHA-256 em vez de inventar uma referência BLAKE2b calculando você mesmo o hash do arquivo baixado.

Confira os pré-requisitos no Linux

Use uma máquina Linux com GNU Bash, cURL com suporte a HTTPS e GNU Coreutils já instalados. O Coreutils fornece b2sum, mktemp, ln e rm. Este exemplo foi testado com Bash 5.3.15, cURL 8.22.0 e Coreutils 9.11; não é uma receita para macOS ou PowerShell. Confira suas ferramentas:

bash --version && curl --version && b2sum --version

Execute em um diretório que você controla, em um sistema de arquivos com suporte a hard links. O destino é um nome de arquivo nesse diretório, não um caminho para outro diretório. Espaços e hifens iniciais são permitidos; barras, quebras de linha, . e .. são rejeitados. O arquivo é salvo com permissões de leitura/gravação apenas para o dono, e um arquivo, diretório ou link simbólico existente não é alterado.

Salve o script de verificação completo

Salve este conteúdo como um novo arquivo chamado verify-download.sh. Execute-o com bash; não cole o script diretamente no seu shell interativo. Em caso de erro, ele encerra de propósito o próprio processo do programa salvo, o que fecharia o shell em que você o colou.

#!/usr/bin/env bash
set -euo pipefail
export LC_ALL=C
umask 077

if (( $# != 3 )); then
  printf 'Usage: bash verify-download.sh HTTPS_URL BLAKE2B_512_HEX FILENAME\n' >&2
  exit 2
fi

url=$1
expected=${2,,}
filename=$3
if [[ ! $expected =~ ^[0-9a-f]{128}$ ]]; then
  printf 'Expected checksum must contain exactly 128 hexadecimal characters.\n' >&2
  exit 2
fi
if [[ $url != https://* ]]; then
  printf 'The download URL must use HTTPS.\n' >&2
  exit 2
fi
if [[ -z $filename || $filename == */* || $filename == . || $filename == .. ||
      $filename == *$'\n'* || $filename == *$'\r'* ]]; then
  printf 'Use a filename without slashes or line breaks.\n' >&2
  exit 2
fi

destination="./$filename"
if [[ -e $destination || -L $destination ]]; then
  printf 'Destination already exists: %s\n' "$destination" >&2
  exit 1
fi

temporary=$(mktemp -d ./.b2-download.XXXXXXXX)
trap 'rm -rf -- "$temporary"' EXIT
if ! curl -q -fsSL --globoff --proto '=https' --proto-redir '=https' \
    --max-redirs 5 --connect-timeout 10 --max-time 300 \
    --output "$temporary/payload" --url "$url"; then
  printf 'Download failed; no file saved.\n' >&2
  exit 1
fi
if ! printf '%s  %s\n' "$expected" "$temporary/payload" |
    b2sum --check --strict --status -; then
  printf 'Checksum mismatch or unreadable download; no file saved.\n' >&2
  exit 1
fi
if ! ln -T -- "$temporary/payload" "$destination"; then
  printf 'Destination exists or cannot be created; no file saved.\n' >&2
  exit 1
fi
printf 'Verified and saved: %s\n' "$destination"

A entrada de checksum usa o formato do GNU: o digest, dois espaços e depois o nome do arquivo. O script monta esse registro para o próprio payload temporário, em vez de deixar um manifesto baixado escolher caminhos locais. --strict rejeita registros de checksum malformados, enquanto a verificação de argumentos impõe o comprimento de digest de 512 bits antes de qualquer transferência.

A etapa final usa um hard link, não mv: o GNU ln -T sem --force falha se o destino existir, inclusive se ele aparecer depois da verificação inicial. Manter o arquivo temporário no diretório de destino evita um link entre sistemas de arquivos diferentes. O trap de saída remove o diretório temporário privado tanto em caso de sucesso normal quanto de falha. Um encerramento abrupto ou uma queda de energia pode deixá-lo para trás; isto não é um sistema de recuperação após travamentos.

Baixe uma versão com checksum BLAKE2b publicado

A página de download do Arch Linux aponta para o manifesto BLAKE2b dele. Para um exemplo reproduzível, use o tarball de bootstrap de 1º de setembro de 2026, não uma URL “latest” que muda com o tempo. Trata-se do download de um tarball de aproximadamente 121 MiB, não de uma instrução para instalar, extrair ou executar essa versão.

Leia o manifesto versionado do publicador via HTTPS:

curl -q -fsSL --proto '=https' --proto-redir '=https' --max-time 30 \
  --url 'https://archive.archlinux.org/iso/2026.09.01/b2sums.txt'

Encontre a linha que termina em archlinux-bootstrap-2026.09.01-x86_64.tar.zst. Copie o primeiro campo dela, não o checksum da ISO nem um checksum que você gerou localmente. A chamada abaixo usa esse valor publicado de 128 caracteres e salva o tarball correspondente:

(
  url='https://archive.archlinux.org/iso/2026.09.01/archlinux-bootstrap-2026.09.01-x86_64.tar.zst'
  expected='3893c310ec7d52fd5dee7eec51bc9d611200a5636985c8b627871d1ee85d83821284bcb9a6843afa011a6607ee9ce3202f7e7f5f168f29a07541c0836eeaefd0'
  bash verify-download.sh "$url" "$expected" archlinux-bootstrap-2026.09.01-x86_64.tar.zst
)

Em caso de sucesso, o programa salvo imprime:

Verified and saved: ./archlinux-bootstrap-2026.09.01-x86_64.tar.zst

Só então o destino é criado. Um arquivo vazio também é válido se o checksum esperado dele conferir; o script verifica bytes, não se eles formam um pacote de arquivos útil.

Interprete as falhas antes de usar o arquivo

Checksum divergente: nenhum destino é criado e o download temporário é removido. Confira de novo a versão, a arquitetura e o valor esperado confiável. Não “corrija” a divergência usando o checksum do próprio download como valor esperado.
Erro de HTTP, TLS ou transferência incompleta: o cURL falha, o script retorna um status de saída diferente de zero e qualquer payload parcial é removido. A transferência tem um prazo de cinco minutos; ajuste-o de forma deliberada para downloads maiores ou conexões mais lentas.
Destino existente: o script retorna um status de saída diferente de zero e preserva os bytes do destino. Escolha outro nome de arquivo em vez de apagar um download anterior sem verificá-lo.
Falha na publicação: uma operação de hard link sem suporte ou um destino criado durante a transferência impede o sucesso. A verificação sozinha não significa que o arquivo foi salvo.

As opções do cURL tornam visíveis as falhas de transferência: -f trata a maioria das respostas de erro HTTP como falhas, -sS oculta o medidor de progresso, mas mantém os diagnósticos, e -L segue redirecionamentos. Tanto a URL inicial quanto os redirecionamentos ficam restritos a HTTPS, com no máximo cinco redirecionamentos. -q vem primeiro para que uma configuração local do curl não altere silenciosamente as opções deste comando. Redirecionamentos somente via HTTPS ainda podem mudar de host; o checksum confiável continua sendo a referência no nível dos bytes.

Entenda o que a correspondência entre checksums comprova

Uma correspondência estabelece a concordância com o digest esperado, não que o arquivo seja inofensivo nem que uma pessoa específica o tenha publicado. Neste exemplo, a base de confiança é o site do publicador Arch Linux via HTTPS. Se um invasor controlar tanto o artefato quanto essa fonte de checksum, ele poderá substituir os dois. Para autenticar o publicador além dessa base de confiança, siga as instruções de verificação de assinatura do publicador e confirme separadamente a identidade da chave de assinatura.

O script também pressupõe que outros processos não podem modificar de forma maliciosa seu diretório de trabalho nem o arquivo salvo. Ele é uma verificação local de download, não uma sandbox nem uma garantia de que os bytes continuem inalterados após a verificação. Em um fluxo de trabalho de catalogação de mídia, guarde o checksum esperado junto com a fonte e as informações da versão, para que uma comparação posterior tenha uma referência que você consiga explicar.