contrib/libfido2/man/fido_dev_set_pin.3

   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
  25 The
  26 .Fn fido_dev_set_pin
  27 function sets the PIN of device
  28 .Fa dev
  29 to
  30 .Fa pin ,
  31 where
  32 .Fa pin
  33 is a NUL-terminated UTF-8 string.
  34 If
  35 .Fa oldpin
  36 is not NULL, the device's PIN is changed from
  37 .Fa oldpin
  38 to
  39 .Fa pin ,
  40 where
  41 .Fa pin
  42 and
  43 .Fa oldpin
  44 are NUL-terminated UTF-8 strings.
  45 .Pp
  46 The
  47 .Fn fido_dev_get_retry_count
  48 function fills
  49 .Fa retries
  50 with the number of PIN retries left in
  51 .Fa dev
  52 before lock-out, where
  53 .Fa retries
  54 is an addressable pointer.
  55 .Pp
  56 The
  57 .Fn fido_dev_get_uv_retry_count
  58 function fills
  59 .Fa retries
  60 with the number of built-in UV retries left in
  61 .Fa dev
  62 before built-in UV is disabled, where
  63 .Fa retries
  64 is an addressable pointer.
  65 .Pp
  66 The
  67 .Fn fido_dev_reset
  68 function performs a reset on
  69 .Fa dev ,
  70 resetting the device's PIN and erasing credentials stored on the
  71 device.
  72 .Pp
  73 Please note that
  74 .Fn fido_dev_set_pin ,
  75 .Fn fido_dev_get_retry_count ,
  76 .Fn fido_dev_get_uv_retry_count ,
  77 and
  78 .Fn fido_dev_reset
  79 are synchronous and will block if necessary.
  80 .Sh RETURN VALUES
  81 The 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 ,
  85 and
  86 .Fn fido_dev_reset
  87 are defined in
  88 .In fido/err.h .
  89 On success,
  90 .Dv FIDO_OK
  91 is returned.
  92 .Sh CAVEATS
  93 Regarding
  94 .Fn fido_dev_reset ,
  95 the actual user-flow to perform a reset is outside the scope of the
  96 FIDO2 specification, and may therefore vary depending on the
  97 authenticator.
  98 Yubico authenticators will return
  99 .Dv FIDO_ERR_NOT_ALLOWED
 100 if a reset is issued later than 5 seconds after power-up, and
 101 .Dv FIDO_ERR_ACTION_TIMEOUT
 102 if the user fails to confirm the reset by touching the key
 103 within 30 seconds.