Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Verification journal

The verification journal is an append-only record of every successful verification. This page documents its purpose, its hash chain, its storage backends, its configuration, and its HTTP API.

Purpose

The journal gives each authenticated user a tamper-evident audit log of the credentials that the verifier accepted. The journal has these properties:

  • Non-repudiation: the journal records every accepted verification.
  • Tamper detection: a change to any entry breaks the hash chain.
  • Per-user scoping: each username has an independent chain.
  • Access control: a user can read only the user’s own journal over mutual TLS.

The server records an entry after a successful verification. A failed verification does not produce an entry.

Hash chaining

Each entry stores a hash that links it to the previous entry in the same user chain. The server computes two hashes.

attestation_signature_hash = hex(SHA-256(attestation_jwt_bytes))
entry_hash                 = hex(SHA-256(username_bytes || previous_hash_bytes || attestation_signature_hash_bytes))

The definitions of the two values are:

ValueInput
attestation_signature_hashThe raw bytes of the attestation JWT.
entry_hashThe username bytes, then the previous hash bytes, then the attestation hash bytes.

The server includes the username in the entry_hash input, so the hash of an entry is bound to its owner. This binding prevents a hash collision between two different users.

For the first entry of a chain, the previous_hash value is absent and the server substitutes an empty byte sequence.

When an entry has no signed attestation, for example a verifier app entry, the server substitutes the string qr:<username>:<entry_id> for the JWT bytes. This substitution keeps the attestation_signature_hash unique across users.

All hashes use SHA-256 and are stored as lowercase hexadecimal strings.

Storage backends

The backend key of the [journal_config] table selects the backend.

BackendPersistenceMulti-instanceNotes
sqlite_memoryNoNoDefault. Useful for development and tests.
sqlite_fileYesNoSingle instance with persistence.
postgresYesYesRecommended for high-availability deployments.

The SQLite backend creates the tables journal_entries and journal_heads. The tables include a unique index on entry_hash and an index on (username, created_at).

Concurrent append behaviour

The server appends with an optimistic compare-and-swap (CAS) on the per-user chain head. An append performs these operations in order.

OrderOperation
1Read the current head hash for the username.
2Compute the entry hash from that head.
3Append the entry, but only when the stored head still matches the value read in operation 1.

Each backend serializes the read-check-write section.

BackendSerialization
SQLiteA process-level mutex, held across an exclusive database transaction.
PostgreSQLA SELECT ... FOR UPDATE row lock inside a database transaction.

When a concurrent writer changes the head first, the append detects a stale head and retries. The server retries up to 5 times. When the retries are exhausted, the append fails with a hard error and the server reports the failure. The server does not silently drop an entry, because a missing entry would break the audit chain.

Configuration

The [journal_config] table configures the journal. The journal is disabled by default.

KeyTypeRequiredDefaultDescription
enabledbooleanNofalseTurn journaling on or off.
backendstringNosqlite_memoryStorage backend.
pathstringFor sqlite_file—Filesystem path to the SQLite journal file.
urlstringFor postgres—PostgreSQL connection URL.

The example below enables journaling with the SQLite file backend.

[journal_config]
enabled = true
backend = "sqlite_file"
path    = "/var/lib/ewqwe/journal.db"

The example below enables journaling with the PostgreSQL backend.

[journal_config]
enabled = true
backend = "postgres"
url     = "postgres://ewqwe:ewqwe@localhost/ewqwe"

The path value is relative to the configuration file directory. See Configuration for the path resolution rule.

Entry schema

The table below documents a full journal entry. The /download endpoint returns this shape.

FieldTypeDescription
idstringSurrogate primary key in UUIDv4 format.
usernamestringAuthenticated username. The Common Name of the client certificate.
previous_hashstringHash of the preceding entry. Absent for the first entry.
entry_hashstringChain hash of this entry, hex-encoded SHA-256.
attestation_signature_hashstringSHA-256 of the raw attestation JWT bytes, hex-encoded.
attestation_jtistringThe jti claim of the signed attestation.
client_idstringThe relying-party client_id bound to the verification.
doc_typestringCredential document type, for example org.iso.18013.5.1.mDL.
namespacestringCredential namespace, for example org.iso.18013.5.1.
qrcode_app_user_idstringVerifier app user identifier, when the verifier app started the verification.
qrcode_app_user_emailstringVerifier app user email, when the verifier app started the verification.
verification_summaryobjectJSON summary of the verification outcome.
created_atstringCreation time in RFC 3339 format, in UTC.

The verification_summary object holds the success boolean and the credential_claims object.

The /entries endpoint returns a smaller, human-readable view instead of the full entry. See the HTTP API page for the view fields and the query parameters.

Journal HTTP API

All journal endpoints start with /ewqwe_api/journal/{username}. Each endpoint requires a client certificate, and the authenticated username must equal the {username} path parameter.

MethodPathDescription
GET/ewqwe_api/journal/{username}/entriesList recent entries, newest first.
GET/ewqwe_api/journal/{username}/verifyVerify the full chain integrity.
GET/ewqwe_api/journal/{username}/downloadDownload entries as a JSON file.

The HTTP API page documents the query parameters, the response bodies, and the status codes of each endpoint.

When the journal is disabled, the journal store is absent and a request to these paths returns an internal server error.

Chain verification

The /verify endpoint recomputes every entry_hash from the first entry and compares the result with the stored values. The response holds these fields.

FieldTypeDescription
usernamestringThe journal owner.
validbooleantrue when every entry verifies from the first entry to the head.
entries_verifiedintegerNumber of entries that the server checked.
first_entry_hashstringHash of the first entry, when present.
last_entry_hashstringHash of the current head, when present.
errorstringHuman-readable reason when valid is false.