Boost file integrity with B2sum for secure verification

Tim Koschützki

Co-founder · Berlin, Germany · Show bio

Checksums help detect changed files when compared with trusted expected values. The BLAKE2-based b2sum utility computes and verifies those checksums. A digest alone does not establish who created a file: obtain the expected checksum through a trusted channel, such as an authenticated release or a signed manifest, rather than downloading both file and checksum from an untrusted source.

Why BLAKE2 matters for modern development

BLAKE2 provides significant advantages over legacy hashing algorithms. It is considered cryptographically secure and has been thoroughly reviewed by the cryptographic community. For compliance-critical applications, verify that BLAKE2 meets your regulatory requirements, as some standards may specifically require SHA-2 or SHA-3.

The b2sum implementation excels in:

• Validating software distributions
• Securing backup integrity
• Auditing CI/CD artifact chains
• Detecting changes after file transfers

Install GNU coreutils if b2sum is unavailable. On macOS, Homebrew's coreutils package provides gb2sum; use that name in these examples or explicitly configure the GNU tool directory on PATH. The parallel example also requires GNU Parallel.

# Generate checksum for Ubuntu 24.04 live server iso (noble numbat)
b2sum ubuntu-24.04-live-server-amd64.iso > checksum.b2

# Verify against stored hash
b2sum -c checksum.b2
# ubuntu-24.04-live-server-amd64.iso: OK

The example above records a local baseline; it does not authenticate an Ubuntu release. Use Ubuntu's signed release checksums to verify a downloaded installation image.

CI/CD integration: automated verification

For checked-in release artifacts, generate artifacts.b2 on a trusted machine with b2sum -- dist/app.tar > artifacts.b2, review it, and commit it with the artifact. This workflow then detects mismatches. Do not regenerate the expected manifest immediately before verification, which would make the check accept any replacement. Protect the branch holding trusted manifests:

name: Verify Artifacts
on: [workflow_dispatch]
permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Verify checksums
        run: |
          if ! b2sum -c artifacts.b2; then
            echo "Checksum verification failed" >&2
            exit 1
          fi

Advanced verification patterns

Combine b2sum with other open source tools for enhanced workflows:

Parallel Verification with Error Handling

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

BACKUP_DIR=${1:?Usage: hash-backups.sh BACKUP_DIR}
TMP_DIR=$(mktemp -d .checksums.XXXXXX)
trap 'rm -rf "${TMP_DIR}"' EXIT

find "$BACKUP_DIR" -type f -name "*.tar" -print0 | \
  parallel -0 --jobs 4 --keep-order --halt now,fail=1 b2sum -- {} \
  > "$TMP_DIR/checksums.b2"

test -s "$TMP_DIR/checksums.b2"
mv "$TMP_DIR/checksums.b2" checksums.b2

Run this script with an absolute backup directory, for example bash hash-backups.sh /backups. GNU Parallel groups each job's output, including filenames with whitespace. The temporary manifest replaces checksums.b2 only after every hash succeeds; duplicate basenames in different directories remain distinct. Avoid modifying the backup files while hashing or verifying them.

Python Integrity Checker with Retries

import subprocess
from pathlib import Path

def verify_file(file_path: Path, expected_hash: str, retries: int = 3) -> bool:
    if retries < 1:
        raise ValueError("retries must be positive")
    for attempt in range(retries):
        try:
            result = subprocess.run(
                ['b2sum', '--zero', '--', str(file_path)],
                capture_output=True,
                text=True,
                check=True
            )
            actual_hash = result.stdout.split()[0]
            return actual_hash == expected_hash
        except subprocess.CalledProcessError as e:
            if attempt == retries - 1:
                raise RuntimeError(f"Failed to verify {file_path}") from e
            continue
    return False

Measure performance on your workload

Performance depends on file size, storage, caching, CPU instructions, and implementation. Measure on representative files; do not assume BLAKE2 is always faster than hardware-accelerated SHA-256:

time b2sum -- large-file.bin > /dev/null
time sha256sum -- large-file.bin > /dev/null

Best practices for production use

1. Protect Expected Hashes: Restrict writes to manifests and authenticate their origin.
2. Parallel Processing: Leverage GNU Parallel for handling large datasets.
3. Automated Alerts: Integrate verification failures with your monitoring systems.
4. Version Control: Track checksum files alongside your source code.
5. Error Recovery: Implement retry mechanisms for network- or IO-related failures.
6. Logging: Maintain detailed audit logs of all verification activities.

Additional considerations

Backwards compatibility

Since b2sum is included in GNU coreutils, it is available by default on most Linux distributions. Most existing workflows that rely on traditional checksum utilities can often adopt b2sum with minimal modification. However, ensure that any integrated scripts and applications support BLAKE2 hashes if they enforce specific hash formats.

Hash function comparison

While md5sum remains quick, its known vulnerabilities disqualify it for secure file verification. SHA-256 is also suitable for integrity verification. Benchmark it alongside b2sum rather than choosing based on an assumed speed advantage.

Common pitfalls and troubleshooting

• Ensure files are fully transferred before generating checksums to avoid mismatches.
• Verify the integrity of stored checksum files to prevent issues during verification.
• In CI/CD pipelines, implement clear alerting mechanisms for checksum failures, enabling rapid issue resolution.
• When processing files in parallel, manage temporary storage carefully to prevent race conditions.

For teams handling media assets at scale, Transloadit's 🤖 /file/hash Robot can compute BLAKE2 digests when you add a Step with algorithm: "b2". Its default algorithm is SHA-256. The Robot generates hashes; your application must compare them with trusted expected values to verify integrity.