fido_dev_get_puat,
fido_dev_set_puat,
fido_dev_puat_ptr,
fido_dev_puat_len —
FIDO2 PIN/UV Auth token management functions
#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)