Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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
       credentials and FIDO2 relying parties.

       Retrieval  of  a	credential's encryption	key is possible	during enroll-
       ment	      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 manage-
       ment 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-veri-
       fication	gesture	is required.

       The fido_dev_largeblob_get_array() function retrieves  the  authentica-
       tor'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 authenti-
       cator'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-ver-
       ification 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  ar-
       ray can be read without user interaction	or verification.

FreeBSD	Ports 14.quarterly     October 26, 2020		 FIDO_LARGEBLOB_GET(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=fido_dev_largeblob_set_array&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help