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   allocated,   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.
       Either metadata_p or *metadata_p may be NULL, in which case fido_credman_metadata_free() is a NOP.

       The fido_credman_get_dev_metadata() function populates metadata with information 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_credman_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 belonging 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 returned.

       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  resident  credentials  belonging  to
       rp_id in dev.  A valid pin must be provided.

       The   fido_credman_rk_count()   function   returns  the  number  of  resident  credentials  in  rk.   The
       fido_credman_rk() function returns a pointer to the credential 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 credential'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 returned.

       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 provided.

       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 pointers  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_credman_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  defined  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.

Debian                                            June 28, 2019                     FIDO_CREDMAN_METADATA_NEW(3)