fido_dev_get_puat - Man Page

#include <fido.h>

int
fido_dev_get_puat(fido_dev_t *dev, unsigned int perm, const char *rpid, const char *pin);

int
fido_dev_set_puat(fido_dev_t *dev, const unsigned char *ptr, size_t len);

const unsigned char *
fido_dev_puat_ptr(const fido_dev_t *dev);

size_t
fido_dev_puat_len(const fido_dev_t *dev);

The fido_dev_get_puat() negotiates a FIDO2 PIN/UV Auth token with the permission bitmask specified by perm and associates it with dev. If perm does not require specifying a relying party ID, rpid may be NULL. Otherwise rpid must point to a NUL-terminated UTF-8 string. If a PIN is not needed to authenticate against dev, then pin may be NULL. Otherwise pin must point to a NUL-terminated UTF-8 string. Supported flags for perm are

FIDO_PUAT_MAKECRED

Permission for fido_dev_make_cred(). An rpid is required.

FIDO_PUAT_GETASSERT

Permission for fido_dev_get_assert(). An rpid is required.

FIDO_PUAT_CREDMAN

Permission for the credential management API. An rpid is optional.

FIDO_PUAT_BIOENROLL

Permission for the biometric enrollment API. The rpid is ignored.

FIDO_PUAT_LARGEBLOB

Permission for the large blobs API. The rpid is ignored.

FIDO_PUAT_CONFIG

Permission for the authenticator config API. The rpid is ignored.

FIDO_PUAT_CREDMAN_RO

Persistent read-only permission for the credential management API. The rpid is ignored.

The fido_dev_set_puat() function can be used to associate a token retrieved out-of-band with dev. No references to ptr are kept. If ptr is NULL or len is zero, the token is cleared from dev.

The fido_dev_puat_ptr() function returns a pointer to the PIN/UV Auth token currently associated with dev. The corresponding length can be obtained by calling fido_dev_puat_len().

Associating a token with dev has the main benefit of reducing the user interaction to a minimum in a sequence of operations where each would require some form of UV. Likewise, if multiple operations in a sequence need to be authenticated by a PIN, using a token avoids the need of caching the PIN for the duration of the whole sequence.

Once a token is associated with dev, it will take precedence over the regular PIN/UV Authentication for all operations that support the use of a token, until it is cleared from dev. The validity of the token is determined by the authenticator; it may expire and its permissions may be affected by its use. An invalid token is not automatically cleared from dev. Applications can call fido_dev_set_puat() or fido_dev_get_puat() to discard or obtain a new PIN/UV Auth token and retry the failed operation as appropriate.

For further details on token semantics, please refer to the FIDO Client to Authenticator Protocol (CTAP) standard.

On success, fido_dev_get_puat() and fido_dev_set_puat() return FIDO_OK. On error, a different error code defined in <fido/err.h> is returned.

fido_dev_puat_ptr() may return NULL if there is no PIN/UV Auth token associated with dev. If not NULL, the returned pointer is guaranteed to exist until either fido_dev_get_puat() fido_dev_set_puat(), or fido_dev_free() is invoked.

fido_dev_new(3)

fido_cbor_info_new(3).

The man pages fido_dev_puat_len(3), fido_dev_puat_ptr(3) and fido_dev_set_puat(3) are aliases of fido_dev_get_puat(3).