1.\" Copyright (c) 2018-2021 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: May 23 2018 $ 29.Dt FIDO_CRED_NEW 3 30.Os 31.Sh NAME 32.Nm fido_cred_new , 33.Nm fido_cred_free , 34.Nm fido_cred_pin_minlen , 35.Nm fido_cred_prot , 36.Nm fido_cred_fmt , 37.Nm fido_cred_rp_id , 38.Nm fido_cred_rp_name , 39.Nm fido_cred_user_name , 40.Nm fido_cred_display_name , 41.Nm fido_cred_authdata_ptr , 42.Nm fido_cred_authdata_raw_ptr , 43.Nm fido_cred_clientdata_hash_ptr , 44.Nm fido_cred_id_ptr , 45.Nm fido_cred_aaguid_ptr , 46.Nm fido_cred_largeblob_key_ptr , 47.Nm fido_cred_pubkey_ptr , 48.Nm fido_cred_sig_ptr , 49.Nm fido_cred_user_id_ptr , 50.Nm fido_cred_x5c_ptr , 51.Nm fido_cred_attstmt_ptr , 52.Nm fido_cred_authdata_len , 53.Nm fido_cred_authdata_raw_len , 54.Nm fido_cred_clientdata_hash_len , 55.Nm fido_cred_id_len , 56.Nm fido_cred_aaguid_len , 57.Nm fido_cred_largeblob_key_len , 58.Nm fido_cred_pubkey_len , 59.Nm fido_cred_sig_len , 60.Nm fido_cred_user_id_len , 61.Nm fido_cred_x5c_len , 62.Nm fido_cred_attstmt_len , 63.Nm fido_cred_type , 64.Nm fido_cred_flags , 65.Nm fido_cred_sigcount 66.Nd FIDO2 credential API 67.Sh SYNOPSIS 68.In fido.h 69.Ft fido_cred_t * 70.Fn fido_cred_new "void" 71.Ft void 72.Fn fido_cred_free "fido_cred_t **cred_p" 73.Ft size_t 74.Fn fido_cred_pin_minlen "const fido_cred_t *cred" 75.Ft int 76.Fn fido_cred_prot "const fido_cred_t *cred" 77.Ft const char * 78.Fn fido_cred_fmt "const fido_cred_t *cred" 79.Ft const char * 80.Fn fido_cred_rp_id "const fido_cred_t *cred" 81.Ft const char * 82.Fn fido_cred_rp_name "const fido_cred_t *cred" 83.Ft const char * 84.Fn fido_cred_user_name "const fido_cred_t *cred" 85.Ft const char * 86.Fn fido_cred_display_name "const fido_cred_t *cred" 87.Ft const unsigned char * 88.Fn fido_cred_authdata_ptr "const fido_cred_t *cred" 89.Ft const unsigned char * 90.Fn fido_cred_authdata_raw_ptr "const fido_cred_t *cred" 91.Ft const unsigned char * 92.Fn fido_cred_clientdata_hash_ptr "const fido_cred_t *cred" 93.Ft const unsigned char * 94.Fn fido_cred_id_ptr "const fido_cred_t *cred" 95.Ft const unsigned char * 96.Fn fido_cred_aaguid_ptr "const fido_cred_t *cred" 97.Ft const unsigned char * 98.Fn fido_cred_largeblob_key_ptr "const fido_cred_t *cred" 99.Ft const unsigned char * 100.Fn fido_cred_pubkey_ptr "const fido_cred_t *cred" 101.Ft const unsigned char * 102.Fn fido_cred_sig_ptr "const fido_cred_t *cred" 103.Ft const unsigned char * 104.Fn fido_cred_user_id_ptr "const fido_cred_t *cred" 105.Ft const unsigned char * 106.Fn fido_cred_x5c_ptr "const fido_cred_t *cred" 107.Ft const unsigned char * 108.Fn fido_cred_attstmt_ptr "const fido_cred_t *cred" 109.Ft size_t 110.Fn fido_cred_authdata_len "const fido_cred_t *cred" 111.Ft size_t 112.Fn fido_cred_authdata_raw_len "const fido_cred_t *cred" 113.Ft size_t 114.Fn fido_cred_clientdata_hash_len "const fido_cred_t *cred" 115.Ft size_t 116.Fn fido_cred_id_len "const fido_cred_t *cred" 117.Ft size_t 118.Fn fido_cred_aaguid_len "const fido_cred_t *cred" 119.Ft size_t 120.Fn fido_cred_largeblob_key_len "const fido_cred_t *cred" 121.Ft size_t 122.Fn fido_cred_pubkey_len "const fido_cred_t *cred" 123.Ft size_t 124.Fn fido_cred_sig_len "const fido_cred_t *cred" 125.Ft size_t 126.Fn fido_cred_user_id_len "const fido_cred_t *cred" 127.Ft size_t 128.Fn fido_cred_x5c_len "const fido_cred_t *cred" 129.Ft size_t 130.Fn fido_cred_attstmt_len "const fido_cred_t *cred" 131.Ft int 132.Fn fido_cred_type "const fido_cred_t *cred" 133.Ft uint8_t 134.Fn fido_cred_flags "const fido_cred_t *cred" 135.Ft uint32_t 136.Fn fido_cred_sigcount "const fido_cred_t *cred" 137.Sh DESCRIPTION 138FIDO2 credentials are abstracted in 139.Em libfido2 140by the 141.Vt fido_cred_t 142type. 143The functions described in this page allow a 144.Vt fido_cred_t 145type to be allocated, deallocated, and inspected. 146For other operations on 147.Vt fido_cred_t , 148please refer to 149.Xr fido_cred_set_authdata 3 , 150.Xr fido_cred_exclude 3 , 151.Xr fido_cred_verify 3 , 152and 153.Xr fido_dev_make_cred 3 . 154.Pp 155The 156.Fn fido_cred_new 157function returns a pointer to a newly allocated, empty 158.Vt fido_cred_t 159type. 160If memory cannot be allocated, NULL is returned. 161.Pp 162The 163.Fn fido_cred_free 164function releases the memory backing 165.Fa *cred_p , 166where 167.Fa *cred_p 168must have been previously allocated by 169.Fn fido_cred_new . 170On return, 171.Fa *cred_p 172is set to NULL. 173Either 174.Fa cred_p 175or 176.Fa *cred_p 177may be NULL, in which case 178.Fn fido_cred_free 179is a NOP. 180.Pp 181If the CTAP 2.1 182.Dv FIDO_EXT_MINPINLEN 183extension is enabled on 184.Fa cred , 185then the 186.Fn fido_cred_pin_minlen 187function returns the minimum PIN length of 188.Fa cred . 189Otherwise, 190.Fn fido_cred_pin_minlen 191returns zero. 192See 193.Xr fido_cred_set_pin_minlen 3 194on how to enable this extension. 195.Pp 196If the CTAP 2.1 197.Dv FIDO_EXT_CRED_PROTECT 198extension is enabled on 199.Fa cred , 200then the 201.Fn fido_cred_prot 202function returns the protection of 203.Fa cred . 204Otherwise, 205.Fn fido_cred_prot 206returns zero. 207See 208.Xr fido_cred_set_prot 3 209for the protection policies understood by 210.Em libfido2 . 211.Pp 212The 213.Fn fido_cred_fmt 214function returns a pointer to a NUL-terminated string containing 215the attestation statement format identifier of 216.Fa cred , 217or NULL if 218.Fa cred 219does not have a format set. 220.Pp 221The 222.Fn fido_cred_rp_id , 223.Fn fido_cred_rp_name , 224.Fn fido_cred_user_name , 225and 226.Fn fido_cred_display_name 227functions return pointers to NUL-terminated strings holding the 228relying party ID, relying party name, user name, and user display 229name attributes of 230.Fa cred , 231or NULL if the respective entry is not set. 232.Pp 233The 234.Fn fido_cred_authdata_ptr , 235.Fn fido_cred_authdata_raw_ptr , 236.Fn fido_cred_clientdata_hash_ptr , 237.Fn fido_cred_id_ptr , 238.Fn fido_cred_aaguid_ptr , 239.Fn fido_cred_largeblob_key_ptr , 240.Fn fido_cred_pubkey_ptr , 241.Fn fido_cred_sig_ptr , 242.Fn fido_cred_user_id_ptr , 243.Fn fido_cred_x5c_ptr , 244and 245.Fn fido_cred_attstmt_ptr 246functions return pointers to the CBOR-encoded and raw authenticator 247data, client data hash, ID, authenticator attestation GUID, 248.Dq largeBlobKey , 249public key, signature, user ID, x509 certificate, and attestation 250statement parts of 251.Fa cred , 252or NULL if the respective entry is not set. 253.Pp 254The corresponding length can be obtained by 255.Fn fido_cred_authdata_len , 256.Fn fido_cred_authdata_raw_len , 257.Fn fido_cred_clientdata_hash_len , 258.Fn fido_cred_id_len , 259.Fn fido_cred_aaguid_len , 260.Fn fido_cred_largeblob_key_len , 261.Fn fido_cred_pubkey_len , 262.Fn fido_cred_sig_len , 263.Fn fido_cred_user_id_len , 264.Fn fido_cred_x5c_len , 265and 266.Fn fido_cred_attstmt_len . 267.Pp 268The authenticator data, x509 certificate, and signature parts of a 269credential are typically passed to a FIDO2 server for verification. 270.Pp 271The 272.Fn fido_cred_type 273function returns the COSE algorithm of 274.Fa cred . 275.Pp 276The 277.Fn fido_cred_flags 278function returns the authenticator data flags of 279.Fa cred . 280.Pp 281The 282.Fn fido_cred_sigcount 283function returns the authenticator data signature counter of 284.Fa cred . 285.Sh RETURN VALUES 286The authenticator data returned by 287.Fn fido_cred_authdata_ptr 288is a CBOR-encoded byte string, as obtained from the authenticator. 289To obtain the decoded byte string, use 290.Fn fido_cred_authdata_raw_ptr . 291.Pp 292If not NULL, pointers returned by 293.Fn fido_cred_fmt , 294.Fn fido_cred_authdata_ptr , 295.Fn fido_cred_clientdata_hash_ptr , 296.Fn fido_cred_id_ptr , 297.Fn fido_cred_aaguid_ptr , 298.Fn fido_cred_largeblob_key_ptr , 299.Fn fido_cred_pubkey_ptr , 300.Fn fido_cred_sig_ptr , 301and 302.Fn fido_cred_x5c_ptr 303are guaranteed to exist until any API function that takes 304.Fa cred 305without the 306.Em const 307qualifier is invoked. 308.Sh SEE ALSO 309.Xr fido_cred_exclude 3 , 310.Xr fido_cred_set_authdata 3 , 311.Xr fido_cred_set_pin_minlen 3 , 312.Xr fido_cred_set_prot 3 , 313.Xr fido_cred_verify 3 , 314.Xr fido_credman_metadata_new 3 , 315.Xr fido_dev_largeblob_get 3 , 316.Xr fido_dev_make_cred 3 317