home | help 
FIDO_CREDMAN_METADATA_NEW(3) Library Functions ManuaFIDO_CREDMAN_METADATA_NEW(3)

NAME
     fido_credman_metadata_new,     fido_credman_rk_new,    fido_credman_rp_new,
     fido_credman_metadata_free,   fido_credman_rk_free,   fido_credman_rp_free,
     fido_credman_rk_existing,	  fido_credman_rk_remaining,	fido_credman_rk,
     fido_credman_rk_count,	 fido_credman_rp_id,	   fido_credman_rp_name,
     fido_credman_rp_count,			    fido_credman_rp_id_hash_ptr,
     fido_credman_rp_id_hash_len,		  fido_credman_get_dev_metadata,
     fido_credman_get_dev_rk,  fido_credman_set_dev_rk, fido_credman_del_dev_rk,
     fido_credman_get_dev_rp -- FIDO2 credential management API

SYNOPSIS
     #include <fido.h>
     #include <fido/credman.h>

     fido_credman_metadata_t *
     fido_credman_metadata_new(void);

     fido_credman_rk_t *
     fido_credman_rk_new(void);

     fido_credman_rp_t *
     fido_credman_rp_new(void);

     void
     fido_credman_metadata_free(fido_credman_metadata_t **metadata_p);

     void
     fido_credman_rk_free(fido_credman_rk_t **rk_p);

     void
     fido_credman_rp_free(fido_credman_rp_t **rp_p);

     uint64_t
     fido_credman_rk_existing(const fido_credman_metadata_t *metadata);

     uint64_t
     fido_credman_rk_remaining(const fido_credman_metadata_t *metadata);

     const fido_cred_t *
     fido_credman_rk(const fido_credman_rk_t *rk, size_t idx);

     size_t
     fido_credman_rk_count(const fido_credman_rk_t *rk);

     const char *
     fido_credman_rp_id(const fido_credman_rp_t *rp, size_t idx);

     const char *
     fido_credman_rp_name(const fido_credman_rp_t *rp, size_t idx);

     size_t
     fido_credman_rp_count(const fido_credman_rp_t *rp);

     const unsigned char *
     fido_credman_rp_id_hash_ptr(const fido_credman_rp_t *rp, size_t idx);

     size_t
     fido_credman_rp_id_hash_len(const fido_credman_rp_t *, size_t idx);

     int
     fido_credman_get_dev_metadata(fido_dev_t *dev,
	 fido_credman_metadata_t *metadata, const char *pin);

     int
     fido_credman_get_dev_rk(fido_dev_t *dev, const char *rp_id,
	 fido_credman_rk_t *rk, const char *pin);

     int
     fido_credman_set_dev_rk(fido_dev_t *dev, fido_cred_t *cred,
	 const char *pin);

     int
     fido_credman_del_dev_rk(fido_dev_t *dev, const unsigned char *cred_id,
	 size_t cred_id_len, const char *pin);

     int
     fido_credman_get_dev_rp(fido_dev_t *dev, fido_credman_rp_t *rp,
	 const char *pin);

