1.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions are 5.\" met: 6.\" 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in 11.\" the documentation and/or other materials provided with the 12.\" distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 15.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 16.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 17.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 18.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 19.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 20.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 24.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" SPDX-License-Identifier: BSD-2-Clause 27.\" 28.Dd $Mdocdate: April 27 2022 $ 29.Dt FIDO_ASSERT_NEW 3 30.Os 31.Sh NAME 32.Nm fido_assert_new , 33.Nm fido_assert_free , 34.Nm fido_assert_count , 35.Nm fido_assert_rp_id , 36.Nm fido_assert_user_display_name , 37.Nm fido_assert_user_icon , 38.Nm fido_assert_user_name , 39.Nm fido_assert_authdata_ptr , 40.Nm fido_assert_blob_ptr , 41.Nm fido_assert_clientdata_hash_ptr , 42.Nm fido_assert_hmac_secret_ptr , 43.Nm fido_assert_largeblob_key_ptr , 44.Nm fido_assert_user_id_ptr , 45.Nm fido_assert_sig_ptr , 46.Nm fido_assert_id_ptr , 47.Nm fido_assert_authdata_len , 48.Nm fido_assert_blob_len , 49.Nm fido_assert_clientdata_hash_len , 50.Nm fido_assert_hmac_secret_len , 51.Nm fido_assert_largeblob_key_len , 52.Nm fido_assert_user_id_len , 53.Nm fido_assert_sig_len , 54.Nm fido_assert_id_len , 55.Nm fido_assert_sigcount , 56.Nm fido_assert_flags 57.Nd FIDO2 assertion API 58.Sh SYNOPSIS 59.In fido.h 60.Ft fido_assert_t * 61.Fn fido_assert_new "void" 62.Ft void 63.Fn fido_assert_free "fido_assert_t **assert_p" 64.Ft size_t 65.Fn fido_assert_count "const fido_assert_t *assert" 66.Ft const char * 67.Fn fido_assert_rp_id "const fido_assert_t *assert" 68.Ft const char * 69.Fn fido_assert_user_display_name "const fido_assert_t *assert" "size_t idx" 70.Ft const char * 71.Fn fido_assert_user_icon "const fido_assert_t *assert" "size_t idx" 72.Ft const char * 73.Fn fido_assert_user_name "const fido_assert_t *assert" "size_t idx" 74.Ft const unsigned char * 75.Fn fido_assert_authdata_ptr "const fido_assert_t *assert" "size_t idx" 76.Ft const unsigned char * 77.Fn fido_assert_clientdata_hash_ptr "const fido_assert_t *assert" 78.Ft const unsigned char * 79.Fn fido_assert_blob_ptr "const fido_assert_t *assert" "size_t idx" 80.Ft const unsigned char * 81.Fn fido_assert_hmac_secret_ptr "const fido_assert_t *assert" "size_t idx" 82.Ft const unsigned char * 83.Fn fido_assert_largeblob_key_ptr "const fido_assert_t *assert" "size_t idx" 84.Ft const unsigned char * 85.Fn fido_assert_user_id_ptr "const fido_assert_t *assert" "size_t idx" 86.Ft const unsigned char * 87.Fn fido_assert_sig_ptr "const fido_assert_t *assert" "size_t idx" 88.Ft const unsigned char * 89.Fn fido_assert_id_ptr "const fido_assert_t *assert" "size_t idx" 90.Ft size_t 91.Fn fido_assert_authdata_len "const fido_assert_t *assert" "size_t idx" 92.Ft size_t 93.Fn fido_assert_clientdata_hash_len "const fido_assert_t *assert" 94.Ft size_t 95.Fn fido_assert_blob_len "const fido_assert_t *assert" "size_t idx" 96.Ft size_t 97.Fn fido_assert_hmac_secret_len "const fido_assert_t *assert" "size_t idx" 98.Ft size_t 99.Fn fido_assert_largeblob_key_len "const fido_assert_t *assert" "size_t idx" 100.Ft size_t 101.Fn fido_assert_user_id_len "const fido_assert_t *assert" "size_t idx" 102.Ft size_t 103.Fn fido_assert_sig_len "const fido_assert_t *assert" "size_t idx" 104.Ft size_t 105.Fn fido_assert_id_len "const fido_assert_t *assert" "size_t idx" 106.Ft uint32_t 107.Fn fido_assert_sigcount "const fido_assert_t *assert" "size_t idx" 108.Ft uint8_t 109.Fn fido_assert_flags "const fido_assert_t *assert" "size_t idx" 110.Sh DESCRIPTION 111A FIDO2 assertion is a collection of statements, each statement a 112map between a challenge, a credential, a signature, and ancillary 113attributes. 114In 115.Em libfido2 , 116a FIDO2 assertion is abstracted by the 117.Vt fido_assert_t 118type. 119The functions described in this page allow a 120.Vt fido_assert_t 121type to be allocated, deallocated, and inspected. 122For other operations on 123.Vt fido_assert_t , 124please refer to 125.Xr fido_assert_set_authdata 3 , 126.Xr fido_assert_allow_cred 3 , 127.Xr fido_assert_verify 3 , 128and 129.Xr fido_dev_get_assert 3 . 130.Pp 131The 132.Fn fido_assert_new 133function returns a pointer to a newly allocated, empty 134.Vt fido_assert_t 135type. 136If memory cannot be allocated, NULL is returned. 137.Pp 138The 139.Fn fido_assert_free 140function releases the memory backing 141.Fa *assert_p , 142where 143.Fa *assert_p 144must have been previously allocated by 145.Fn fido_assert_new . 146On return, 147.Fa *assert_p 148is set to NULL. 149Either 150.Fa assert_p 151or 152.Fa *assert_p 153may be NULL, in which case 154.Fn fido_assert_free 155is a NOP. 156.Pp 157The 158.Fn fido_assert_count 159function returns the number of statements in 160.Fa assert . 161.Pp 162The 163.Fn fido_assert_rp_id 164function returns a pointer to a NUL-terminated string holding the 165relying party ID of 166.Fa assert . 167.Pp 168The 169.Fn fido_assert_user_display_name , 170.Fn fido_assert_user_icon , 171and 172.Fn fido_assert_user_name , 173functions return pointers to the user display name, icon, and 174name attributes of statement 175.Fa idx 176in 177.Fa assert . 178If not NULL, the values returned by these functions point to 179NUL-terminated UTF-8 strings. 180The user display name, icon, and name attributes will typically 181only be returned by the authenticator if user verification was 182performed by the authenticator and multiple resident/discoverable 183credentials were involved in the assertion. 184.Pp 185The 186.Fn fido_assert_authdata_ptr , 187.Fn fido_assert_clientdata_hash_ptr , 188.Fn fido_assert_id_ptr , 189.Fn fido_assert_user_id_ptr , 190.Fn fido_assert_sig_ptr , 191.Fn fido_assert_sigcount , 192and 193.Fn fido_assert_flags 194functions return pointers to the CBOR-encoded authenticator data, 195client data hash, credential ID, user ID, signature, signature 196count, and authenticator data flags of statement 197.Fa idx 198in 199.Fa assert . 200.Pp 201The 202.Fn fido_assert_hmac_secret_ptr 203function returns a pointer to the hmac-secret attribute of statement 204.Fa idx 205in 206.Fa assert . 207The HMAC Secret Extension 208.Pq hmac-secret 209is a CTAP 2.0 extension. 210Note that the resulting hmac-secret varies according to whether 211user verification was performed by the authenticator. 212.Pp 213The 214.Fn fido_assert_blob_ptr 215and 216.Fn fido_assert_largeblob_key_ptr 217functions return pointers to the 218.Dq credBlob 219and 220.Dq largeBlobKey 221attributes of statement 222.Fa idx 223in 224.Fa assert . 225Credential Blob 226.Pq credBlob 227and 228Large Blob Key 229.Pq largeBlobKey 230are CTAP 2.1 extensions. 231.Pp 232The 233.Fn fido_assert_authdata_len , 234.Fn fido_assert_clientdata_hash_len , 235.Fn fido_assert_id_len , 236.Fn fido_assert_user_id_len , 237.Fn fido_assert_sig_len , 238.Fn fido_assert_hmac_secret_len , 239.Fn fido_assert_blob_len , 240and 241.Fn fido_assert_largeblob_key_len 242functions return the length of a given attribute. 243.Pp 244Please note that the first statement in 245.Fa assert 246has an 247.Fa idx 248(index) value of 0. 249.Pp 250The authenticator data and signature parts of an assertion 251statement are typically passed to a FIDO2 server for verification. 252.Sh RETURN VALUES 253The authenticator data returned by 254.Fn fido_assert_authdata_ptr 255is a CBOR-encoded byte string, as obtained from the authenticator. 256.Pp 257The 258.Fn fido_assert_rp_id , 259.Fn fido_assert_user_display_name , 260.Fn fido_assert_user_icon , 261.Fn fido_assert_user_name , 262.Fn fido_assert_authdata_ptr , 263.Fn fido_assert_clientdata_hash_ptr , 264.Fn fido_assert_id_ptr , 265.Fn fido_assert_user_id_ptr , 266.Fn fido_assert_sig_ptr , 267.Fn fido_assert_hmac_secret_ptr , 268.Fn fido_assert_blob_ptr , 269and 270.Fn fido_assert_largeblob_key_ptr 271functions may return NULL if the respective field in 272.Fa assert 273is not set. 274If not NULL, returned pointers are guaranteed to exist until any API 275function that takes 276.Fa assert 277without the 278.Em const 279qualifier is invoked. 280.Sh SEE ALSO 281.Xr fido_assert_allow_cred 3 , 282.Xr fido_assert_set_authdata 3 , 283.Xr fido_assert_verify 3 , 284.Xr fido_dev_get_assert 3 , 285.Xr fido_dev_largeblob_get 3 286