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