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 24 2018 $ 6.Dt FIDO_CBOR_INFO_NEW 3 7.Os 8.Sh NAME 9.Nm fido_cbor_info_new , 10.Nm fido_cbor_info_free , 11.Nm fido_dev_get_cbor_info , 12.Nm fido_cbor_info_aaguid_ptr , 13.Nm fido_cbor_info_extensions_ptr , 14.Nm fido_cbor_info_protocols_ptr , 15.Nm fido_cbor_info_transports_ptr , 16.Nm fido_cbor_info_versions_ptr , 17.Nm fido_cbor_info_options_name_ptr , 18.Nm fido_cbor_info_options_value_ptr , 19.Nm fido_cbor_info_algorithm_type , 20.Nm fido_cbor_info_algorithm_cose , 21.Nm fido_cbor_info_algorithm_count , 22.Nm fido_cbor_info_aaguid_len , 23.Nm fido_cbor_info_extensions_len , 24.Nm fido_cbor_info_protocols_len , 25.Nm fido_cbor_info_transports_len , 26.Nm fido_cbor_info_versions_len , 27.Nm fido_cbor_info_options_len , 28.Nm fido_cbor_info_maxmsgsiz , 29.Nm fido_cbor_info_maxcredbloblen , 30.Nm fido_cbor_info_maxcredcntlst , 31.Nm fido_cbor_info_maxcredidlen , 32.Nm fido_cbor_info_fwversion 33.Nd FIDO2 CBOR Info API 34.Sh SYNOPSIS 35.In fido.h 36.Ft fido_cbor_info_t * 37.Fn fido_cbor_info_new "void" 38.Ft void 39.Fn fido_cbor_info_free "fido_cbor_info_t **ci_p" 40.Ft int 41.Fn fido_dev_get_cbor_info "fido_dev_t *dev" "fido_cbor_info_t *ci" 42.Ft const unsigned char * 43.Fn fido_cbor_info_aaguid_ptr "const fido_cbor_info_t *ci" 44.Ft char ** 45.Fn fido_cbor_info_extensions_ptr "const fido_cbor_info_t *ci" 46.Ft const uint8_t * 47.Fn fido_cbor_info_protocols_ptr "const fido_cbor_info_t *ci" 48.Ft char ** 49.Fn fido_cbor_info_transports_ptr "const fido_cbor_info_t *ci" 50.Ft char ** 51.Fn fido_cbor_info_versions_ptr "const fido_cbor_info_t *ci" 52.Ft char ** 53.Fn fido_cbor_info_options_name_ptr "const fido_cbor_info_t *ci" 54.Ft const bool * 55.Fn fido_cbor_info_options_value_ptr "const fido_cbor_info_t *ci" 56.Ft const char * 57.Fn fido_cbor_info_algorithm_type "const fido_cbor_info_t *ci" "size_t idx" 58.Ft int 59.Fn fido_cbor_info_algorithm_cose "const fido_cbor_info_t *ci" "size_t idx" 60.Ft size_t 61.Fn fido_cbor_info_algorithm_count "const fido_cbor_info_t *ci" 62.Ft size_t 63.Fn fido_cbor_info_aaguid_len "const fido_cbor_info_t *ci" 64.Ft size_t 65.Fn fido_cbor_info_extensions_len "const fido_cbor_info_t *ci" 66.Ft size_t 67.Fn fido_cbor_info_protocols_len "const fido_cbor_info_t *ci" 68.Ft size_t 69.Fn fido_cbor_info_transports_len "const fido_cbor_info_t *ci" 70.Ft size_t 71.Fn fido_cbor_info_versions_len "const fido_cbor_info_t *ci" 72.Ft size_t 73.Fn fido_cbor_info_options_len "const fido_cbor_info_t *ci" 74.Ft uint64_t 75.Fn fido_cbor_info_maxmsgsiz "const fido_cbor_info_t *ci" 76.Ft uint64_t 77.Fn fido_cbor_info_maxcredbloblen "const fido_cbor_info_t *ci" 78.Ft uint64_t 79.Fn fido_cbor_info_maxcredcntlst "const fido_cbor_info_t *ci" 80.Ft uint64_t 81.Fn fido_cbor_info_maxcredidlen "const fido_cbor_info_t *ci" 82.Ft uint64_t 83.Fn fido_cbor_info_fwversion "const fido_cbor_info_t *ci" 84.Sh DESCRIPTION 85The 86.Fn fido_cbor_info_new 87function returns a pointer to a newly allocated, empty 88.Vt fido_cbor_info_t 89type. 90If memory cannot be allocated, NULL is returned. 91.Pp 92The 93.Fn fido_cbor_info_free 94function releases the memory backing 95.Fa *ci_p , 96where 97.Fa *ci_p 98must have been previously allocated by 99.Fn fido_cbor_info_new . 100On return, 101.Fa *ci_p 102is set to NULL. 103Either 104.Fa ci_p 105or 106.Fa *ci_p 107may be NULL, in which case 108.Fn fido_cbor_info_free 109is a NOP. 110.Pp 111The 112.Fn fido_dev_get_cbor_info 113function transmits a 114.Dv CTAP_CBOR_GETINFO 115command to 116.Fa dev 117and fills 118.Fa ci 119with attributes retrieved from the command's response. 120The 121.Fn fido_dev_get_cbor_info 122function may block. 123.Pp 124The 125.Fn fido_cbor_info_aaguid_ptr , 126.Fn fido_cbor_info_extensions_ptr , 127.Fn fido_cbor_info_protocols_ptr , 128.Fn fido_cbor_info_transports_ptr , 129and 130.Fn fido_cbor_info_versions_ptr 131functions return pointers to the authenticator attestation GUID, 132supported extensions, PIN protocol, transports, and CTAP version 133strings of 134.Fa ci . 135The corresponding length of a given attribute can be 136obtained by 137.Fn fido_cbor_info_aaguid_len , 138.Fn fido_cbor_info_extensions_len , 139.Fn fido_cbor_info_protocols_len , 140.Fn fido_cbor_info_transports_len , 141or 142.Fn fido_cbor_info_versions_len . 143.Pp 144The 145.Fn fido_cbor_info_options_name_ptr 146and 147.Fn fido_cbor_info_options_value_ptr 148functions return pointers to the array of option names and their 149respective values 150in 151.Fa ci . 152The length of the options array is returned by 153.Fn fido_cbor_info_options_len . 154.Pp 155The 156.Fn fido_cbor_info_algorithm_count 157function returns the number of supported algorithms in 158.Fa ci . 159The 160.Fn fido_cbor_info_algorithm_cose 161function returns the COSE identifier of algorithm 162.Fa idx 163in 164.Fa ci , 165or 0 if the COSE identifier is unknown or unset. 166The 167.Fn fido_cbor_info_algorithm_type 168function returns the type of algorithm 169.Fa idx 170in 171.Fa ci , 172or NULL if the type is unset. 173Please note that the first algorithm in 174.Fa ci 175has an 176.Fa idx 177(index) value of 0. 178.Pp 179The 180.Fn fido_cbor_info_maxmsgsiz 181function returns the maximum message size attribute of 182.Fa ci . 183.Pp 184The 185.Fn fido_cbor_info_maxcredbloblen 186function returns the maximum 187.Dq credBlob 188length in bytes supported by the authenticator as reported in 189.Fa ci . 190.Pp 191The 192.Fn fido_cbor_info_maxcredcntlst 193function returns the maximum supported number of credentials in 194a single credential ID list as reported in 195.Fa ci . 196.Pp 197The 198.Fn fido_cbor_info_maxcredidlen 199function returns the maximum supported length of a credential ID 200as reported in 201.Fa ci . 202.Pp 203The 204.Fn fido_cbor_info_fwversion 205function returns the firmware version attribute of 206.Fa ci . 207.Pp 208A complete example of how to use these functions can be found in the 209.Pa example/info.c 210file shipped with 211.Em libfido2 . 212.Sh RETURN VALUES 213The 214.Fn fido_cbor_info_aaguid_ptr , 215.Fn fido_cbor_info_extensions_ptr , 216.Fn fido_cbor_info_protocols_ptr , 217.Fn fido_cbor_info_transports_ptr , 218.Fn fido_cbor_info_versions_ptr , 219.Fn fido_cbor_info_options_name_ptr , 220and 221.Fn fido_cbor_info_options_value_ptr 222functions return NULL if the respective field in 223.Fa ci 224is absent. 225If not NULL, returned pointers are guaranteed to exist until any 226API function that takes 227.Fa ci 228without the 229.Em const 230qualifier is invoked. 231.Sh SEE ALSO 232.Xr fido_dev_open 3 233