Skip to main content

Module device_challenge

Module device_challenge 

Source
Expand description

Anonymous device enrollment — stateless HMAC challenge and Ed25519 verification.

The challenge is HMAC-SHA256(challenge_key, pubkey). It is deterministic: the same pubkey always produces the same challenge. Replay of a valid (pubkey, signature) pair is idempotent — it re-enrolls the same device, producing the same DeviceRecord upsert. This is analogous to PKCS#10 CSR signing in standard PKI, where the CA validates possession, not freshness.

challenge_key is derived from the node signing key via HKDF so that:

  1. It never overlaps with the JWT signing path.
  2. It is safe to use as a challenge oracle (HMAC is secure under chosen-message attacks).

Functions§

compute_kid
Compute the kid for a cookie signing key (first 4 bytes of SHA-256 → 8 hex chars).
derive_challenge_key
Derive the challenge key from the node signing key seed.
derive_cookie_key_seed
Derive the cookie signing key from the node signing key seed.
device_challenge
Compute the challenge bytes the client must sign to prove device key possession.
encode_vault_device_cookie
Encode a __Secure-VaultDevice cookie value.
verify_device_enrollment
Verify that signature is a valid Ed25519 signature over HMAC(challenge_key, pubkey).
verify_vault_device_cookie
Verify a __Secure-VaultDevice cookie and return the device pubkey on success.