1.\" Copyright (c) 2018 Yubico AB. All rights reserved.
2.\" Use of this source code is governed by a BSD-style
3.\" license that can be found in the LICENSE file.
4.\"
5.Dd $Mdocdate: May 25 2018 $
6.Dt FIDO_DEV_SET_PIN 3
7.Os
8.Sh NAME
9.Nm fido_dev_set_pin ,
10.Nm fido_dev_get_retry_count ,
11.Nm fido_dev_get_uv_retry_count ,
12.Nm fido_dev_reset
13.Nd FIDO 2 device management functions
14.Sh SYNOPSIS
15.In fido.h
16.Ft int
17.Fn fido_dev_set_pin "fido_dev_t *dev" "const char *pin" "const char *oldpin"
18.Ft int
19.Fn fido_dev_get_retry_count "fido_dev_t *dev" "int *retries"
20.Ft int
21.Fn fido_dev_get_uv_retry_count "fido_dev_t *dev" "int *retries"
22.Ft int
23.Fn fido_dev_reset "fido_dev_t *dev"
24.Sh DESCRIPTION
25The
26.Fn fido_dev_set_pin
27function sets the PIN of device
28.Fa dev
29to
30.Fa pin ,
31where
32.Fa pin
33is a NUL-terminated UTF-8 string.
34If
35.Fa oldpin
36is not NULL, the device's PIN is changed from
37.Fa oldpin
38to
39.Fa pin ,
40where
41.Fa pin
42and
43.Fa oldpin
44are NUL-terminated UTF-8 strings.
45.Pp
46The
47.Fn fido_dev_get_retry_count
48function fills
49.Fa retries
50with the number of PIN retries left in
51.Fa dev
52before lock-out, where
53.Fa retries
54is an addressable pointer.
55.Pp
56The
57.Fn fido_dev_get_uv_retry_count
58function fills
59.Fa retries
60with the number of built-in UV retries left in
61.Fa dev
62before built-in UV is disabled, where
63.Fa retries
64is an addressable pointer.
65.Pp
66The
67.Fn fido_dev_reset
68function performs a reset on
69.Fa dev ,
70resetting the device's PIN and erasing credentials stored on the
71device.
72.Pp
73Please note that
74.Fn fido_dev_set_pin ,
75.Fn fido_dev_get_retry_count ,
76.Fn fido_dev_get_uv_retry_count ,
77and
78.Fn fido_dev_reset
79are synchronous and will block if necessary.
80.Sh RETURN VALUES
81The error codes returned by
82.Fn fido_dev_set_pin ,
83.Fn fido_dev_get_retry_count ,
84.Fn fido_dev_get_uv_retry_count ,
85and
86.Fn fido_dev_reset
87are defined in
88.In fido/err.h .
89On success,
90.Dv FIDO_OK
91is returned.
92.Sh CAVEATS
93Regarding
94.Fn fido_dev_reset ,
95the actual user-flow to perform a reset is outside the scope of the
96FIDO2 specification, and may therefore vary depending on the
97authenticator.
98Yubico authenticators will return
99.Dv FIDO_ERR_NOT_ALLOWED
100if a reset is issued later than 5 seconds after power-up, and
101.Dv FIDO_ERR_ACTION_TIMEOUT
102if the user fails to confirm the reset by touching the key
103within 30 seconds.
104