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: October 22 2019 $ 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. 183.Pp 184The 185.Fn fido_assert_blob_ptr 186and 187.Fn fido_assert_largeblob_key_ptr 188functions return pointers to the 189.Dq credBlob 190and 191.Dq largeBlobKey 192attributes of statement 193.Fa idx 194in 195.Fa assert . 196Credential Blob 197.Pq credBlob 198and 199Large Blob Key 200.Pq largeBlobKey 201are CTAP 2.1 extensions. 202.Pp 203The 204.Fn fido_assert_authdata_len , 205.Fn fido_assert_clientdata_hash_len , 206.Fn fido_assert_id_len , 207.Fn fido_assert_user_id_len , 208.Fn fido_assert_sig_len , 209.Fn fido_assert_hmac_secret_len , 210.Fn fido_assert_blob_len , 211and 212.Fn fido_assert_largeblob_key_len 213functions return the length of a given attribute. 214.Pp 215Please note that the first statement in 216.Fa assert 217has an 218.Fa idx 219(index) value of 0. 220.Pp 221The authenticator data and signature parts of an assertion 222statement are typically passed to a FIDO2 server for verification. 223.Sh RETURN VALUES 224The authenticator data returned by 225.Fn fido_assert_authdata_ptr 226is a CBOR-encoded byte string, as obtained from the authenticator. 227.Pp 228The 229.Fn fido_assert_rp_id , 230.Fn fido_assert_user_display_name , 231.Fn fido_assert_user_icon , 232.Fn fido_assert_user_name , 233.Fn fido_assert_authdata_ptr , 234.Fn fido_assert_clientdata_hash_ptr , 235.Fn fido_assert_id_ptr , 236.Fn fido_assert_user_id_ptr , 237.Fn fido_assert_sig_ptr , 238.Fn fido_assert_hmac_secret_ptr , 239.Fn fido_assert_blob_ptr , 240and 241.Fn fido_assert_largeblob_key_ptr 242functions may return NULL if the respective field in 243.Fa assert 244is not set. 245If not NULL, returned pointers are guaranteed to exist until any API 246function that takes 247.Fa assert 248without the 249.Em const 250qualifier is invoked. 251.Sh SEE ALSO 252.Xr fido_assert_allow_cred 3 , 253.Xr fido_assert_set_authdata 3 , 254.Xr fido_assert_verify 3 , 255.Xr fido_dev_get_assert 3 , 256.Xr fido_dev_largeblob_get 3 257