Usage model

1. Make a credential with a U2F/FIDO device, e.g. using navigator.credential.create in webauthn, or using fido_dev_make_cred(3) on a client.
2. Optionally, get an assertion from the device with the hmac-secret extension enabled, e.g. using navigator.credential.get in webauthn, or using fido_dev_get_assert(3) on a client.
3. Call fido_cred_encrypt() with the credential, optionally the assertion, and the payload you wish to encrypt so that it cannot be decrypted except with the same U2F/FIDO device later on. You will be returned a ciphertext, which includes enough information to verify an assertion of the credential and recover the plaintext later on.
4. Store the ciphertext alongside the credential id so you can retireve it later during authentication. Do not store the credential's public key — the ciphertext contains enough information to verify an assertion during authentication, as if the public key had been stored.

Typically the payload will be the same for every credential of a single user. For example, you might store a share of the encryption key for the user's password vault, and store the same key for every credential registered by the user. This way, any one of the user's U2F/FIDO keys can be used (along with a share derived from another factor such as a master password) to decrypt the password vault.

You may also wish to verify any device attestation in the credential separately with fido_cred_verify(3) — fido_cred_encrypt() does not verify device attestations.

Authentication

1. Get an assertion from a U2F/FIDO device, e.g. using navigator.credential.get in webauthn, or using fido_dev_get_assert(3) on a client. If hmac-secret was enabled during registration, it must be enabled during authentication too.
2. Retrieve the ciphertext stored for the alleged credential id in the assertion.
3. Call fido_assert_decrypt() to simultaneously verify the assertion of the credential and decrypt the ciphertext.

Functions

fido_assert_decrypt(assert, idx, ciphertext, ciphertextlen, payloadp, payloadlenp)

Verify the signature in statement index idx of assert against the ciphertext ciphertext of ciphertextlen bytes. If the signature matches, decrypt the ciphertext and return its payload in a newly allocated buffer in *payloadp with length in bytes stored in *payloadlenp. The buffer is allocated with malloc(3) or equivalent and must be freed with free(3) when done. If the signature does not match or anything else about the assertion statement is invalid, return one of the FIDO_ERR_* constants to indicate failure.

fido_assert_decrypt() implies the same authentication guarantees as fido_assert_verify() normally does without fidocrypt, but with fidocrypt, you must use fido_assert_decrypt() instead of fido_assert_verify().

If the ciphertext was created with an assertion made using the hmac-secret extension during credential registration, then assert must also have the hmac-secret extension, and conversely.

fido_cred_encrypt(cred, assert, idx, payload, payloadlen, ciphertextp, ciphertextlenp)

Encrypt a message payload of payloadlen bytes using the credential in cred, and, if provided, the hmac-secret in the statement index idx of assert. Return a newly allocated buffer in *ciphertextp with a length in bytes in *ciphertextlenp. The buffer is allocated with malloc(3) or equivalent and must be freed with free(3) when done.

You should store the ciphertext, and only the ciphertext, to later verify an assertion of the credential with fido_assert_decrypt(). You must not store the credential's public key — the ciphertext contains enough information to verify an assertion during authentication, as if the public key had been stored.

assert may be a null pointer, in which case no hmac-secret is incorporated, and hmac-secret must be disabled when getting an assertion from this device to retrieve the secret.