Signaturen
Was BatteryPass in jeder Passversion signiert, wie Hash und Ed25519-Signatur entstehen und wie Sie sie mit den veröffentlichten Schlüsseln prüfen.
Jede veröffentlichte Passversion ist signiert. So kann jeder prüfen, dass die Daten von Ihrer BatteryPass-Installation stammen und danach nicht verändert wurden. Für die Prüfung braucht es weder ein Konto noch einen Aufruf bei BatteryPass: Das öffentliche JSON und die veröffentlichten Schlüssel genügen.
Was signiert wird
Bei der Veröffentlichung signiert BatteryPass zwei Dokumente jeder Version mit dem aktiven Schlüssel, in derselben Transaktion, die sie speichert:
| Dokument | Enthält | Hash und Signatur | Wo Sie es lesen |
|---|---|---|---|
| Öffentliches Dokument | Die Projektion auf die Stufe public, mit Bezeichnungen | public_hash, public_signature | document und verification des öffentlichen JSON (getPublicPassport); public_document von getPassportVersion |
| Snapshot | Jedes Feld in jeder Zugriffsstufe, mit Herkunft und Dokumentverweisen | canonical_hash, signature | snapshot von getPassportVersion, für Ihre Organisation |
Das öffentliche Dokument sieht jeder Scanner, also kann es jeder prüfen. Der Snapshot belegt den vollständigen
Datensatz gegenüber Ihnen und gegenüber Behörden, denen Sie ihn vorlegen. Im öffentlichen JSON ist nur
document signiert; die Geschwister passport_id, status, valid_until, verification und links ändern
sich im Leben eines Passes und sind nicht abgedeckt.
{
"algorithm": "Ed25519",
"canonicalization": "RFC8785",
"hash": "sha256:22471733ece6d811d244144731fc505180c5e7760a7a016c1322338bce0f56e5",
"signature": "w0nnz3kjhrEGb1DtMoGp9qlH9g8q0h9YDJRb2jfabq7AOzPMUpnWXoxmIlptgJPTDVy3LWxLQkOpQYuGYXgJ4w",
"key_id": "2027-10-k2",
"signed_at": "2026-10-24T09:15:02Z",
"keys_url": "https://batterypass.example.com/.well-known/batterypass/keys.json"
}Wie eine Signatur entsteht und geprüft wird
Kanonisieren
Serialisieren Sie das signierte Objekt (document oder snapshot) mit dem JSON Canonicalization Scheme,
JCS (RFC 8785). JCS sortiert die Objektfelder, entfernt Leerraum und schreibt Zahlen und Zeichenketten in
einer festgelegten Form; dieselben Daten ergeben so immer dieselben Bytes. Kanonisieren Sie das geparste
Objekt, nicht die Bytes der Antwort.
Hashen
Berechnen Sie SHA-256 über die kanonischen Bytes und schreiben Sie ihn als sha256: gefolgt vom Hex-Digest
in Kleinbuchstaben. Er muss verification.hash entsprechen (bzw. public_hash, canonical_hash).
Schlüssel finden
Laden Sie das JWK-Set von /.well-known/batterypass/keys.json der BatteryPass-Adresse, der Sie vertrauen,
und nehmen Sie den Schlüssel, dessen kid gleich verification.key_id ist. keys_url ist nicht signiert:
zeigt es auf eine andere Adresse, gilt die Prüfung als fehlgeschlagen.
Prüfen
Dekodieren Sie x des Schlüssels und die Signatur aus base64url ohne Padding (32 und 64 Bytes) und prüfen
Sie die Ed25519-Signatur über die kanonischen Bytes, nicht über den Hash.
Die Anleitung zur Signaturprüfung zeigt das Schritt für Schritt mit vollständigem Code.
Die veröffentlichten Schlüssel
Die öffentlichen Schlüssel liegen als JWK-Set unter /.well-known/batterypass/keys.json Ihrer
BatteryPass-Adresse, außerhalb von /api/v1. Das Set braucht keinen Schlüssel, ist von jedem Ursprung aus
lesbar (CORS) und darf eine Stunde zwischengespeichert werden.
{
"keys": [
{ "kty": "OKP", "crv": "Ed25519", "x": "WuoaQRoQuh2kPs5yYB6HxNz3Y58ndE8fRHnzG10NxoU", "kid": "2027-10-k2", "use": "sig", "alg": "EdDSA" },
{ "kty": "OKP", "crv": "Ed25519", "x": "JEpD6r2NnmNrL4_7UWS9wIWLFyjCfaSClypHm110Vl4", "kid": "2026-10-k1", "use": "sig", "alg": "EdDSA" }
]
}Der aktive Schlüssel steht an erster Stelle. Schlüssel wechselt der Betreiber Ihrer Installation: Ein neuer
Schlüssel signiert neue Versionen, die alten öffentlichen Schlüssel bleiben im Set, damit frühere Signaturen
weiter prüfbar sind. Ein Schlüssel, der eine veröffentlichte Version signiert hat, wird nie entfernt.
Zwischenspeichern Sie Schlüssel nach kid und laden Sie das Set erneut, wenn Ihnen eine unbekannte kid
begegnet.
Prüfung auf dem Server oder offline
verifyPassport | Offline-Prüfung | |
|---|---|---|
| Was geprüft wird | Beide Signaturen und beide Hashes einer Version gegen die gespeicherten Dokumente | Das öffentliche Dokument, das Ihnen vorliegt, gegen den veröffentlichten Schlüssel |
| Ergebnis | valid, public_document_valid, snapshot_valid, key_id, version_no, signed_at, checked_at | Ihr eigenes Ja oder Nein |
| Vertrauen | Sie vertrauen der Antwort des Servers | Sie vertrauen nur dem Schlüssel, den Sie fest hinterlegen können |
| Braucht | Die UUID des Passes; version_no optional (Standard: aktuelle Version) | Das öffentliche JSON und das JWK-Set |
verifyPassport ist eine Abkürzung für eine schnelle Prüfung. Für einen unabhängigen Nachweis, etwa in einem
Archiv oder im System eines Kunden, prüfen Sie offline.
Eine gültige Signatur zeigt, dass diese BatteryPass-Installation genau diese Daten in dieser Version veröffentlicht hat. Sie sagt nichts darüber, ob die Daten richtig oder vollständig sind, und sie ist kein qualifiziertes elektronisches Siegel nach eIDAS.