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