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 FIDO 2 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 88FIDO 2 assertions are abstracted in 89.Em libfido2 90by the 91.Vt fido_assert_t 92type. 93The functions described in this page allow a 94.Vt fido_assert_t 95type to be allocated, deallocated, and inspected. 96For other operations on 97.Vt fido_assert_t , 98please refer to 99.Xr fido_assert_set_authdata 3 , 100.Xr fido_assert_allow_cred 3 , 101.Xr fido_assert_verify 3 , 102and 103.Xr fido_dev_get_assert 3 . 104.Pp 105The 106.Fn fido_assert_new 107function returns a pointer to a newly allocated, empty 108.Vt fido_assert_t 109type. 110If memory cannot be allocated, NULL is returned. 111.Pp 112The 113.Fn fido_assert_free 114function releases the memory backing 115.Fa *assert_p , 116where 117.Fa *assert_p 118must have been previously allocated by 119.Fn fido_assert_new . 120On return, 121.Fa *assert_p 122is set to NULL. 123Either 124.Fa assert_p 125or 126.Fa *assert_p 127may be NULL, in which case 128.Fn fido_assert_free 129is a NOP. 130.Pp 131The 132.Fn fido_assert_count 133function returns the number of statements in 134.Fa assert . 135.Pp 136The 137.Fn fido_assert_rp_id 138function returns a pointer to a NUL-terminated string holding the 139relying party ID of 140.Fa assert . 141.Pp 142The 143.Fn fido_assert_user_display_name , 144.Fn fido_assert_user_icon , 145and 146.Fn fido_assert_user_name , 147functions return pointers to the user display name, icon, and 148name attributes of statement 149.Fa idx 150in 151.Fa assert . 152If not NULL, the values returned by these functions point to 153NUL-terminated UTF-8 strings. 154.Pp 155The 156.Fn fido_assert_user_id_ptr , 157.Fn fido_assert_authdata_ptr , 158.Fn fido_assert_blob_ptr , 159.Fn fido_assert_hmac_secret_ptr , 160.Fn fido_assert_largeblob_key_ptr , 161.Fn fido_assert_sig_ptr , 162and 163.Fn fido_assert_id_ptr 164functions return pointers to the user ID, CBOR-encoded 165authenticator data, cred blob, hmac-secret, 166.Dq largeBlobKey , 167signature, and credential ID attributes of statement 168.Fa idx 169in 170.Fa assert . 171.Pp 172The 173.Fn fido_assert_user_id_len , 174.Fn fido_assert_authdata_len , 175.Fn fido_assert_blob_len , 176.Fn fido_assert_hmac_secret_len , 177.Fn fido_assert_largeblob_key_len , 178.Fn fido_assert_sig_len , 179and 180.Fn fido_assert_id_len 181functions can be used to retrieve the corresponding length of a 182specific attribute. 183.Pp 184The 185.Fn fido_assert_sigcount 186function can be used to obtain the signature counter of statement 187.Fa idx 188in 189.Fa assert . 190.Pp 191The 192.Fn fido_assert_flags 193function returns the authenticator data flags of statement 194.Fa idx 195in 196.Fa assert . 197.Pp 198Please note that the first statement in 199.Fa assert 200has an 201.Fa idx 202(index) value of 0. 203.Pp 204The authenticator data and signature parts of an assertion 205statement are typically passed to a FIDO 2 server for verification. 206.Pp 207The 208.Fn fido_assert_clientdata_hash_ptr 209function returns a pointer to the client data hash of 210.Fa assert . 211The corresponding length can be obtained by 212.Fn fido_assert_clientdata_hash_len . 213.Sh RETURN VALUES 214The authenticator data returned by 215.Fn fido_assert_authdata_ptr 216is a CBOR-encoded byte string, as obtained from the authenticator. 217.Pp 218The 219.Fn fido_assert_user_display_name , 220.Fn fido_assert_user_icon , 221.Fn fido_assert_user_name , 222.Fn fido_assert_authdata_ptr , 223.Fn fido_assert_clientdata_hash_ptr , 224.Fn fido_assert_hmac_secret_ptr , 225.Fn fido_assert_largeblob_key_ptr , 226.Fn fido_assert_user_id_ptr , 227and 228.Fn fido_assert_sig_ptr 229functions return NULL if the respective field in 230.Fa assert 231is not set. 232If not NULL, returned pointers are guaranteed to exist until any API 233function that takes 234.Fa assert 235without the 236.Em const 237qualifier is invoked. 238.Sh SEE ALSO 239.Xr fido_assert_allow_cred 3 , 240.Xr fido_assert_set_authdata 3 , 241.Xr fido_assert_verify 3 , 242.Xr fido_dev_get_assert 3 , 243.Xr fido_dev_largeblob_get 3 244