DESCRIPTION
     The credential management API of libfido2 allows resident credentials on  a
     FIDO2 authenticator to be listed, inspected, modified, and removed.  Please
     note  that  not all FIDO2 authenticators support credential management.  To
     obtain information on what  an  authenticator  supports,  please  refer  to
     fido_cbor_info_new(3).

     The fido_credman_metadata_t type abstracts credential management metadata.

     The fido_credman_metadata_new() function returns a pointer to a newly allo-
     cated,  empty fido_credman_metadata_t type.  If memory cannot be allocated,
     NULL is returned.

     The  fido_credman_metadata_free()	function  releases  the  memory  backing
     *metadata_p,  where  *metadata_p  must  have  been  previously allocated by
     fido_credman_metadata_new().  On return, *metadata_p is set to  NULL.   Ei-
     ther  metadata_p  or  *metadata_p	may  be  NULL,	in which case fido_cred-
     man_metadata_free() is a NOP.

     The fido_credman_get_dev_metadata() function populates metadata with infor-
     mation retrieved from dev.  A valid pin must be provided.

     The fido_credman_rk_existing() function inspects metadata and  returns  the
     number  of  resident  credentials	on  the  authenticator.   The fido_cred-
     man_rk_remaining() function inspects metadata  and  returns  the  estimated
     number of resident credentials that can be created on the authenticator.

     The  fido_credman_rk_t  type  abstracts the set of resident credentials be-
     longing to a given relying party.

     The fido_credman_rk_new() function returns a pointer to a newly  allocated,
     empty  fido_credman_rk_t  type.  If memory cannot be allocated, NULL is re-
     turned.

     The fido_credman_rk_free() function  releases  the  memory  backing  *rk_p,
     where  *rk_p  must have been previously allocated by fido_credman_rk_new().
     On return, *rk_p is set to NULL.  Either rk_p or  *rk_p  may  be  NULL,  in
     which case fido_credman_rk_free() is a NOP.

     The  fido_credman_get_dev_rk()  function populates rk with the set of resi-
     dent credentials belonging to rp_id in dev.  A valid pin must be provided.

     The fido_credman_rk_count() function returns the number of resident creden-
     tials in rk.  The fido_credman_rk() function returns a pointer to the  cre-
     dential  at  index  idx in rk.  Please note that the first credential in rk
     has an idx (index) value of 0.

     The fido_credman_set_dev_rk() function updates the credential pointed to by
     cred in dev.  The credential id and user id attributes of cred must be set.
     See fido_cred_set_id(3) and fido_cred_set_user(3) for details.  Only a cre-
     dential's user attributes (name, display name) may be updated at this time.

     The fido_credman_del_dev_rk()  function  deletes  the  resident  credential
     identified  by cred_id from dev, where cred_id points to cred_id_len bytes.
     A valid pin must be provided.

     The fido_credman_rp_t type abstracts information about a relying party.

     The fido_credman_rp_new() function returns a pointer to a newly  allocated,
     empty  fido_credman_rp_t  type.  If memory cannot be allocated, NULL is re-
     turned.

     The fido_credman_rp_free() function  releases  the  memory  backing  *rp_p,
     where  *rp_p  must have been previously allocated by fido_credman_rp_new().
     On return, *rp_p is set to NULL.  Either rp_p or  *rp_p  may  be  NULL,  in
     which case fido_credman_rp_free() is a NOP.

     The  fido_credman_get_dev_rp() function populates rp with information about
     relying parties with resident credentials in dev.	A valid pin must be pro-
     vided.

     The fido_credman_rp_count() function returns the number of relying  parties
     in rp.

     The fido_credman_rp_id() and fido_credman_rp_name() functions return point-
     ers to the id and name of relying party idx in rp.  If not NULL, the values
     returned  by these functions point to NUL-terminated UTF-8 strings.  Please
     note that the first relying party in rp has an idx (index) value of 0.

     The fido_credman_rp_id_hash_ptr() function returns a pointer to the  hashed
     id of relying party idx in rp.  The corresponding length can be obtained by
     fido_credman_rp_id_hash_len().  Please note that the first relying party in
     rp has an idx (index) value of 0.

RETURN VALUES
     The  fido_credman_get_dev_metadata(), fido_credman_get_dev_rk(), fido_cred-
     man_set_dev_rk(), fido_credman_del_dev_rk(), and  fido_credman_get_dev_rp()
     functions	return FIDO_OK on success.  On error, a different error code de-
     fined in <fido/err.h> is returned.  Functions returning  pointers	are  not
     guaranteed  to  succeed,  and  should  have their return values checked for
     NULL.

SEE ALSO
     fido_cbor_info_new(3), fido_cred_new(3), fido_dev_supports_credman(3)

CAVEATS
     Resident credentials are called "discoverable credentials" in CTAP 2.1.

FreeBSD ports 15.quarterly	  June 28, 2019     FIDO_CREDMAN_METADATA_NEW(3)
home | help