FIDO_CREDMAN_METADATA_NEW(3)

FIDO_CREDMAN_METADATA_NEW(3) | Library Functions Manual | FIDO_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 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.

June 28, 2019 | Yubico AB