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_ASSERT_NEW 3 7.Os 8.Sh NAME 9.Nm fido_assert_new , 10.Nm fido_assert_free , 11.Nm fido_assert_count , 12.Nm fido_assert_rp_id , 13.Nm fido_assert_user_display_name , 14.Nm fido_assert_user_icon , 15.Nm fido_assert_user_name , 16.Nm fido_assert_authdata_ptr , 17.Nm fido_assert_blob_ptr , 18.Nm fido_assert_clientdata_hash_ptr , 19.Nm fido_assert_hmac_secret_ptr , 20.Nm fido_assert_largeblob_key_ptr , 21.Nm fido_assert_user_id_ptr , 22.Nm fido_assert_sig_ptr , 23.Nm fido_assert_id_ptr , 24.Nm fido_assert_authdata_len , 25.Nm fido_assert_blob_len , 26.Nm fido_assert_clientdata_hash_len , 27.Nm fido_assert_hmac_secret_len , 28.Nm fido_assert_largeblob_key_len , 29.Nm fido_assert_user_id_len , 30.Nm fido_assert_sig_len , 31.Nm fido_assert_id_len , 32.Nm fido_assert_sigcount , 33.Nm fido_assert_flags 34.Nd FIDO2 assertion API 35.Sh SYNOPSIS 36.In fido.h 37.Ft fido_assert_t * 38.Fn fido_assert_new "void" 39.Ft void 40.Fn fido_assert_free "fido_assert_t **assert_p" 41.Ft size_t 42.Fn fido_assert_count "const fido_assert_t *assert" 43.Ft const char * 44.Fn fido_assert_rp_id "const fido_assert_t *assert" 45.Ft const char * 46.Fn fido_assert_user_display_name "const fido_assert_t *assert" "size_t idx" 47.Ft const char * 48.Fn fido_assert_user_icon "const fido_assert_t *assert" "size_t idx" 49.Ft const char * 50.Fn fido_assert_user_name "const fido_assert_t *assert" "size_t idx" 51.Ft const unsigned char * 52.Fn fido_assert_authdata_ptr "const fido_assert_t *assert" "size_t idx" 53.Ft const unsigned char * 54.Fn fido_assert_clientdata_hash_ptr "const fido_assert_t *assert" 55.Ft const unsigned char * 56.Fn fido_assert_blob_ptr "const fido_assert_t *assert" "size_t idx" 57.Ft const unsigned char * 58.Fn fido_assert_hmac_secret_ptr "const fido_assert_t *assert" "size_t idx" 59.Ft const unsigned char * 60.Fn fido_assert_largeblob_key_ptr "const fido_assert_t *assert" "size_t idx" 61.Ft const unsigned char * 62.Fn fido_assert_user_id_ptr "const fido_assert_t *assert" "size_t idx" 63.Ft const unsigned char * 64.Fn fido_assert_sig_ptr "const fido_assert_t *assert" "size_t idx" 65.Ft const unsigned char * 66.Fn fido_assert_id_ptr "const fido_assert_t *assert" "size_t idx" 67.Ft size_t 68.Fn fido_assert_authdata_len "const fido_assert_t *assert" "size_t idx" 69.Ft size_t 70.Fn fido_assert_clientdata_hash_len "const fido_assert_t *assert" 71.Ft size_t 72.Fn fido_assert_blob_len "const fido_assert_t *assert" "size_t idx" 73.Ft size_t 74.Fn fido_assert_hmac_secret_len "const fido_assert_t *assert" "size_t idx" 75.Ft size_t 76.Fn fido_assert_largeblob_key_len "const fido_assert_t *assert" "size_t idx" 77.Ft size_t 78.Fn fido_assert_user_id_len "const fido_assert_t *assert" "size_t idx" 79.Ft size_t 80.Fn fido_assert_sig_len "const fido_assert_t *assert" "size_t idx" 81.Ft size_t 82.Fn fido_assert_id_len "const fido_assert_t *assert" "size_t idx" 83.Ft uint32_t 84.Fn fido_assert_sigcount "const fido_assert_t *assert" "size_t idx" 85.Ft uint8_t 86.Fn fido_assert_flags "const fido_assert_t *assert" "size_t idx" 87.Sh DESCRIPTION 88A FIDO2 assertion is a collection of statements, each statement a 89map between a challenge, a credential, a signature, and ancillary 90attributes. 91In 92.Em libfido2 , 93a FIDO2 assertion is abstracted by the 94.Vt fido_assert_t 95type. 96The functions described in this page allow a 97.Vt fido_assert_t 98type to be allocated, deallocated, and inspected. 99For other operations on 100.Vt fido_assert_t , 101please refer to 102.Xr fido_assert_set_authdata 3 , 103.Xr fido_assert_allow_cred 3 , 104.Xr fido_assert_verify 3 , 105and 106.Xr fido_dev_get_assert 3 . 107.Pp 108The 109.Fn fido_assert_new 110function returns a pointer to a newly allocated, empty 111.Vt fido_assert_t 112type. 113If memory cannot be allocated, NULL is returned. 114.Pp 115The 116.Fn fido_assert_free 117function releases the memory backing 118.Fa *assert_p , 119where 120.Fa *assert_p 121must have been previously allocated by 122.Fn fido_assert_new . 123On return, 124.Fa *assert_p 125is set to NULL. 126Either 127.Fa assert_p 128or 129.Fa *assert_p 130may be NULL, in which case 131.Fn fido_assert_free 132is a NOP. 133.Pp 134The 135.Fn fido_assert_count 136function returns the number of statements in 137.Fa assert . 138.Pp 139The 140.Fn fido_assert_rp_id 141function returns a pointer to a NUL-terminated string holding the 142relying party ID of 143.Fa assert . 144.Pp 145The 146.Fn fido_assert_user_display_name , 147.Fn fido_assert_user_icon , 148and 149.Fn fido_assert_user_name , 150functions return pointers to the user display name, icon, and 151name attributes of statement 152.Fa idx 153in 154.Fa assert . 155If not NULL, the values returned by these functions point to 156NUL-terminated UTF-8 strings. 157.Pp 158The 159.Fn fido_assert_authdata_ptr , 160.Fn fido_assert_clientdata_hash_ptr , 161.Fn fido_assert_id_ptr , 162.Fn fido_assert_user_id_ptr , 163.Fn fido_assert_sig_ptr , 164.Fn fido_assert_sigcount , 165and 166.Fn fido_assert_flags 167functions return pointers to the CBOR-encoded authenticator data, 168client data hash, credential ID, user ID, signature, signature 169count, and authenticator data flags of statement 170.Fa idx 171in 172.Fa assert . 173.Pp 174The 175.Fn fido_assert_hmac_secret_ptr 176function returns a pointer to the hmac-secret attribute of statement 177.Fa idx 178in 179.Fa assert . 180The HMAC Secret Extension 181.Pq hmac-secret 182is a CTAP 2.0 extension. 183Note that the resulting hmac-secret varies according to whether 184user verification was performed by the authenticator. 185.Pp 186The 187.Fn fido_assert_blob_ptr 188and 189.Fn fido_assert_largeblob_key_ptr 190functions return pointers to the 191.Dq credBlob 192and 193.Dq largeBlobKey 194attributes of statement 195.Fa idx 196in 197.Fa assert . 198Credential Blob 199.Pq credBlob 200and 201Large Blob Key 202.Pq largeBlobKey 203are CTAP 2.1 extensions. 204.Pp 205The 206.Fn fido_assert_authdata_len , 207.Fn fido_assert_clientdata_hash_len , 208.Fn fido_assert_id_len , 209.Fn fido_assert_user_id_len , 210.Fn fido_assert_sig_len , 211.Fn fido_assert_hmac_secret_len , 212.Fn fido_assert_blob_len , 213and 214.Fn fido_assert_largeblob_key_len 215functions return the length of a given attribute. 216.Pp 217Please note that the first statement in 218.Fa assert 219has an 220.Fa idx 221(index) value of 0. 222.Pp 223The authenticator data and signature parts of an assertion 224statement are typically passed to a FIDO2 server for verification. 225.Sh RETURN VALUES 226The authenticator data returned by 227.Fn fido_assert_authdata_ptr 228is a CBOR-encoded byte string, as obtained from the authenticator. 229.Pp 230The 231.Fn fido_assert_rp_id , 232.Fn fido_assert_user_display_name , 233.Fn fido_assert_user_icon , 234.Fn fido_assert_user_name , 235.Fn fido_assert_authdata_ptr , 236.Fn fido_assert_clientdata_hash_ptr , 237.Fn fido_assert_id_ptr , 238.Fn fido_assert_user_id_ptr , 239.Fn fido_assert_sig_ptr , 240.Fn fido_assert_hmac_secret_ptr , 241.Fn fido_assert_blob_ptr , 242and 243.Fn fido_assert_largeblob_key_ptr 244functions may return NULL if the respective field in 245.Fa assert 246is not set. 247If not NULL, returned pointers are guaranteed to exist until any API 248function that takes 249.Fa assert 250without the 251.Em const 252qualifier is invoked. 253.Sh SEE ALSO 254.Xr fido_assert_allow_cred 3 , 255.Xr fido_assert_set_authdata 3 , 256.Xr fido_assert_verify 3 , 257.Xr fido_dev_get_assert 3 , 258.Xr fido_dev_largeblob_get 3 259