1.\" Copyright (c) 2018-2022 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: April 22 2022 $ 29.Dt FIDO_CBOR_INFO_NEW 3 30.Os 31.Sh NAME 32.Nm fido_cbor_info_new , 33.Nm fido_cbor_info_free , 34.Nm fido_dev_get_cbor_info , 35.Nm fido_cbor_info_aaguid_ptr , 36.Nm fido_cbor_info_extensions_ptr , 37.Nm fido_cbor_info_protocols_ptr , 38.Nm fido_cbor_info_transports_ptr , 39.Nm fido_cbor_info_versions_ptr , 40.Nm fido_cbor_info_options_name_ptr , 41.Nm fido_cbor_info_options_value_ptr , 42.Nm fido_cbor_info_algorithm_type , 43.Nm fido_cbor_info_algorithm_cose , 44.Nm fido_cbor_info_algorithm_count , 45.Nm fido_cbor_info_certs_name_ptr , 46.Nm fido_cbor_info_certs_value_ptr , 47.Nm fido_cbor_info_certs_len , 48.Nm fido_cbor_info_aaguid_len , 49.Nm fido_cbor_info_extensions_len , 50.Nm fido_cbor_info_protocols_len , 51.Nm fido_cbor_info_transports_len , 52.Nm fido_cbor_info_versions_len , 53.Nm fido_cbor_info_options_len , 54.Nm fido_cbor_info_maxmsgsiz , 55.Nm fido_cbor_info_maxcredbloblen , 56.Nm fido_cbor_info_maxcredcntlst , 57.Nm fido_cbor_info_maxcredidlen , 58.Nm fido_cbor_info_maxlargeblob , 59.Nm fido_cbor_info_maxrpid_minpinlen , 60.Nm fido_cbor_info_minpinlen , 61.Nm fido_cbor_info_fwversion , 62.Nm fido_cbor_info_uv_attempts , 63.Nm fido_cbor_info_uv_modality , 64.Nm fido_cbor_info_rk_remaining , 65.Nm fido_cbor_info_new_pin_required 66.Nd FIDO2 CBOR Info API 67.Sh SYNOPSIS 68.In fido.h 69.Ft fido_cbor_info_t * 70.Fn fido_cbor_info_new "void" 71.Ft void 72.Fn fido_cbor_info_free "fido_cbor_info_t **ci_p" 73.Ft int 74.Fn fido_dev_get_cbor_info "fido_dev_t *dev" "fido_cbor_info_t *ci" 75.Ft const unsigned char * 76.Fn fido_cbor_info_aaguid_ptr "const fido_cbor_info_t *ci" 77.Ft char ** 78.Fn fido_cbor_info_extensions_ptr "const fido_cbor_info_t *ci" 79.Ft const uint8_t * 80.Fn fido_cbor_info_protocols_ptr "const fido_cbor_info_t *ci" 81.Ft char ** 82.Fn fido_cbor_info_transports_ptr "const fido_cbor_info_t *ci" 83.Ft char ** 84.Fn fido_cbor_info_versions_ptr "const fido_cbor_info_t *ci" 85.Ft char ** 86.Fn fido_cbor_info_options_name_ptr "const fido_cbor_info_t *ci" 87.Ft const bool * 88.Fn fido_cbor_info_options_value_ptr "const fido_cbor_info_t *ci" 89.Ft const char * 90.Fn fido_cbor_info_algorithm_type "const fido_cbor_info_t *ci" "size_t idx" 91.Ft int 92.Fn fido_cbor_info_algorithm_cose "const fido_cbor_info_t *ci" "size_t idx" 93.Ft size_t 94.Fn fido_cbor_info_algorithm_count "const fido_cbor_info_t *ci" 95.Ft char ** 96.Fn fido_cbor_info_certs_name_ptr "const fido_cbor_info_t *ci" 97.Ft const uint64_t * 98.Fn fido_cbor_info_certs_value_ptr "const fido_cbor_info_t *ci" 99.Ft size_t 100.Fn fido_cbor_info_certs_len "const fido_cbor_info_t *ci" 101.Ft size_t 102.Fn fido_cbor_info_aaguid_len "const fido_cbor_info_t *ci" 103.Ft size_t 104.Fn fido_cbor_info_extensions_len "const fido_cbor_info_t *ci" 105.Ft size_t 106.Fn fido_cbor_info_protocols_len "const fido_cbor_info_t *ci" 107.Ft size_t 108.Fn fido_cbor_info_transports_len "const fido_cbor_info_t *ci" 109.Ft size_t 110.Fn fido_cbor_info_versions_len "const fido_cbor_info_t *ci" 111.Ft size_t 112.Fn fido_cbor_info_options_len "const fido_cbor_info_t *ci" 113.Ft uint64_t 114.Fn fido_cbor_info_maxmsgsiz "const fido_cbor_info_t *ci" 115.Ft uint64_t 116.Fn fido_cbor_info_maxcredbloblen "const fido_cbor_info_t *ci" 117.Ft uint64_t 118.Fn fido_cbor_info_maxcredcntlst "const fido_cbor_info_t *ci" 119.Ft uint64_t 120.Fn fido_cbor_info_maxcredidlen "const fido_cbor_info_t *ci" 121.Ft uint64_t 122.Fn fido_cbor_info_maxlargeblob "const fido_cbor_info_t *ci" 123.Ft uint64_t 124.Fn fido_cbor_info_maxrpid_minpinlen "const fido_cbor_info_t *ci" 125.Ft uint64_t 126.Fn fido_cbor_info_minpinlen "const fido_cbor_info_t *ci" 127.Ft uint64_t 128.Fn fido_cbor_info_fwversion "const fido_cbor_info_t *ci" 129.Ft uint64_t 130.Fn fido_cbor_info_uv_attempts "const fido_cbor_info_t *ci" 131.Ft uint64_t 132.Fn fido_cbor_info_uv_modality "const fido_cbor_info_t *ci" 133.Ft int64_t 134.Fn fido_cbor_info_rk_remaining "const fido_cbor_info_t *ci" 135.Ft bool 136.Fn fido_cbor_info_new_pin_required "const fido_cbor_info_t *ci" 137.Sh DESCRIPTION 138The 139.Fn fido_cbor_info_new 140function returns a pointer to a newly allocated, empty 141.Vt fido_cbor_info_t 142type. 143If memory cannot be allocated, NULL is returned. 144.Pp 145The 146.Fn fido_cbor_info_free 147function releases the memory backing 148.Fa *ci_p , 149where 150.Fa *ci_p 151must have been previously allocated by 152.Fn fido_cbor_info_new . 153On return, 154.Fa *ci_p 155is set to NULL. 156Either 157.Fa ci_p 158or 159.Fa *ci_p 160may be NULL, in which case 161.Fn fido_cbor_info_free 162is a NOP. 163.Pp 164The 165.Fn fido_dev_get_cbor_info 166function transmits a 167.Dv CTAP_CBOR_GETINFO 168command to 169.Fa dev 170and fills 171.Fa ci 172with attributes retrieved from the command's response. 173The 174.Fn fido_dev_get_cbor_info 175function may block. 176.Pp 177The 178.Fn fido_cbor_info_aaguid_ptr , 179.Fn fido_cbor_info_extensions_ptr , 180.Fn fido_cbor_info_protocols_ptr , 181.Fn fido_cbor_info_transports_ptr , 182and 183.Fn fido_cbor_info_versions_ptr 184functions return pointers to the authenticator attestation GUID, 185supported extensions, PIN protocol, transports, and CTAP version 186strings of 187.Fa ci . 188The corresponding length of a given attribute can be 189obtained by 190.Fn fido_cbor_info_aaguid_len , 191.Fn fido_cbor_info_extensions_len , 192.Fn fido_cbor_info_protocols_len , 193.Fn fido_cbor_info_transports_len , 194or 195.Fn fido_cbor_info_versions_len . 196.Pp 197The 198.Fn fido_cbor_info_options_name_ptr 199and 200.Fn fido_cbor_info_options_value_ptr 201functions return pointers to the array of option names and their 202respective values 203in 204.Fa ci . 205The length of the options array is returned by 206.Fn fido_cbor_info_options_len . 207.Pp 208The 209.Fn fido_cbor_info_algorithm_count 210function returns the number of supported algorithms in 211.Fa ci . 212The 213.Fn fido_cbor_info_algorithm_cose 214function returns the COSE identifier of algorithm 215.Fa idx 216in 217.Fa ci , 218or 0 if the COSE identifier is unknown or unset. 219The 220.Fn fido_cbor_info_algorithm_type 221function returns the type of algorithm 222.Fa idx 223in 224.Fa ci , 225or NULL if the type is unset. 226Please note that the first algorithm in 227.Fa ci 228has an 229.Fa idx 230(index) value of 0. 231.Pp 232The 233.Fn fido_cbor_info_certs_name_ptr 234and 235.Fn fido_cbor_info_certs_value_ptr 236functions return pointers to the array of certification names and their 237respective values 238in 239.Fa ci . 240The length of the certifications array is returned by 241.Fn fido_cbor_info_certs_len . 242.Pp 243The 244.Fn fido_cbor_info_maxmsgsiz 245function returns the maximum message size attribute of 246.Fa ci . 247.Pp 248The 249.Fn fido_cbor_info_maxcredbloblen 250function returns the maximum 251.Dq credBlob 252length in bytes supported by the authenticator as reported in 253.Fa ci . 254.Pp 255The 256.Fn fido_cbor_info_maxcredcntlst 257function returns the maximum supported number of credentials in 258a single credential ID list as reported in 259.Fa ci . 260.Pp 261The 262.Fn fido_cbor_info_maxcredidlen 263function returns the maximum supported length of a credential ID 264as reported in 265.Fa ci . 266.Pp 267The 268.Fn fido_cbor_info_maxrpid_minpinlen 269function returns the maximum number of RP IDs that may be passed to 270.Xr fido_dev_set_pin_minlen_rpid 3 , 271as reported in 272.Fa ci . 273The minimum PIN length attribute is a CTAP 2.1 addition. 274If the attribute is not advertised by the authenticator, the 275.Fn fido_cbor_info_maxrpid_minpinlen 276function returns zero. 277.Pp 278The 279.Fn fido_cbor_info_maxlargeblob 280function returns the maximum length in bytes of an authenticator's 281serialized largeBlob array as reported in 282.Fa ci . 283.Pp 284The 285.Fn fido_cbor_info_minpinlen 286function returns the minimum PIN length enforced by the 287authenticator as reported in 288.Fa ci . 289The minimum PIN length attribute is a CTAP 2.1 addition. 290If the attribute is not advertised by the authenticator, the 291.Fn fido_cbor_info_minpinlen 292function returns zero. 293.Pp 294The 295.Fn fido_cbor_info_fwversion 296function returns the firmware version attribute of 297.Fa ci . 298.Pp 299The 300.Fn fido_cbor_info_uv_attempts 301function returns the number of UV attempts that the platform may 302attempt before falling back to PIN authentication. 303If 1, then all 304.Xr fido_dev_get_uv_retry_count 3 305retries are handled internally by the authenticator and the 306platform may only attempt non-PIN UV once. 307The UV attempts attribute is a CTAP 2.1 addition. 308If the attribute is not advertised by the authenticator, 309the 310.Fn fido_cbor_info_uv_attempts 311function returns zero. 312.Pp 313The 314.Fn fido_cbor_info_uv_modality 315function returns a bitmask representing different UV modes 316supported by the authenticator, as defined in the FIDO Registry of 317Predefined Values and reported in 318.Fa ci . 319See the 320.Em FIDO_UV_MODE_* 321definitions in 322.In fido/param.h 323for the set of values defined by libfido2 and a brief description 324of each. 325The UV modality attribute is a CTAP 2.1 addition. 326If the attribute is not advertised by the authenticator, the 327.Fn fido_cbor_info_uv_modality 328function returns zero. 329.Pp 330The 331.Fn fido_cbor_info_rk_remaining 332function returns the estimated number of additional 333resident/discoverable credentials that can be stored on the 334authenticator as reported in 335.Fa ci . 336The estimated number of remaining resident credentials is a 337CTAP 2.1 addition. 338If the attribute is not advertised by the authenticator, the 339.Fn fido_cbor_info_rk_remaining 340function returns -1. 341.Pp 342The 343.Fn fido_cbor_info_new_pin_required 344function returns whether a new PIN is required by the authenticator 345as reported in 346.Fa ci . 347If 348.Fn fido_cbor_info_new_pin_required 349returns true, operations requiring PIN authentication will fail 350until a new PIN is set on the authenticator. 351The 352.Xr fido_dev_set_pin 3 353function can be used to set a new PIN. 354.Pp 355A complete example of how to use these functions can be found in the 356.Pa example/info.c 357file shipped with 358.Em libfido2 . 359.Sh RETURN VALUES 360The 361.Fn fido_cbor_info_aaguid_ptr , 362.Fn fido_cbor_info_extensions_ptr , 363.Fn fido_cbor_info_protocols_ptr , 364.Fn fido_cbor_info_transports_ptr , 365.Fn fido_cbor_info_versions_ptr , 366.Fn fido_cbor_info_options_name_ptr , 367and 368.Fn fido_cbor_info_options_value_ptr 369functions return NULL if the respective field in 370.Fa ci 371is absent. 372If not NULL, returned pointers are guaranteed to exist until any 373API function that takes 374.Fa ci 375without the 376.Em const 377qualifier is invoked. 378.Sh SEE ALSO 379.Xr fido_dev_get_uv_retry_count 3 , 380.Xr fido_dev_open 3 , 381.Xr fido_dev_set_pin 3 , 382.Xr fido_dev_set_pin_minlen_rpid 3 383.Rs 384.%D 2021-05-25 385.%O Review Draft, Version 2.2 386.%Q FIDO Alliance 387.%R FIDO Registry of Predefined Values 388.%U https://fidoalliance.org/specs/common-specs/fido-registry-v2.2-rd-20210525.html 389.Re 390