FIDO_CREDMAN_SET_DEV_RK(3)

💖 FIDO_CREDMAN_METADATA_NEW — the credential management API, bestie edition 💖

okay so this is from the Library Functions Manual (section 3), and it's literally the whole FIDO2 credential management glow-up for libfido2. pull up a chair 🫶

---

✨ 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 — the 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 🦋

so the credential management API of libfido2 lets you list, inspect, modify, and remove resident credentials sitting on a FIDO2 authenticator. iconic behaviour, truly.

⚠️ not every FIDO2 authenticator supports credential management, bestie. some of them are just not that girl. to find out what an authenticator actually supports, go look at fido_cbor_info_new(3). 👑

the fido_credman_metadata_t type is the vibe-abstraction for credential management metadata.

fido_credman_metadata_new() hands you a pointer to a freshly allocated, empty fido_credman_metadata_t. and if memory can't be allocated? NULL. that's it, that's the whole thing. 😭

fido_credman_metadata_free() releases the memory backing *metadata_p, and *metadata_p has to have been previously allocated by fido_credman_metadata_new() — no freeloaders. on return, *metadata_p gets set to NULL. and plot twist: either metadata_p or *metadata_p may be NULL, in which case fido_credman_metadata_free() is a whole NOP. nothing happens. it's giving ghosting. 💅

fido_credman_get_dev_metadata() populates metadata with info pulled from dev. a valid pin must be provided — no pin, no entry. 🔐

fido_credman_rk_existing() inspects metadata and returns the number of resident credentials on the authenticator. fido_credman_rk_remaining() also inspects metadata, but returns the estimated number of resident credentials that can still be created on the authenticator. the way that's the capacity check of your dreams ✨

the fido_credman_rk_t type abstracts the set of resident credentials belonging to a given relying party.

fido_credman_rk_new() returns a pointer to a newly allocated, empty fido_credman_rk_t. if memory can't be allocated, NULL is returned.

fido_credman_rk_free() 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, and in that case fido_credman_rk_free() is a NOP. 🫧

fido_credman_get_dev_rk() populates rk with the set of resident credentials belonging to rp_id in dev. a valid pin must be provided.

fido_credman_rk_count() returns the number of resident credentials in rk. fido_credman_rk() 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. zero-indexed, as nature intended. no cap.

fido_credman_set_dev_rk() 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 the deets. and heads up: only a credential's user attributes (name, display name) may be updated at this time. that's the limit, bestie. that's the whole menu.

fido_credman_del_dev_rk() 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. goodbye, credential, you were real 🎀

the fido_credman_rp_t type abstracts information about a relying party.

fido_credman_rp_new() returns a pointer to a newly allocated, empty fido_credman_rp_t. if memory can't be allocated, NULL is returned.

fido_credman_rp_free() 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.

fido_credman_get_dev_rp() populates rp with information about relying parties that have resident credentials in dev. a valid pin must be provided.

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

fido_credman_rp_id() and fido_credman_rp_name() 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. and yes, same rules apply: the first relying party in rp has an idx (index) value of 0. 🌀

fido_credman_rp_id_hash_ptr() 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(). and one more time for the people in the back — the first relying party in rp has an idx (index) value of 0. 🫶

---

🔥 RETURN VALUES 🔥

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() all return FIDO_OK on success. on error, you get a different error code defined in <fido/err.h>.

and like — functions that return pointers are not guaranteed to succeed, so please, for the love of everything, check those return values for NULL. this is your reminder. this is the vibe check. ⭐

---

🌈 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. same thing, different name, it's giving rebrand era. 🙈

---

and that's the page, bestie 🦋 this came out of the Debian distro, dated June 28, 2019, and it lives as FIDO_CREDMAN_METADATA_NEW(3) in the manual. stan a well-documented API. 💜🎀👑