NAME

fido_dev_get_puat, fido_dev_set_puat, fido_dev_puat_ptr, fido_dev_puat_len — FIDO2 PIN/UV Auth token management functions

SYNOPSIS

#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);

DESCRIPTION

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.

RETURN VALUES

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.

SEE ALSO

fido_dev_new(3)