TRACE Producer#
The planned TRACE producer makes jans-fido2 emit one record for each passkey registration and assertion outcome that has a session, to the Lock Server. Each record is signed and hash-chained. The chain lets a reader detect a gap or an altered record between records it has seen. It cannot by itself show that the newest records are missing: detecting tail loss needs an independently trusted checkpoint or an expected chain head. This page covers the planned configuration properties and what a record contains.
Status
This is planned behavior, not yet available. The properties are added in
#15680 and take effect only after that PR and the
follow-up work tracked in #15275 (record emission,
signing, and transport) are merged. Until then, setting fido2TraceEnabled to true does not change behavior.
Lock dependency: the producer's key must be registered on Lock with FIDO_CEREMONY in its
authorized_event_kinds. The current Lock Server does not define that event kind, so delivery will fail
until Lock adds support for it.
Configuration#
All properties are set in the fido2Configuration object, the same place as the Lock audit properties in
FIDO2 Configuration Parameters.
| Property | Type | Default | Description |
|---|---|---|---|
fido2TraceEnabled |
Boolean | false |
Planned. Master switch. When false, nothing is emitted. |
fido2TraceProducerId |
String | derived | Planned. Stable producer ID. Leave empty to derive it from the server ID and version; the derived value can change on upgrade, so set an explicit ID for continuity. |
fido2TraceChainGenesis |
String | first_observed |
Planned. pre_registered if Lock knows each node's chain genesis in advance, otherwise first_observed. |
fido2TraceIncludeCredentialIdHash |
Boolean | true |
Planned. Include credential_id_hash, a hash of the credential ID, rather than the raw credential ID. |
fido2TraceIncludeAttestationDetail |
Boolean | false |
Planned. Include optional signed attestation and MDS trust detail in each record. |
fido2TraceEndpoint |
String | discovered | Planned. Lock Server ingestion endpoint, /jans-lock/api/v1/audit/trace. |
fido2TraceKeyStorePath |
String | — | Planned. Path to a BCFKS keystore file that holds the Ed25519 producer signing key. The key stays in the file and is never stored in configuration. |
fido2TraceKeyAlias |
String | — | Planned. Alias of the Ed25519 signing key inside fido2TraceKeyStorePath. |
fido2TraceKeyStorePassword |
String | — | Planned. Keystore password, encrypted at rest like other client secrets. |
The TRACE properties are separate from the lockAudit* properties. Enabling one does not enable the other.
The client that sends records uses the trace.write scope, requested when the FIDO Server registers as a client
through the SSA-to-DCR client-credentials flow.
What a record contains#
Each record is a FIDO_CEREMONY event.
- Event kind:
trace.event_kindisFIDO_CEREMONY. - Ceremony:
ceremony_typeisREGISTRATIONorASSERTION. - Outcome:
ceremony_outcomeisSUCCESS,FAILURE, orABANDONED. - Authenticator:
authenticator_attachmentisplatformorcross-platform. - Correlation:
trace.session_idis required. Ceremonies with no session do not emit a record by default. - Integrity:
record_id,sequence_number,prev_record_hash, and an Ed25519signatureover the RFC 8785 (JCS) canonical form of the record.
Records do not contain policy decisions, invocations, or capability IDs. TRACE records describe what happened in a ceremony, and they do not affect how the ceremony is decided.
Signing#
A record is signed as follows:
- Remove the
signaturemember, if present, and take the rest of the record. - Serialize it with the JSON Canonicalization Scheme (RFC 8785): members sorted by UTF-16 code units, no
insignificant whitespace, and numbers in the ECMAScript form, for example
1e+30and0.000001. - Sign the UTF-8 bytes of that canonical form with Ed25519 (RFC 8032).
- Store the 64-byte signature as base64url without padding, which is 86 characters.
Records that contain an unpaired surrogate, or a non-finite number such as NaN, are rejected rather than signed.
Hashes use the sha256: prefix followed by the lowercase hex digest.
The prev_record_hash of a record is the content_digest of the previous record. Lock computes that digest over
the complete previous record, including its signature. Hash the signed form, not the unsigned form, when you
set prev_record_hash. Otherwise Lock flags the link with chain_link_failure_flag.
Signing key#
The producer key is an Ed25519 key in a BCFKS keystore. Create one with a BouncyCastle provider jar. keytool
prompts for the keystore and key passwords, so do not pass them on the command line:
keytool -genkeypair -storetype BCFKS -keystore /etc/jans/conf/trace-producer.bcfks \
-alias trace-producer -keyalg Ed25519 -dname "CN=jans-fido2-trace" -validity 3650 \
-providerpath /path/to/bcprov-jdk18on.jar \
-providerclass org.bouncycastle.jce.provider.BouncyCastleProvider
Then set fido2TraceKeyStorePath to the file, fido2TraceKeyAlias to trace-producer, and
fido2TraceKeyStorePassword to the keystore password. The password is encrypted when it is stored.
Register the public key on Lock#
Lock needs the public key as an Ed25519 JWK. Export the certificate that keytool created, then take the raw
32-byte key from its public key and encode it as base64url:
keytool -exportcert -storetype BCFKS -keystore /etc/jans/conf/trace-producer.bcfks -alias trace-producer \
-providerpath /path/to/bcprov-jdk18on.jar \
-providerclass org.bouncycastle.jce.provider.BouncyCastleProvider -file trace-producer.der
openssl x509 -inform DER -in trace-producer.der -pubkey -noout > trace-producer.pem
openssl pkey -pubin -in trace-producer.pem -outform DER | tail -c 32 | base64 | tr '+/' '-_' | tr -d '='
Register the result with {"kty": "OKP", "crv": "Ed25519", "x": "<output>"} as described in
Register a key. Lock does not yet define the FIDO_CEREMONY event kind, so
registration with that kind cannot succeed until Lock adds it.
Rotating the signing key#
Lock accepts a new key only under a new kid, and it never changes a registered key. To rotate:
- Create a new key with a new alias, or in a new keystore file.
- Register its public key on Lock under a new
kid, as described in Register a key. - Set
fido2TraceKeyAliasorfido2TraceKeyStorePathto the new key. - Revoke the old key on Lock once its records no longer need to be verified, as described in Revoke a key.
- Decide whether the producer chain continues or starts a new one. See Register a producer chain for when a new chain is needed.
FIPS builds
Ed25519 signs and verifies under the BC-FIPS 1.0.2.7 provider that the FIPS build uses. When BC-FIPS approved-only mode is enabled, Ed25519 is rejected. Jans does not enable that mode, so TRACE signing works in the FIPS build but is not FIPS-approved. Do not describe TRACE signing as FIPS-approved until this changes.
Lock compatibility
For integers above 2^53, RFC 8785 requires rounding to an IEEE double before serialization. The current Lock canonicalizer does not do this, so records with such integers fail verification on Lock. Tracked in #15703.
Delivery#
Records are sent asynchronously and in batches, never one HTTP call per ceremony, and they are kept off the ceremony's hot path. Delivery is retried on transport failure.