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