Heruntergeladene Dateien mit b2sum und der CLI verifizieren

Tim Koschützki

Mitgründer · Berlin, Deutschland ·

Eine Prüfsummenprüfung muss die Datei erfassen, die Sie verwenden möchten. GNU b2sum --check prüft die Dateinamen im Manifest. Wenn Sie dieses Manifest my-app.bin.b2 nennen, wird dadurch nicht my-app.bin geprüft. Diese Anleitung erstellt eine vertrauenswürdige Prüfsumme, kopiert eine Beispielversion in ein Downloadverzeichnis und verifiziert mit Bash genau das Artefakt, das einem Skript übergeben wird.

Das passende BLAKE2-Format verwenden

GNU b2sum verwendet BLAKE2b mit einer Standard-Hashlänge von 512 Bit, ausgegeben als 128 hexadezimale Zeichen. BLAKE2s ist eine andere Variante. Die Wahl von b2sum --length=256 erzeugt BLAKE2b-256, nicht BLAKE2s-256. Das Ergebnis ist auch nicht die erste Hälfte eines BLAKE2b-512-Hashwerts. Algorithmus und Länge müssen zur Prüfsumme des Herausgebers passen. RFC 7693 beschreibt, wie BLAKE2 die angeforderte Hashlänge berücksichtigt.

Die folgenden Beispiele verwenden den standardmäßigen BLAKE2b-512-Hashwert. Eine übereinstimmende Prüfsumme erkennt Änderungen gegenüber Ihrer vertrauenswürdigen Referenz. Sie identifiziert weder den Herausgeber noch macht sie die Ausführung einer heruntergeladenen Datei sicher.

Die lokalen Werkzeuge prüfen

Verwenden Sie Linux mit Bash, GNU coreutils (b2sum) und GNU diffutils (cmp). Prüfen Sie diese vor dem Start:

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

Falls ein Befehl fehlt, installieren Sie das Paket bash, coreutils oder diffutils Ihrer Distribution. Diese Anleitung wurde mit GNU coreutils 9.11 getestet. Sie verwendet eine lokale Kopie, um die Schritte auf Erzeuger- und Empfängerseite zu demonstrieren. Sie konfiguriert keinen gehosteten CI/CD-Dienst und führt keinen Download über das Netzwerk durch.

Eine Beispielversion erstellen

Führen Sie alle Codeabschnitte aus demselben übergeordneten Verzeichnis aus. Die Subshells halten Verzeichniswechsel auf den jeweiligen Block beschränkt. Die Einrichtung erstellt b2sum-demo und verweigert die Wiederverwendung eines vorhandenen Verzeichnisses. Ein erneuter Durchlauf überschreibt daher keinen früheren Versuch.

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

Das Beispielartefakt enthält Text, damit Änderungen leicht erkennbar sind. Dieselben Befehle funktionieren auch mit Binärdateien und leeren Dateien.

Ein Manifest für eine einzelne Datei erzeugen

Berechnen Sie auf Erzeugerseite den Hashwert des fertigen Artefakts aus dem Verzeichnis, in dem es liegt:

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

Lassen Sie diese Ausgabe unverändert. Sie enthält den Hashwert, ein Leerzeichen, die Binärmodus-Markierung * und den relativen Dateinamen ./my app.bin, gefolgt von einem Zeilenumbruch. GNU dokumentiert dieses Prüfsummen-Datensatzformat. ./ ist Teil des gespeicherten Dateinamens und verhindert außerdem, dass ein führender Bindestrich als Option interpretiert wird.

noclobber verweigert das Ersetzen eines vorhandenen Manifests. Ein fehlgeschlagener Hash-Befehl kann eine unvollständige neue Begleitdatei hinterlassen, da die Shell die Ausgabe zuerst öffnet. Veröffentlichen Sie diese fehlerhafte Ausgabe nicht. Erzeugen Sie Prüfsummen aus der vertrauenswürdigen Version, niemals aus einem verdächtigen Download, nur damit er die Prüfung besteht.

Die Version kopieren und prüfen

Kopieren Sie beide Dateien in ein neues Verzeichnis, um einen Download zu simulieren. Auch dieser Block verweigert die Wiederverwendung seines Zielverzeichnisses:

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

Für dieses Manifest ist das Verzeichnis mit dem Artefakt das Basisverzeichnis. Wechseln Sie in dieses Verzeichnis, bevor Sie das Standardprüfprogramm verwenden:

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

Erwartete Ausgabe mit coreutils 9.11 in der C-Locale; die Anführungszeichen um Dateinamen können je nach Version und Locale variieren:

'./my app.bin': OK

Relative Dateinamen in einem Manifest werden vom Arbeitsverzeichnis des Prüfprogramms aus aufgelöst, nicht vom Speicherort des Manifests aus. Ein Aufruf von b2sum --check b2sum-demo/downloads/my\ app.bin.b2 aus dem übergeordneten Verzeichnis würde dort nach ./my app.bin suchen. Das gemeinsame Verschieben von Artefakt und Manifest funktioniert, wenn Sie die Prüfung ebenfalls aus dem neuen Verzeichnis ausführen.

