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