1.\" Copyright (c) 2018 Yubico AB. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions are 5.\" met: 6.\" 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in 11.\" the documentation and/or other materials provided with the 12.\" distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 15.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 16.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 17.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 18.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 19.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 20.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 24.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" SPDX-License-Identifier: BSD-2-Clause 27.\" 28.Dd $Mdocdate: May 25 2018 $ 29.Dt FIDO_DEV_OPEN 3 30.Os 31.Sh NAME 32.Nm fido_dev_open , 33.Nm fido_dev_open_with_info , 34.Nm fido_dev_close , 35.Nm fido_dev_cancel , 36.Nm fido_dev_new , 37.Nm fido_dev_new_with_info , 38.Nm fido_dev_free , 39.Nm fido_dev_force_fido2 , 40.Nm fido_dev_force_u2f , 41.Nm fido_dev_is_fido2 , 42.Nm fido_dev_is_winhello , 43.Nm fido_dev_supports_credman , 44.Nm fido_dev_supports_cred_prot , 45.Nm fido_dev_supports_permissions , 46.Nm fido_dev_supports_pin , 47.Nm fido_dev_supports_uv , 48.Nm fido_dev_has_pin , 49.Nm fido_dev_has_uv , 50.Nm fido_dev_protocol , 51.Nm fido_dev_build , 52.Nm fido_dev_flags , 53.Nm fido_dev_major , 54.Nm fido_dev_minor 55.Nd FIDO2 device open/close and related functions 56.Sh SYNOPSIS 57.In fido.h 58.Ft int 59.Fn fido_dev_open "fido_dev_t *dev" "const char *path" 60.Ft int 61.Fn fido_dev_open_with_info "fido_dev_t *dev" 62.Ft int 63.Fn fido_dev_close "fido_dev_t *dev" 64.Ft int 65.Fn fido_dev_cancel "fido_dev_t *dev" 66.Ft fido_dev_t * 67.Fn fido_dev_new "void" 68.Ft fido_dev_t * 69.Fn fido_dev_new_with_info "const fido_dev_info_t *" 70.Ft void 71.Fn fido_dev_free "fido_dev_t **dev_p" 72.Ft void 73.Fn fido_dev_force_fido2 "fido_dev_t *dev" 74.Ft void 75.Fn fido_dev_force_u2f "fido_dev_t *dev" 76.Ft bool 77.Fn fido_dev_is_fido2 "const fido_dev_t *dev" 78.Ft bool 79.Fn fido_dev_is_winhello "const fido_dev_t *dev" 80.Ft bool 81.Fn fido_dev_supports_credman "const fido_dev_t *dev" 82.Ft bool 83.Fn fido_dev_supports_cred_prot "const fido_dev_t *dev" 84.Ft bool 85.Fn fido_dev_supports_permissions "const fido_dev_t *dev" 86.Ft bool 87.Fn fido_dev_supports_pin "const fido_dev_t *dev" 88.Ft bool 89.Fn fido_dev_supports_uv "const fido_dev_t *dev" 90.Ft bool 91.Fn fido_dev_has_pin "const fido_dev_t *dev" 92.Ft bool 93.Fn fido_dev_has_uv "const fido_dev_t *dev" 94.Ft uint8_t 95.Fn fido_dev_protocol "const fido_dev_t *dev" 96.Ft uint8_t 97.Fn fido_dev_build "const fido_dev_t *dev" 98.Ft uint8_t 99.Fn fido_dev_flags "const fido_dev_t *dev" 100.Ft uint8_t 101.Fn fido_dev_major "const fido_dev_t *dev" 102.Ft uint8_t 103.Fn fido_dev_minor "const fido_dev_t *dev" 104.Sh DESCRIPTION 105The 106.Fn fido_dev_open 107function opens the device pointed to by 108.Fa path , 109where 110.Fa dev 111is a freshly allocated or otherwise closed 112.Vt fido_dev_t . 113If 114.Fa dev 115claims to be FIDO2, 116.Em libfido2 117will attempt to speak FIDO2 to 118.Fa dev . 119If that fails, 120.Em libfido2 121will fallback to U2F unless the 122.Dv FIDO_DISABLE_U2F_FALLBACK 123flag was set in 124.Xr fido_init 3 . 125.Pp 126The 127.Fn fido_dev_open_with_info 128function opens 129.Fa dev 130as previously allocated using 131.Fn fido_dev_new_with_info . 132.Pp 133The 134.Fn fido_dev_close 135function closes the device represented by 136.Fa dev . 137If 138.Fa dev 139is already closed, 140.Fn fido_dev_close 141is a NOP. 142.Pp 143The 144.Fn fido_dev_cancel 145function cancels any pending requests on 146.Fa dev . 147.Pp 148The 149.Fn fido_dev_new 150function returns a pointer to a newly allocated, empty 151.Vt fido_dev_t . 152If memory cannot be allocated, NULL is returned. 153.Pp 154The 155.Fn fido_dev_new_with_info 156function returns a pointer to a newly allocated 157.Vt fido_dev_t 158with 159.Vt fido_dev_info_t 160parameters, for use with 161.Xr fido_dev_info_manifest 3 162and 163.Fn fido_dev_open_with_info . 164If memory cannot be allocated, NULL is returned. 165.Pp 166The 167.Fn fido_dev_free 168function releases the memory backing 169.Fa *dev_p , 170where 171.Fa *dev_p 172must have been previously allocated by 173.Fn fido_dev_new . 174On return, 175.Fa *dev_p 176is set to NULL. 177Either 178.Fa dev_p 179or 180.Fa *dev_p 181may be NULL, in which case 182.Fn fido_dev_free 183is a NOP. 184.Pp 185The 186.Fn fido_dev_force_fido2 187function can be used to force CTAP2 communication with 188.Fa dev , 189where 190.Fa dev 191is an open device. 192.Pp 193The 194.Fn fido_dev_force_u2f 195function can be used to force CTAP1 (U2F) communication with 196.Fa dev , 197where 198.Fa dev 199is an open device. 200.Pp 201The 202.Fn fido_dev_is_fido2 203function returns 204.Dv true 205if 206.Fa dev 207is a FIDO2 device. 208.Pp 209The 210.Fn fido_dev_is_winhello 211function returns 212.Dv true 213if 214.Fa dev 215is a Windows Hello device. 216.Pp 217The 218.Fn fido_dev_supports_credman 219function returns 220.Dv true 221if 222.Fa dev 223supports CTAP 2.1 Credential Management. 224.Pp 225The 226.Fn fido_dev_supports_cred_prot 227function returns 228.Dv true 229if 230.Fa dev 231supports CTAP 2.1 Credential Protection. 232.Pp 233The 234.Fn fido_dev_supports_permissions 235function returns 236.Dv true 237if 238.Fa dev 239supports CTAP 2.1 UV token permissions. 240.Pp 241The 242.Fn fido_dev_supports_pin 243function returns 244.Dv true 245if 246.Fa dev 247supports CTAP 2.0 Client PINs. 248.Pp 249The 250.Fn fido_dev_supports_uv 251function returns 252.Dv true 253if 254.Fa dev 255supports a built-in user verification method. 256.Pp 257The 258.Fn fido_dev_has_pin 259function returns 260.Dv true 261if 262.Fa dev 263has a CTAP 2.0 Client PIN set. 264.Pp 265The 266.Fn fido_dev_has_uv 267function returns 268.Dv true 269if 270.Fa dev 271supports built-in user verification and its user verification 272feature is configured. 273.Pp 274The 275.Fn fido_dev_protocol 276function returns the CTAPHID protocol version identifier of 277.Fa dev . 278.Pp 279The 280.Fn fido_dev_build 281function returns the CTAPHID build version number of 282.Fa dev . 283.Pp 284The 285.Fn fido_dev_flags 286function returns the CTAPHID capabilities flags of 287.Fa dev . 288.Pp 289The 290.Fn fido_dev_major 291function returns the CTAPHID major version number of 292.Fa dev . 293.Pp 294The 295.Fn fido_dev_minor 296function returns the CTAPHID minor version number of 297.Fa dev . 298.Pp 299For the format and meaning of the CTAPHID parameters returned by 300functions above, please refer to the FIDO Client to Authenticator 301Protocol (CTAP) specification. 302.Sh RETURN VALUES 303On success, 304.Fn fido_dev_open , 305.Fn fido_dev_open_with_info , 306and 307.Fn fido_dev_close 308return 309.Dv FIDO_OK . 310On error, a different error code defined in 311.In fido/err.h 312is returned. 313.Sh SEE ALSO 314.Xr fido_dev_info_manifest 3 , 315.Xr fido_dev_set_io_functions 3 , 316.Xr fido_init 3 317