FIDO_ASSERT_NEW(3)

💖 FIDO_ASSERT_NEW(3) — the FIDO2 assertion API, explained by your bestie 💖

okay so bestie, welcome to FIDO_ASSERT_NEW(3) from the Library Functions Manual ✨ this is the libfido2 corner of the world where FIDO2 assertions live, and honestly? it's giving main character energy. let's get into it 🎀

✨ NAME ✨

fido_assert_new, fido_assert_free, fido_assert_count, fido_assert_rp_id, fido_assert_user_display_name, fido_assert_user_icon, fido_assert_user_name, fido_assert_authdata_ptr, fido_assert_authdata_raw_ptr, fido_assert_blob_ptr, fido_assert_clientdata_hash_ptr, fido_assert_hmac_secret_ptr, fido_assert_largeblob_key_ptr, fido_assert_user_id_ptr, fido_assert_sig_ptr, fido_assert_id_ptr, fido_assert_authdata_len, fido_assert_authdata_raw_len, fido_assert_blob_len, fido_assert_clientdata_hash_len, fido_assert_hmac_secret_len, fido_assert_largeblob_key_len, fido_assert_user_id_len, fido_assert_sig_len, fido_assert_id_len, fido_assert_sigcount, fido_assert_flags — FIDO2 assertion API 🦋

✨ SYNOPSIS ✨

#include <fido.h>

fido_assert_t *
fido_assert_new(void);

void
fido_assert_free(fido_assert_t **assert_p);

size_t
fido_assert_count(const fido_assert_t *assert);

const char *
fido_assert_rp_id(const fido_assert_t *assert);

const char *
fido_assert_user_display_name(const fido_assert_t *assert, size_t idx);

const char *
fido_assert_user_icon(const fido_assert_t *assert, size_t idx);

const char *
fido_assert_user_name(const fido_assert_t *assert, size_t idx);

const unsigned char *
fido_assert_authdata_ptr(const fido_assert_t *assert, size_t idx);

const unsigned char *
fido_assert_authdata_raw_ptr(const fido_assert_t *assert, size_t idx);

const unsigned char *
fido_assert_clientdata_hash_ptr(const fido_assert_t *assert);

const unsigned char *
fido_assert_blob_ptr(const fido_assert_t *assert, size_t idx);

const unsigned char *
fido_assert_hmac_secret_ptr(const fido_assert_t *assert, size_t idx);

const unsigned char *
fido_assert_largeblob_key_ptr(const fido_assert_t *assert, size_t idx);

const unsigned char *
fido_assert_user_id_ptr(const fido_assert_t *assert, size_t idx);

const unsigned char *
fido_assert_sig_ptr(const fido_assert_t *assert, size_t idx);

const unsigned char *
fido_assert_id_ptr(const fido_assert_t *assert, size_t idx);

size_t
fido_assert_authdata_len(const fido_assert_t *assert, size_t idx);

size_t
fido_assert_authdata_raw_len(const fido_assert_t *assert, size_t idx);

size_t
fido_assert_clientdata_hash_len(const fido_assert_t *assert);

size_t
fido_assert_blob_len(const fido_assert_t *assert, size_t idx);

size_t
fido_assert_hmac_secret_len(const fido_assert_t *assert, size_t idx);

size_t
fido_assert_largeblob_key_len(const fido_assert_t *assert, size_t idx);

size_t
fido_assert_user_id_len(const fido_assert_t *assert, size_t idx);

size_t
fido_assert_sig_len(const fido_assert_t *assert, size_t idx);

size_t
fido_assert_id_len(const fido_assert_t *assert, size_t idx);

uint32_t
fido_assert_sigcount(const fido_assert_t *assert, size_t idx);

uint8_t
fido_assert_flags(const fido_assert_t *assert, size_t idx);

🌸 DESCRIPTION 🌸

okay so picture this: a FIDO2 assertion is basically a collection of statements, and each statement is a little map between a challenge, a credential, a signature, and some ancillary attributes. in libfido2, that whole vibe is abstracted by the fido_assert_t type 💅

