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: March 30 2022 $ 29.Dt FIDO_DEV_INFO_MANIFEST 3 30.Os 31.Sh NAME 32.Nm fido_dev_info_manifest , 33.Nm fido_dev_info_new , 34.Nm fido_dev_info_free , 35.Nm fido_dev_info_ptr , 36.Nm fido_dev_info_path , 37.Nm fido_dev_info_product , 38.Nm fido_dev_info_vendor , 39.Nm fido_dev_info_manufacturer_string , 40.Nm fido_dev_info_product_string , 41.Nm fido_dev_info_set 42.Nd FIDO2 device discovery functions 43.Sh SYNOPSIS 44.In fido.h 45.Ft int 46.Fn fido_dev_info_manifest "fido_dev_info_t *devlist" "size_t ilen" "size_t *olen" 47.Ft fido_dev_info_t * 48.Fn fido_dev_info_new "size_t n" 49.Ft void 50.Fn fido_dev_info_free "fido_dev_info_t **devlist_p" "size_t n" 51.Ft const fido_dev_info_t * 52.Fn fido_dev_info_ptr "const fido_dev_info_t *devlist" "size_t i" 53.Ft const char * 54.Fn fido_dev_info_path "const fido_dev_info_t *di" 55.Ft int16_t 56.Fn fido_dev_info_product "const fido_dev_info_t *di" 57.Ft int16_t 58.Fn fido_dev_info_vendor "const fido_dev_info_t *di" 59.Ft const char * 60.Fn fido_dev_info_manufacturer_string "const fido_dev_info_t *di" 61.Ft const char * 62.Fn fido_dev_info_product_string "const fido_dev_info_t *di" 63.Ft int 64.Fn fido_dev_info_set "fido_dev_info_t *devlist" "size_t i" "const char *path" "const char *manufacturer" "const char *product" "const fido_dev_io_t *io" "const fido_dev_transport_t *transport" 65.Sh DESCRIPTION 66The 67.Fn fido_dev_info_manifest 68function fills 69.Fa devlist 70with up to 71.Fa ilen 72FIDO2 devices found by the underlying operating system. 73Currently only USB HID devices are supported. 74The number of discovered devices is returned in 75.Fa olen , 76where 77.Fa olen 78is an addressable pointer. 79.Pp 80The 81.Fn fido_dev_info_new 82function returns a pointer to a newly allocated, empty device list 83with 84.Fa n 85available slots. 86If memory is not available, NULL is returned. 87.Pp 88The 89.Fn fido_dev_info_free 90function releases the memory backing 91.Fa *devlist_p , 92where 93.Fa *devlist_p 94must have been previously allocated by 95.Fn fido_dev_info_new . 96The number 97.Fa n 98of allocated slots must also be provided. 99On return, 100.Fa *devlist_p 101is set to NULL. 102Either 103.Fa devlist_p 104or 105.Fa *devlist_p 106may be NULL, in which case 107.Fn fido_dev_info_free 108is a NOP. 109.Pp 110The 111.Fn fido_dev_info_ptr 112function returns a pointer to slot number 113.Fa i 114of 115.Fa devlist . 116It is the caller's responsibility to ensure that 117.Fa i 118is bounded. 119Please note that the first slot has index 0. 120.Pp 121The 122.Fn fido_dev_info_path 123function returns the filesystem path or subsystem-specific identification 124string of 125.Fa di . 126.Pp 127The 128.Fn fido_dev_info_product 129function returns the product ID of 130.Fa di . 131.Pp 132The 133.Fn fido_dev_info_vendor 134function returns the vendor ID of 135.Fa di . 136.Pp 137The 138.Fn fido_dev_info_manufacturer_string 139function returns the manufacturer string of 140.Fa di . 141If 142.Fa di 143does not have an associated manufacturer string, 144.Fn fido_dev_info_manufacturer_string 145returns an empty string. 146.Pp 147The 148.Fn fido_dev_info_product_string 149function returns the product string of 150.Fa di . 151If 152.Fa di 153does not have an associated product string, 154.Fn fido_dev_info_product_string 155returns an empty string. 156.Pp 157An example of how to use the functions described in this document 158can be found in the 159.Pa examples/manifest.c 160file shipped with 161.Em libfido2 . 162.Pp 163The 164.Fn fido_dev_info_set 165function initializes an entry in a device list allocated by 166.Fn fido_dev_info_new 167with the specified path, manufacturer, and product strings, and with 168the specified I/O handlers and, optionally, transport functions, as 169described in 170.Xr fido_dev_set_io_functions 3 . 171The 172.Fa io 173argument must be specified; the 174.Fa transport 175argument may be 176.Dv NULL . 177The path, I/O handlers, and transport functions will be used 178automatically by 179.Xr fido_dev_new_with_info 3 180and 181.Xr fido_dev_open_with_info 3 . 182An application can use this, for example, to substitute mock FIDO2 183devices in testing for the real ones that 184.Fn fido_dev_info_manifest 185would discover. 186.Sh RETURN VALUES 187The 188.Fn fido_dev_info_manifest 189function always returns 190.Dv FIDO_OK . 191If a discovery error occurs, the 192.Fa olen 193pointer is set to 0. 194.Pp 195On success, the 196.Fn fido_dev_info_set 197function returns 198.Dv FIDO_OK . 199On error, a different error code defined in 200.In fido/err.h 201is returned. 202.Pp 203The pointers returned by 204.Fn fido_dev_info_ptr , 205.Fn fido_dev_info_path , 206.Fn fido_dev_info_manufacturer_string , 207and 208.Fn fido_dev_info_product_string 209are guaranteed to exist until 210.Fn fido_dev_info_free 211is called on the corresponding device list. 212