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