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