Die Option --strict lässt die Prüfung bei fehlerhaft formatierten Datensätzen scheitern. Sie prüft nicht, ob das Manifest das von Ihnen vorgesehene Artefakt nennt. Ein völlig gültiger Datensatz für other.bin kann die Prüfung bestehen, während my app.bin beschädigt ist oder fehlt. Verwenden Sie das folgende Skript, wenn ein Aufrufer eine bestimmte Datei anfordert.

Integritätsprüfungen automatisieren

Speichern Sie dies als b2sum-demo/verify-integrity.sh. Das Skript akzeptiert einen Artefaktpfad und liest die danebenliegende Datei .b2. Seine Anforderungen an das Manifest sind bewusst eng gefasst: Es muss genau den einzelnen Datensatz enthalten, den b2sum --binary -- './filename' mit dem Basisnamen des Artefakts und der Standard-Hashlänge erzeugt. Ausgaben mit Tags, zusätzliche Datensätze, geänderte Leerraumzeichen und abweichende Pfadschreibweisen werden abgelehnt.

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

Das Skript berechnet den Hashwert der angeforderten Datei und vergleicht den gesamten neu erzeugten Datensatz einschließlich des Dateinamens mit dem vertrauenswürdigen Manifest. cmp meldet nur dann Erfolg, wenn die Bytes übereinstimmen. Mit pipefail lässt Bash auch bei einer fehlgeschlagenen Hashberechnung die Pipeline scheitern. Leerzeichen und führende Bindestriche in Dateinamen werden unterstützt.

Das Skript wechselt selbst in das Verzeichnis des Artefakts. Aufrufer können daher einen relativen oder absoluten Pfad aus einem anderen Verzeichnis verwenden. Die physische Verzeichnisauflösung mit cd -P bewahrt die Bedeutung von Pfaden, die symbolische Links mit anschließendem .. enthalten. Das Skript schreibt weder in das Artefakt noch in dessen Manifest. Lassen Sie beide während der Verifizierung und der anschließenden Verwendung unverändert. Dieses Skript sperrt Dateien nicht gegen gleichzeitige Änderungen.

Nachfolgende Arbeit bei fehlgeschlagener Verifizierung stoppen

Führen Sie das Prüfskript mit Bash aus und machen Sie den nächsten Befehl von seinem Exit-Status abhängig:

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

Ein erfolgreicher Durchlauf gibt Folgendes aus:

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

Um einen Fehlerfall zu testen, ändern Sie nur die heruntergeladene Kopie, die Sie anschließend verwerfen können:

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

Dies gibt Verification failed: b2sum-demo/downloads/my app.bin auf der Standardfehlerausgabe aus und beendet sich mit Status 1. In einem CI/CD-Job muss der Schritt, der das Artefakt verwendet oder bereitstellt, ebenfalls von einer erfolgreichen Verifizierung abhängen. Ein späterer erfolgreicher Shell-Befehl darf den Fehler nicht verdecken.

Häufige Probleme beheben

Das Skript lehnt ein Manifest ab, das b2sum --check akzeptiert: Prüfen Sie dessen Dateinamen und Format. Dieses Skript erfordert einen Datensatz im Binärmodus mit ./basename, einschließlich des abschließenden Zeilenumbruchs. Folgen Sie bei einem Manifest des Herausgebers für mehrere Dateien dessen dokumentierter Verzeichnisstruktur und prüfen Sie, welche Dateien es erfasst, bevor Sie das Standardprüfprogramm verwenden.
Die Bytes unterscheiden sich: Prüfen Sie, ob Sie die gewünschte Version heruntergeladen haben. Laden Sie sie erneut von der vertrauenswürdigen Quelle herunter und untersuchen Sie wiederholte Abweichungen. Auch geänderte Textzeilenenden verändern einen Hashwert.
Eine Datei fehlt oder ist nicht lesbar: Prüfen Sie sowohl den Artefaktpfad als auch die Begleitdatei .b2 sowie die Verzeichnisberechtigungen. Ein leeres Artefakt ist gültig, wenn seine Prüfsumme übereinstimmt; ein leeres Manifest ist ungültig.
Ein Befehl fehlt: Das Prüfskript benötigt sowohl GNU b2sum als auch cmp in seinem Suchpfad für ausführbare Programme. Ein Fehler bei der Hashberechnung oder beim Vergleich liefert einen Status ungleich null zurück.

Die erwartete Prüfsumme vertrauenswürdig halten

Beziehen Sie die erwartete Prüfsumme über einen Veröffentlichungskanal, dem Sie vertrauen, oder verifizieren Sie ein signiertes Manifest mit einem Herausgeberschlüssel, dessen Identität Sie unabhängig festgestellt haben. Ein Angreifer, der sowohl das Artefakt als auch seine Prüfsumme ersetzen kann, kann diese Prüfung bestehen lassen. Werden beide vom selben kompromittierten Speicherort heruntergeladen, bietet das keine Authentizitätsgarantie.

Unsere lokale Kopie demonstriert die Integritätsprüfung nach der Übertragung. Eine neue Prüfsumme aus den heruntergeladenen Bytes zu erzeugen, würde lediglich beschreiben, was angekommen ist. Behalten Sie die vertrauenswürdige Prüfsumme des Erzeugers als Referenz bei und verifizieren Sie das Artefakt, bevor Sie es verwenden.