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: August 11 2020 $ 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_clientdata_hash_ptr , 18.Nm fido_assert_hmac_secret_ptr , 19.Nm fido_assert_user_id_ptr , 20.Nm fido_assert_sig_ptr , 21.Nm fido_assert_id_ptr , 22.Nm fido_assert_authdata_len , 23.Nm fido_assert_clientdata_hash_len , 24.Nm fido_assert_hmac_secret_len , 25.Nm fido_assert_user_id_len , 26.Nm fido_assert_sig_len , 27.Nm fido_assert_id_len , 28.Nm fido_assert_sigcount , 29.Nm fido_assert_flags 30.Nd FIDO 2 assertion API 31.Sh SYNOPSIS 32.In fido.h 33.Ft fido_assert_t * 34.Fn fido_assert_new "void" 35.Ft void 36.Fn fido_assert_free "fido_assert_t **assert_p" 37.Ft size_t 38.Fn fido_assert_count "const fido_assert_t *assert" 39.Ft const char * 40.Fn fido_assert_rp_id "const fido_assert_t *assert" 41.Ft const char * 42.Fn fido_assert_user_display_name "const fido_assert_t *assert" "size_t idx" 43.Ft const char * 44.Fn fido_assert_user_icon "const fido_assert_t *assert" "size_t idx" 45.Ft const char * 46.Fn fido_assert_user_name "const fido_assert_t *assert" "size_t idx" 47.Ft const unsigned char * 48.Fn fido_assert_authdata_ptr "const fido_assert_t *assert" "size_t idx" 49.Ft const unsigned char * 50.Fn fido_assert_clientdata_hash_ptr "const fido_assert_t *assert" 51.Ft const unsigned char * 52.Fn fido_assert_hmac_secret_ptr "const fido_assert_t *assert" "size_t idx" 53.Ft const unsigned char * 54.Fn fido_assert_user_id_ptr "const fido_assert_t *assert" "size_t idx" 55.Ft const unsigned char * 56.Fn fido_assert_sig_ptr "const fido_assert_t *assert" "size_t idx" 57.Ft const unsigned char * 58.Fn fido_assert_id_ptr "const fido_assert_t *assert" "size_t idx" 59.Ft size_t 60.Fn fido_assert_authdata_len "const fido_assert_t *assert" "size_t idx" 61.Ft size_t 62.Fn fido_assert_clientdata_hash_len "const fido_assert_t *assert" 63.Ft size_t 64.Fn fido_assert_hmac_secret_len "const fido_assert_t *assert" "size_t idx" 65.Ft size_t 66.Fn fido_assert_user_id_len "const fido_assert_t *assert" "size_t idx" 67.Ft size_t 68.Fn fido_assert_sig_len "const fido_assert_t *assert" "size_t idx" 69.Ft size_t 70.Fn fido_assert_id_len "const fido_assert_t *assert" "size_t idx" 71.Ft uint32_t 72.Fn fido_assert_sigcount "const fido_assert_t *assert" "size_t idx" 73.Ft uint8_t 74.Fn fido_assert_flags "const fido_assert_t *assert" "size_t idx" 75.Sh DESCRIPTION 76FIDO 2 assertions are abstracted in 77.Em libfido2 78by the 79.Vt fido_assert_t 80type. 81The functions described in this page allow a 82.Vt fido_assert_t 83type to be allocated, deallocated, and inspected. 84For other operations on 85.Vt fido_assert_t , 86please refer to 87.Xr fido_assert_set_authdata 3 , 88.Xr fido_assert_allow_cred 3 , 89.Xr fido_assert_verify 3 , 90and 91.Xr fido_dev_get_assert 3 . 92.Pp 93The 94.Fn fido_assert_new 95function returns a pointer to a newly allocated, empty 96.Vt fido_assert_t 97type. 98If memory cannot be allocated, NULL is returned. 99.Pp 100The 101.Fn fido_assert_free 102function releases the memory backing 103.Fa *assert_p , 104where 105.Fa *assert_p 106must have been previously allocated by 107.Fn fido_assert_new . 108On return, 109.Fa *assert_p 110is set to NULL. 111Either 112.Fa assert_p 113or 114.Fa *assert_p 115may be NULL, in which case 116.Fn fido_assert_free 117is a NOP. 118.Pp 119The 120.Fn fido_assert_count 121function returns the number of statements in 122.Fa assert . 123.Pp 124The 125.Fn fido_assert_rp_id 126function returns a pointer to a NUL-terminated string holding the 127relying party ID of 128.Fa assert . 129.Pp 130The 131.Fn fido_assert_user_display_name , 132.Fn fido_assert_user_icon , 133and 134.Fn fido_assert_user_name , 135functions return pointers to the user display name, icon, and 136name attributes of statement 137.Fa idx 138in 139.Fa assert . 140If not NULL, the values returned by these functions point to 141NUL-terminated UTF-8 strings. 142.Pp 143The 144.Fn fido_assert_user_id_ptr , 145.Fn fido_assert_authdata_ptr , 146.Fn fido_assert_hmac_secret_ptr , 147.Fn fido_assert_sig_ptr , 148and 149.Fn fido_assert_id_ptr 150functions return pointers to the user ID, authenticator data, 151hmac-secret, signature, and credential ID attributes of statement 152.Fa idx 153in 154.Fa assert . 155The 156.Fn fido_assert_user_id_len , 157.Fn fido_assert_authdata_len , 158.Fn fido_assert_hmac_secret_len , 159.Fn fido_assert_sig_len , 160and 161.Fn fido_assert_id_len 162functions can be used to retrieve the corresponding length of a 163specific attribute. 164.Pp 165The 166.Fn fido_assert_sigcount 167function can be used to obtain the signature counter of statement 168.Fa idx 169in 170.Fa assert . 171.Pp 172The 173.Fn fido_assert_flags 174function returns the authenticator data flags of statement 175.Fa idx 176in 177.Fa assert . 178.Pp 179Please note that the first statement in 180.Fa assert 181has an 182.Fa idx 183(index) value of 0. 184.Pp 185The authenticator data and signature parts of an assertion 186statement are typically passed to a FIDO 2 server for verification. 187.Pp 188The 189.Fn fido_assert_clientdata_hash_ptr 190function returns a pointer to the client data hash of 191.Fa assert . 192The corresponding length can be obtained by 193.Fn fido_assert_clientdata_hash_len . 194.Sh RETURN VALUES 195The 196.Fn fido_assert_user_display_name , 197.Fn fido_assert_user_icon , 198.Fn fido_assert_user_name , 199.Fn fido_assert_authdata_ptr , 200.Fn fido_assert_clientdata_hash_ptr , 201.Fn fido_assert_user_id_ptr , 202and 203.Fn fido_assert_sig_ptr 204functions return NULL if the respective field in 205.Fa assert 206is not set. 207If not NULL, returned pointers are guaranteed to exist until any API 208function that takes 209.Fa assert 210without the 211.Em const 212qualifier is invoked. 213.Sh SEE ALSO 214.Xr fido_assert_allow_cred 3 , 215.Xr fido_assert_set_authdata 3 , 216.Xr fido_assert_verify 3 , 217.Xr fido_dev_get_assert 3 218