fido_dev_largeblob_get(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
FIDO_LARGEBLOB_GET(3)   NetBSD 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), dur-
     ing assertion with fido_assert_set_extensions(3) and
     fido_assert_largeblob_key_ptr(3), or, in the case of a resident creden-
     tial, 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 authentica-
     tor'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.

NetBSD 10.99                   January 13, 2025                   NetBSD 10.99