FreeBSD manual
download PDF document: fido_dev_largeblob_get.3.pdf
FIDO_LARGEBLOB_GET(3) FreeBSD Library Functions Manual FIDO_LARGEBLOB_GET(3)
NAME
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
SYNOPSIS
#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);
DESCRIPTION
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.
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.
RETURN VALUES
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.
SEE ALSO
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)
CAVEATS
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.
FreeBSD 14.0-RELEASE-p11 October 26, 2020 FreeBSD 14.0-RELEASE-p11