xref: /freebsd-src/contrib/libfido2/man/fido_dev_set_pin.3 (revision 2ccfa855b2fc331819953e3de1b1c15ce5b95a7e)

.\" Copyright (c) 2018 Yubico AB. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\"    1. Redistributions of source code must retain the above copyright
.\"       notice, this list of conditions and the following disclaimer.
.\"    2. Redistributions in binary form must reproduce the above copyright
.\"       notice, this list of conditions and the following disclaimer in
.\"       the documentation and/or other materials provided with the
.\"       distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.Dd $Mdocdate: May 25 2018 $
.Dt FIDO_DEV_SET_PIN 3
.Os
.Sh NAME
.Nm fido_dev_set_pin ,
.Nm fido_dev_get_retry_count ,
.Nm fido_dev_get_uv_retry_count ,
.Nm fido_dev_reset
.Nd FIDO2 device management functions
.Sh SYNOPSIS
.In fido.h
.Ft int
.Fn fido_dev_set_pin "fido_dev_t *dev" "const char *pin" "const char *oldpin"
.Ft int
.Fn fido_dev_get_retry_count "fido_dev_t *dev" "int *retries"
.Ft int
.Fn fido_dev_get_uv_retry_count "fido_dev_t *dev" "int *retries"
.Ft int
.Fn fido_dev_reset "fido_dev_t *dev"
.Sh DESCRIPTION
The
.Fn fido_dev_set_pin
function sets the PIN of device
.Fa dev
to
.Fa pin ,
where
.Fa pin
is a NUL-terminated UTF-8 string.
If
.Fa oldpin
is not NULL, the device's PIN is changed from
.Fa oldpin
to
.Fa pin ,
where
.Fa pin
and
.Fa oldpin
are NUL-terminated UTF-8 strings.
.Pp
The
.Fn fido_dev_get_retry_count
function fills
.Fa retries
with the number of PIN retries left in
.Fa dev
before lock-out, where
.Fa retries
is an addressable pointer.
.Pp
The
.Fn fido_dev_get_uv_retry_count
function fills
.Fa retries
with the number of built-in UV retries left in
.Fa dev
before built-in UV is disabled, where
.Fa retries
is an addressable pointer.
.Pp
The
.Fn fido_dev_reset
function performs a reset on
.Fa dev ,
resetting the device's PIN and erasing credentials stored on the
device.
.Pp
Please note that
.Fn fido_dev_set_pin ,
.Fn fido_dev_get_retry_count ,
.Fn fido_dev_get_uv_retry_count ,
and
.Fn fido_dev_reset
are synchronous and will block if necessary.
.Sh RETURN VALUES
The error codes returned by
.Fn fido_dev_set_pin ,
.Fn fido_dev_get_retry_count ,
.Fn fido_dev_get_uv_retry_count ,
and
.Fn fido_dev_reset
are defined in
.In fido/err.h .
On success,
.Dv FIDO_OK
is returned.
.Sh SEE ALSO
.Xr fido_cbor_info_uv_attempts 3
.Sh CAVEATS
Regarding
.Fn fido_dev_reset ,
the actual user-flow to perform a reset is outside the scope of the
FIDO2 specification, and may therefore vary depending on the
authenticator.
Yubico authenticators will return
.Dv FIDO_ERR_NOT_ALLOWED
if a reset is issued later than 5 seconds after power-up, and
.Dv FIDO_ERR_ACTION_TIMEOUT
if the user fails to confirm the reset by touching the key
within 30 seconds.