home | help 
FIDO_LARGEBLOB_GET(3)	     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  cre-
     dentials 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_large-
     blob_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.  Inser-
     tion happens at the end of the array if no  existing  element  can  be  de-
     crypted 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 er-
     ror 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_cred-
     man_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 ports 15.quarterly	October 26, 2020	   FIDO_LARGEBLOB_GET(3)
home | help