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.

       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.

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.

Debian                                          October 26, 2020                           FIDO_LARGEBLOB_GET(3)