fido_dev_largeblob_get,
fido_dev_largeblob_set,
fido_dev_largeblob_remove,
fido_dev_largeblob_get_array,
fido_dev_largeblob_set_array —
FIDO2 large blob API
#include
<fido.h>
int
fido_dev_largeblob_get(
fido_dev_t
*dev,
const
unsigned char *key_ptr,
size_t key_len,
unsigned char
**blob_ptr,
size_t
*blob_len);
int
fido_dev_largeblob_set(
fido_dev_t
*dev,
const
unsigned char *key_ptr,
size_t key_len,
const unsigned char
*blob_ptr,
size_t blob_len,
const char
*pin);
int
fido_dev_largeblob_remove(
fido_dev_t
*dev,
const
unsigned char *key_ptr,
size_t key_len,
const char
*pin);
int
fido_dev_largeblob_get_array(
fido_dev_t
*dev,
unsigned
char **cbor_ptr,
size_t
*cbor_len);
int
fido_dev_largeblob_set_array(
fido_dev_t
*dev,
const
unsigned char *cbor_ptr,
size_t cbor_len,
const char
*pin);
The “largeBlobs” API of
libfido2
allows binary blobs residing on a CTAP 2.1 authenticator to be read, written,
and inspected. “largeBlobs” is a CTAP 2.1 extension.
“largeBlobs” are stored as elements of a CBOR array.
Confidentiality is ensured by encrypting each element with a distinct,
credential-bound 256-bit AES-GCM key. The array is otherwise shared between
different credentials and FIDO2 relying parties.
Retrieval of a credential's encryption key is possible during enrollment with
fido_cred_set_extensions(3)
and
fido_cred_largeblob_key_ptr(3),
during assertion with
fido_assert_set_extensions(3)
and
fido_assert_largeblob_key_ptr(3),
or, in the case of a resident credential, via
libfido2's credential management API.
The “largeBlobs” CBOR array is opaque to the authenticator.
Management of the array is left at the discretion of FIDO2 clients. For
further details on CTAP 2.1's “largeBlobs” extension, please
refer to the CTAP 2.1 spec.
The
fido_dev_largeblob_get() function
retrieves the authenticator's “largeBlobs” CBOR array and, on
success, returns the first blob (iterating from array index zero) that can be
decrypted by
key_ptr, where
key_ptr points to
key_len bytes. On success,
fido_dev_largeblob_get() sets
blob_ptr to the body of the decrypted blob,
and
blob_len to the length of the decrypted
blob in bytes. It is the caller's responsibility to free
blob_ptr.
The
fido_dev_largeblob_set() function uses
key_ptr to encrypt
blob_ptr and inserts the result in the
authenticator's “largeBlobs” CBOR array. Insertion happens at
the end of the array if no existing element can be decrypted by
key_ptr, or at the position of the first
element (iterating from array index zero) that can be decrypted by
key_ptr.
key_len holds the length of
key_ptr in bytes, and
blob_len the length of
blob_ptr in bytes. A
pin or equivalent user-verification gesture
is required.
The
fido_dev_largeblob_remove() function
retrieves the authenticator's “largeBlobs” CBOR array and, on
success, drops the first blob (iterating from array index zero) that can be
decrypted by
key_ptr, where
key_ptr points to
key_len bytes. A
pin or equivalent user-verification gesture
is required.
The
fido_dev_largeblob_get_array() function
retrieves the authenticator's “largeBlobs” CBOR array and, on
success, sets
cbor_ptr to the body of the
CBOR array, and
cbor_len to its corresponding
length in bytes. It is the caller's responsibility to free
cbor_ptr.
Finally, the
fido_dev_largeblob_set_array()
function sets the authenticator's “largeBlobs” CBOR array to the
data pointed to by
cbor_ptr, where
cbor_ptr points to
cbor_len bytes. A
pin or equivalent user-verification gesture
is required.
The functions
fido_dev_largeblob_set(),
fido_dev_largeblob_get(),
fido_dev_largeblob_remove(),
fido_dev_largeblob_get_array(), and
fido_dev_largeblob_set_array() return
FIDO_OK on success. On error, an error code
defined in
<fido/err.h>
is returned.
fido_assert_largeblob_key_len(3),
fido_assert_largeblob_key_ptr(3),
fido_assert_set_extensions(3),
fido_cred_largeblob_key_len(3),
fido_cred_largeblob_key_ptr(3),
fido_cred_set_extensions(3),
fido_credman_get_dev_rk(3),
fido_credman_get_dev_rp(3),
fido_dev_get_assert(3),
fido_dev_make_cred(3)
The “largeBlobs” extension is not meant to be used to store
sensitive data. When retrieved, a credential's “largeBlobs”
encryption key is transmitted in the clear, and an authenticator's
“largeBlobs” CBOR array can be read without user interaction or
verification.