contrib/libfido2/man/fido_assert_new.3

   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
 111 A FIDO2 assertion is a collection of statements, each statement a
 112 map between a challenge, a credential, a signature, and ancillary
 113 attributes.
 114 In
 115 .Em libfido2 ,
 116 a FIDO2 assertion is abstracted by the
 117 .Vt fido_assert_t
 118 type.
 119 The functions described in this page allow a
 120 .Vt fido_assert_t
 121 type to be allocated, deallocated, and inspected.
 122 For other operations on
 123 .Vt fido_assert_t ,
 124 please refer to
 125 .Xr fido_assert_set_authdata 3 ,
 126 .Xr fido_assert_allow_cred 3 ,
 127 .Xr fido_assert_verify 3 ,
 128 and
 129 .Xr fido_dev_get_assert 3 .
 130 .Pp
 131 The
 132 .Fn fido_assert_new
 133 function returns a pointer to a newly allocated, empty
 134 .Vt fido_assert_t
 135 type.
 136 If memory cannot be allocated, NULL is returned.
 137 .Pp
 138 The
 139 .Fn fido_assert_free
 140 function releases the memory backing
 141 .Fa *assert_p ,
 142 where
 143 .Fa *assert_p
 144 must have been previously allocated by
 145 .Fn fido_assert_new .
 146 On return,
 147 .Fa *assert_p
 148 is set to NULL.
 149 Either
 150 .Fa assert_p
 151 or
 152 .Fa *assert_p
 153 may be NULL, in which case
 154 .Fn fido_assert_free
 155 is a NOP.
 156 .Pp
 157 The
 158 .Fn fido_assert_count
 159 function returns the number of statements in
 160 .Fa assert .
 161 .Pp
 162 The
 163 .Fn fido_assert_rp_id
 164 function returns a pointer to a NUL-terminated string holding the
 165 relying party ID of
 166 .Fa assert .
 167 .Pp
 168 The
 169 .Fn fido_assert_user_display_name ,
 170 .Fn fido_assert_user_icon ,
 171 and
 172 .Fn fido_assert_user_name ,
 173 functions return pointers to the user display name, icon, and
 174 name attributes of statement
 175 .Fa idx
 176 in
 177 .Fa assert .
 178 If not NULL, the values returned by these functions point to
 179 NUL-terminated UTF-8 strings.
 180 The user display name, icon, and name attributes will typically
 181 only be returned by the authenticator if user verification was
 182 performed by the authenticator and multiple resident/discoverable
 183 credentials were involved in the assertion.
 184 .Pp
 185 The
 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 ,
 192 and
 193 .Fn fido_assert_flags
 194 functions return pointers to the CBOR-encoded authenticator data,
 195 client data hash, credential ID, user ID, signature, signature
 196 count, and authenticator data flags of statement
 197 .Fa idx
 198 in
 199 .Fa assert .
 200 .Pp
 201 The
 202 .Fn fido_assert_hmac_secret_ptr
 203 function returns a pointer to the hmac-secret attribute of statement
 204 .Fa idx
 205 in
 206 .Fa assert .
 207 The HMAC Secret Extension
 208 .Pq hmac-secret
 209 is a CTAP 2.0 extension.
 210 Note that the resulting hmac-secret varies according to whether
 211 user verification was performed by the authenticator.
 212 .Pp
 213 The
 214 .Fn fido_assert_blob_ptr
 215 and
 216 .Fn fido_assert_largeblob_key_ptr
 217 functions return pointers to the
 218 .Dq credBlob
 219 and
 220 .Dq largeBlobKey
 221 attributes of statement
 222 .Fa idx
 223 in
 224 .Fa assert .
 225 Credential Blob
 226 .Pq credBlob
 227 and
 228 Large Blob Key
 229 .Pq largeBlobKey
 230 are CTAP 2.1 extensions.
 231 .Pp
 232 The
 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 ,
 240 and
 241 .Fn fido_assert_largeblob_key_len
 242 functions return the length of a given attribute.
 243 .Pp
 244 Please note that the first statement in
 245 .Fa assert
 246 has an
 247 .Fa idx
 248 (index) value of 0.
 249 .Pp
 250 The authenticator data and signature parts of an assertion
 251 statement are typically passed to a FIDO2 server for verification.
 252 .Sh RETURN VALUES
 253 The authenticator data returned by
 254 .Fn fido_assert_authdata_ptr
 255 is a CBOR-encoded byte string, as obtained from the authenticator.
 256 .Pp
 257 The
 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 ,
 269 and
 270 .Fn fido_assert_largeblob_key_ptr
 271 functions may return NULL if the respective field in
 272 .Fa assert
 273 is not set.
 274 If not NULL, returned pointers are guaranteed to exist until any API
 275 function that takes
 276 .Fa assert
 277 without the
 278 .Em const
 279 qualifier 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