1.\" Copyright (c) 2018-2023 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: June 19 2023 $ 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_authdata_raw_ptr , 41.Nm fido_assert_blob_ptr , 42.Nm fido_assert_clientdata_hash_ptr , 43.Nm fido_assert_hmac_secret_ptr , 44.Nm fido_assert_largeblob_key_ptr , 45.Nm fido_assert_user_id_ptr , 46.Nm fido_assert_sig_ptr , 47.Nm fido_assert_id_ptr , 48.Nm fido_assert_authdata_len , 49.Nm fido_assert_authdata_raw_len , 50.Nm fido_assert_blob_len , 51.Nm fido_assert_clientdata_hash_len , 52.Nm fido_assert_hmac_secret_len , 53.Nm fido_assert_largeblob_key_len , 54.Nm fido_assert_user_id_len , 55.Nm fido_assert_sig_len , 56.Nm fido_assert_id_len , 57.Nm fido_assert_sigcount , 58.Nm fido_assert_flags 59.Nd FIDO2 assertion API 60.Sh SYNOPSIS 61.In fido.h 62.Ft fido_assert_t * 63.Fn fido_assert_new "void" 64.Ft void 65.Fn fido_assert_free "fido_assert_t **assert_p" 66.Ft size_t 67.Fn fido_assert_count "const fido_assert_t *assert" 68.Ft const char * 69.Fn fido_assert_rp_id "const fido_assert_t *assert" 70.Ft const char * 71.Fn fido_assert_user_display_name "const fido_assert_t *assert" "size_t idx" 72.Ft const char * 73.Fn fido_assert_user_icon "const fido_assert_t *assert" "size_t idx" 74.Ft const char * 75.Fn fido_assert_user_name "const fido_assert_t *assert" "size_t idx" 76.Ft const unsigned char * 77.Fn fido_assert_authdata_ptr "const fido_assert_t *assert" "size_t idx" 78.Ft const unsigned char * 79.Fn fido_assert_authdata_raw_ptr "const fido_assert_t *assert" "size_t idx" 80.Ft const unsigned char * 81.Fn fido_assert_clientdata_hash_ptr "const fido_assert_t *assert" 82.Ft const unsigned char * 83.Fn fido_assert_blob_ptr "const fido_assert_t *assert" "size_t idx" 84.Ft const unsigned char * 85.Fn fido_assert_hmac_secret_ptr "const fido_assert_t *assert" "size_t idx" 86.Ft const unsigned char * 87.Fn fido_assert_largeblob_key_ptr "const fido_assert_t *assert" "size_t idx" 88.Ft const unsigned char * 89.Fn fido_assert_user_id_ptr "const fido_assert_t *assert" "size_t idx" 90.Ft const unsigned char * 91.Fn fido_assert_sig_ptr "const fido_assert_t *assert" "size_t idx" 92.Ft const unsigned char * 93.Fn fido_assert_id_ptr "const fido_assert_t *assert" "size_t idx" 94.Ft size_t 95.Fn fido_assert_authdata_len "const fido_assert_t *assert" "size_t idx" 96.Ft size_t 97.Fn fido_assert_authdata_raw_len "const fido_assert_t *assert" "size_t idx" 98.Ft size_t 99.Fn fido_assert_clientdata_hash_len "const fido_assert_t *assert" 100.Ft size_t 101.Fn fido_assert_blob_len "const fido_assert_t *assert" "size_t idx" 102.Ft size_t 103.Fn fido_assert_hmac_secret_len "const fido_assert_t *assert" "size_t idx" 104.Ft size_t 105.Fn fido_assert_largeblob_key_len "const fido_assert_t *assert" "size_t idx" 106.Ft size_t 107.Fn fido_assert_user_id_len "const fido_assert_t *assert" "size_t idx" 108.Ft size_t 109.Fn fido_assert_sig_len "const fido_assert_t *assert" "size_t idx" 110.Ft size_t 111.Fn fido_assert_id_len "const fido_assert_t *assert" "size_t idx" 112.Ft uint32_t 113.Fn fido_assert_sigcount "const fido_assert_t *assert" "size_t idx" 114.Ft uint8_t 115.Fn fido_assert_flags "const fido_assert_t *assert" "size_t idx" 116.Sh DESCRIPTION 117A FIDO2 assertion is a collection of statements, each statement a 118map between a challenge, a credential, a signature, and ancillary 119attributes. 120In 121.Em libfido2 , 122a FIDO2 assertion is abstracted by the 123.Vt fido_assert_t 124type. 125The functions described in this page allow a 126.Vt fido_assert_t 127type to be allocated, deallocated, and inspected. 128For other operations on 129.Vt fido_assert_t , 130please refer to 131.Xr fido_assert_set_authdata 3 , 132.Xr fido_assert_allow_cred 3 , 133.Xr fido_assert_verify 3 , 134and 135.Xr fido_dev_get_assert 3 . 136.Pp 137The 138.Fn fido_assert_new 139function returns a pointer to a newly allocated, empty 140.Vt fido_assert_t 141type. 142If memory cannot be allocated, NULL is returned. 143.Pp 144The 145.Fn fido_assert_free 146function releases the memory backing 147.Fa *assert_p , 148where 149.Fa *assert_p 150must have been previously allocated by 151.Fn fido_assert_new . 152On return, 153.Fa *assert_p 154is set to NULL. 155Either 156.Fa assert_p 157or 158.Fa *assert_p 159may be NULL, in which case 160.Fn fido_assert_free 161is a NOP. 162.Pp 163The 164.Fn fido_assert_count 165function returns the number of statements in 166.Fa assert . 167.Pp 168The 169.Fn fido_assert_rp_id 170function returns a pointer to a NUL-terminated string holding the 171relying party ID of 172.Fa assert . 173.Pp 174The 175.Fn fido_assert_user_display_name , 176.Fn fido_assert_user_icon , 177and 178.Fn fido_assert_user_name , 179functions return pointers to the user display name, icon, and 180name attributes of statement 181.Fa idx 182in 183.Fa assert . 184If not NULL, the values returned by these functions point to 185NUL-terminated UTF-8 strings. 186The user display name, icon, and name attributes will typically 187only be returned by the authenticator if user verification was 188performed by the authenticator and multiple resident/discoverable 189credentials were involved in the assertion. 190.Pp 191The 192.Fn fido_assert_authdata_ptr , 193.Fn fido_assert_authdata_raw_ptr , 194.Fn fido_assert_clientdata_hash_ptr , 195.Fn fido_assert_id_ptr , 196.Fn fido_assert_user_id_ptr , 197.Fn fido_assert_sig_ptr , 198.Fn fido_assert_sigcount , 199and 200.Fn fido_assert_flags 201functions return pointers to the CBOR-encoded and raw authenticator data, 202client data hash, credential ID, user ID, signature, signature 203count, and authenticator data flags of statement 204.Fa idx 205in 206.Fa assert . 207.Pp 208The 209.Fn fido_assert_hmac_secret_ptr 210function returns a pointer to the hmac-secret attribute of statement 211.Fa idx 212in 213.Fa assert . 214The HMAC Secret Extension 215.Pq hmac-secret 216is a CTAP 2.0 extension. 217Note that the resulting hmac-secret varies according to whether 218user verification was performed by the authenticator. 219.Pp 220The 221.Fn fido_assert_blob_ptr 222and 223.Fn fido_assert_largeblob_key_ptr 224functions return pointers to the 225.Dq credBlob 226and 227.Dq largeBlobKey 228attributes of statement 229.Fa idx 230in 231.Fa assert . 232Credential Blob 233.Pq credBlob 234and 235Large Blob Key 236.Pq largeBlobKey 237are CTAP 2.1 extensions. 238.Pp 239The 240.Fn fido_assert_authdata_len , 241.Fn fido_assert_authdata_raw_len , 242.Fn fido_assert_clientdata_hash_len , 243.Fn fido_assert_id_len , 244.Fn fido_assert_user_id_len , 245.Fn fido_assert_sig_len , 246.Fn fido_assert_hmac_secret_len , 247.Fn fido_assert_blob_len , 248and 249.Fn fido_assert_largeblob_key_len 250functions return the length of a given attribute. 251.Pp 252Please note that the first statement in 253.Fa assert 254has an 255.Fa idx 256(index) value of 0. 257.Pp 258The authenticator data and signature parts of an assertion 259statement are typically passed to a FIDO2 server for verification. 260.Sh RETURN VALUES 261The authenticator data returned by 262.Fn fido_assert_authdata_ptr 263is a CBOR-encoded byte string, as obtained from the authenticator. 264.Pp 265The 266.Fn fido_assert_rp_id , 267.Fn fido_assert_user_display_name , 268.Fn fido_assert_user_icon , 269.Fn fido_assert_user_name , 270.Fn fido_assert_authdata_ptr , 271.Fn fido_assert_clientdata_hash_ptr , 272.Fn fido_assert_id_ptr , 273.Fn fido_assert_user_id_ptr , 274.Fn fido_assert_sig_ptr , 275.Fn fido_assert_hmac_secret_ptr , 276.Fn fido_assert_blob_ptr , 277and 278.Fn fido_assert_largeblob_key_ptr 279functions may return NULL if the respective field in 280.Fa assert 281is not set. 282If not NULL, returned pointers are guaranteed to exist until any API 283function that takes 284.Fa assert 285without the 286.Em const 287qualifier is invoked. 288.Sh SEE ALSO 289.Xr fido_assert_allow_cred 3 , 290.Xr fido_assert_set_authdata 3 , 291.Xr fido_assert_verify 3 , 292.Xr fido_dev_get_assert 3 , 293.Xr fido_dev_largeblob_get 3 294