FIDO_DEV_GET_PUAT(3)

FIDO_DEV_GET_PUAT(3) | Library Functions Manual | FIDO_DEV_GET_PUAT(3)

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

April 8, 2026 | Yubico AB