the functions on this page let you allocate, deallocate, and inspect a fido_assert_t. for other operations on fido_assert_t, bestie, go check out fido_assert_set_authdata(3), fido_assert_allow_cred(3), fido_assert_verify(3), and fido_dev_get_assert(3) 🫶

fido_assert_new() hands you a pointer to a freshly allocated, empty fido_assert_t type. if memory can't be allocated? it returns NULL. sad but true 😭

fido_assert_free() releases the memory backing *assert_p, and *assert_p must have been previously allocated by fido_assert_new(). on return, *assert_p is set to NULL. and here's the chill part: either assert_p or *assert_p may be NULL, in which case fido_assert_free() is a NOP — no drama, no crash 💖

fido_assert_count() returns the number of statements in assert. slay, simple.

fido_assert_rp_id() returns a pointer to a NUL-terminated string holding the relying party ID of assert.

fido_assert_user_display_name(), fido_assert_user_icon(), and fido_assert_user_name() return pointers to the user display name, icon, and name attributes of statement idx in assert. if they're not NULL, those returned values point to NUL-terminated UTF-8 strings ✨

ngl the user display name, icon, and name attributes will typically only be returned by the authenticator if user verification was performed by the authenticator and multiple resident/discoverable credentials were involved in the assertion. iykyk 🍓

fido_assert_authdata_ptr(), fido_assert_authdata_raw_ptr(), fido_assert_clientdata_hash_ptr(), fido_assert_id_ptr(), fido_assert_user_id_ptr(), fido_assert_sig_ptr(), fido_assert_sigcount(), and fido_assert_flags() return pointers to the CBOR-encoded and raw authenticator data, client data hash, credential ID, user ID, signature, signature count, and authenticator data flags of statement idx in assert 👑

fido_assert_hmac_secret_ptr() returns a pointer to the hmac-secret attribute of statement idx in assert. the HMAC Secret Extension (hmac-secret) is a CTAP 2.0 extension. heads up though: the resulting hmac-secret varies according to whether user verification was performed by the authenticator 🔥

fido_assert_blob_ptr() and fido_assert_largeblob_key_ptr() return pointers to the “credBlob” and “largeBlobKey” attributes of statement idx in assert. Credential Blob (credBlob) and Large Blob Key (largeBlobKey) are CTAP 2.1 extensions 🦋

fido_assert_authdata_len(), fido_assert_authdata_raw_len(), fido_assert_clientdata_hash_len(), fido_assert_id_len(), fido_assert_user_id_len(), fido_assert_sig_len(), fido_assert_hmac_secret_len(), fido_assert_blob_len(), and fido_assert_largeblob_key_len() return the length of a given attribute 📏

⚠️ please note, bestie: the first statement in assert has an idx (index) value of 0. not 1. zero. periodt 💅

the authenticator data and signature parts of an assertion statement are typically passed to a FIDO2 server for verification 🌈

🎀 RETURN VALUES 🎀

the authenticator data returned by fido_assert_authdata_ptr() is a CBOR-encoded byte string, as obtained from the authenticator. no cap.

the following functions may return NULL if the respective field in assert is not set:

• fido_assert_rp_id()
• fido_assert_user_display_name()
• fido_assert_user_icon()
• fido_assert_user_name()
• fido_assert_authdata_ptr()
• fido_assert_clientdata_hash_ptr()
• fido_assert_id_ptr()
• fido_assert_user_id_ptr()
• fido_assert_sig_ptr()
• fido_assert_hmac_secret_ptr()
• fido_assert_blob_ptr()
• fido_assert_largeblob_key_ptr()

and if they're not NULL? those returned pointers are guaranteed to exist until any API function that takes assert without the const qualifier gets invoked 🔥 (so like… don't go calling a mutating function and then acting surprised, bestie 🙈)

🦋 SEE ALSO 🦋

fido_assert_allow_cred(3), fido_assert_set_authdata(3), fido_assert_verify(3), fido_dev_get_assert(3), fido_dev_largeblob_get(3)

and that's the whole page, bestie 💖 this one came to you from Debian, dated June 19, 2023 — go forth and inspect your assertions responsibly 🧚✨💜