1.\" Copyright (c) 2019-2021 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 28 2019 $ 29.Dt FIDO_CREDMAN_METADATA_NEW 3 30.Os 31.Sh NAME 32.Nm fido_credman_metadata_new , 33.Nm fido_credman_rk_new , 34.Nm fido_credman_rp_new , 35.Nm fido_credman_metadata_free , 36.Nm fido_credman_rk_free , 37.Nm fido_credman_rp_free , 38.Nm fido_credman_rk_existing , 39.Nm fido_credman_rk_remaining , 40.Nm fido_credman_rk , 41.Nm fido_credman_rk_count , 42.Nm fido_credman_rp_id , 43.Nm fido_credman_rp_name , 44.Nm fido_credman_rp_count , 45.Nm fido_credman_rp_id_hash_ptr , 46.Nm fido_credman_rp_id_hash_len , 47.Nm fido_credman_get_dev_metadata , 48.Nm fido_credman_get_dev_rk , 49.Nm fido_credman_set_dev_rk , 50.Nm fido_credman_del_dev_rk , 51.Nm fido_credman_get_dev_rp 52.Nd FIDO2 credential management API 53.Sh SYNOPSIS 54.In fido.h 55.In fido/credman.h 56.Ft fido_credman_metadata_t * 57.Fn fido_credman_metadata_new "void" 58.Ft fido_credman_rk_t * 59.Fn fido_credman_rk_new "void" 60.Ft fido_credman_rp_t * 61.Fn fido_credman_rp_new "void" 62.Ft void 63.Fn fido_credman_metadata_free "fido_credman_metadata_t **metadata_p" 64.Ft void 65.Fn fido_credman_rk_free "fido_credman_rk_t **rk_p" 66.Ft void 67.Fn fido_credman_rp_free "fido_credman_rp_t **rp_p" 68.Ft uint64_t 69.Fn fido_credman_rk_existing "const fido_credman_metadata_t *metadata" 70.Ft uint64_t 71.Fn fido_credman_rk_remaining "const fido_credman_metadata_t *metadata" 72.Ft const fido_cred_t * 73.Fn fido_credman_rk "const fido_credman_rk_t *rk" "size_t idx" 74.Ft size_t 75.Fn fido_credman_rk_count "const fido_credman_rk_t *rk" 76.Ft const char * 77.Fn fido_credman_rp_id "const fido_credman_rp_t *rp" "size_t idx" 78.Ft const char * 79.Fn fido_credman_rp_name "const fido_credman_rp_t *rp" "size_t idx" 80.Ft size_t 81.Fn fido_credman_rp_count "const fido_credman_rp_t *rp" 82.Ft const unsigned char * 83.Fn fido_credman_rp_id_hash_ptr "const fido_credman_rp_t *rp" "size_t idx" 84.Ft size_t 85.Fn fido_credman_rp_id_hash_len "const fido_credman_rp_t *" "size_t idx" 86.Ft int 87.Fn fido_credman_get_dev_metadata "fido_dev_t *dev" "fido_credman_metadata_t *metadata" "const char *pin" 88.Ft int 89.Fn fido_credman_get_dev_rk "fido_dev_t *dev" "const char *rp_id" "fido_credman_rk_t *rk" "const char *pin" 90.Ft int 91.Fn fido_credman_set_dev_rk "fido_dev_t *dev" "fido_cred_t *cred" "const char *pin" 92.Ft int 93.Fn fido_credman_del_dev_rk "fido_dev_t *dev" "const unsigned char *cred_id" "size_t cred_id_len" "const char *pin" 94.Ft int 95.Fn fido_credman_get_dev_rp "fido_dev_t *dev" "fido_credman_rp_t *rp" "const char *pin" 96.Sh DESCRIPTION 97The credential management API of 98.Em libfido2 99allows resident credentials on a FIDO2 authenticator to be listed, 100inspected, modified, and removed. 101Please note that not all FIDO2 authenticators support credential 102management. 103To obtain information on what an authenticator supports, please 104refer to 105.Xr fido_cbor_info_new 3 . 106.Pp 107The 108.Vt fido_credman_metadata_t 109type abstracts credential management metadata. 110.Pp 111The 112.Fn fido_credman_metadata_new 113function returns a pointer to a newly allocated, empty 114.Vt fido_credman_metadata_t 115type. 116If memory cannot be allocated, NULL is returned. 117.Pp 118The 119.Fn fido_credman_metadata_free 120function releases the memory backing 121.Fa *metadata_p , 122where 123.Fa *metadata_p 124must have been previously allocated by 125.Fn fido_credman_metadata_new . 126On return, 127.Fa *metadata_p 128is set to NULL. 129Either 130.Fa metadata_p 131or 132.Fa *metadata_p 133may be NULL, in which case 134.Fn fido_credman_metadata_free 135is a NOP. 136.Pp 137The 138.Fn fido_credman_get_dev_metadata 139function populates 140.Fa metadata 141with information retrieved from 142.Fa dev . 143A valid 144.Fa pin 145must be provided. 146.Pp 147The 148.Fn fido_credman_rk_existing 149function inspects 150.Fa metadata 151and returns the number of resident credentials on the 152authenticator. 153The 154.Fn fido_credman_rk_remaining 155function inspects 156.Fa metadata 157and returns the estimated number of resident credentials that can 158be created on the authenticator. 159.Pp 160The 161.Vt fido_credman_rk_t 162type abstracts the set of resident credentials belonging to a 163given relying party. 164.Pp 165The 166.Fn fido_credman_rk_new 167function returns a pointer to a newly allocated, empty 168.Vt fido_credman_rk_t 169type. 170If memory cannot be allocated, NULL is returned. 171.Pp 172The 173.Fn fido_credman_rk_free 174function releases the memory backing 175.Fa *rk_p , 176where 177.Fa *rk_p 178must have been previously allocated by 179.Fn fido_credman_rk_new . 180On return, 181.Fa *rk_p 182is set to NULL. 183Either 184.Fa rk_p 185or 186.Fa *rk_p 187may be NULL, in which case 188.Fn fido_credman_rk_free 189is a NOP. 190.Pp 191The 192.Fn fido_credman_get_dev_rk 193function populates 194.Fa rk 195with the set of resident credentials belonging to 196.Fa rp_id 197in 198.Fa dev . 199A valid 200.Fa pin 201must be provided. 202.Pp 203The 204.Fn fido_credman_rk_count 205function returns the number of resident credentials in 206.Fa rk . 207The 208.Fn fido_credman_rk 209function returns a pointer to the credential at index 210.Fa idx 211in 212.Fa rk . 213Please note that the first credential in 214.Fa rk 215has an 216.Fa idx 217(index) value of 0. 218.Pp 219The 220.Fn fido_credman_set_dev_rk 221function updates the credential pointed to by 222.Fa cred 223in 224.Fa dev . 225The credential id and user id attributes of 226.Fa cred 227must be set. 228See 229.Xr fido_cred_set_id 3 230and 231.Xr fido_cred_set_user 3 232for details. 233Only a credential's user attributes (name, display name) 234may be updated at this time. 235.Pp 236The 237.Fn fido_credman_del_dev_rk 238function deletes the resident credential identified by 239.Fa cred_id 240from 241.Fa dev , 242where 243.Fa cred_id 244points to 245.Fa cred_id_len 246bytes. 247A valid 248.Fa pin 249must be provided. 250.Pp 251The 252.Vt fido_credman_rp_t 253type abstracts information about a relying party. 254.Pp 255The 256.Fn fido_credman_rp_new 257function returns a pointer to a newly allocated, empty 258.Vt fido_credman_rp_t 259type. 260If memory cannot be allocated, NULL is returned. 261.Pp 262The 263.Fn fido_credman_rp_free 264function releases the memory backing 265.Fa *rp_p , 266where 267.Fa *rp_p 268must have been previously allocated by 269.Fn fido_credman_rp_new . 270On return, 271.Fa *rp_p 272is set to NULL. 273Either 274.Fa rp_p 275or 276.Fa *rp_p 277may be NULL, in which case 278.Fn fido_credman_rp_free 279is a NOP. 280.Pp 281The 282.Fn fido_credman_get_dev_rp 283function populates 284.Fa rp 285with information about relying parties with resident credentials 286in 287.Fa dev . 288A valid 289.Fa pin 290must be provided. 291.Pp 292The 293.Fn fido_credman_rp_count 294function returns the number of relying parties in 295.Fa rp . 296.Pp 297The 298.Fn fido_credman_rp_id 299and 300.Fn fido_credman_rp_name 301functions return pointers to the id and name of relying party 302.Fa idx 303in 304.Fa rp . 305If not NULL, the values returned by these functions point to 306NUL-terminated UTF-8 strings. 307Please note that the first relying party in 308.Fa rp 309has an 310.Fa idx 311(index) value of 0. 312.Pp 313The 314.Fn fido_credman_rp_id_hash_ptr 315function returns a pointer to the hashed id of relying party 316.Fa idx 317in 318.Fa rp . 319The corresponding length can be obtained by 320.Fn fido_credman_rp_id_hash_len . 321Please note that the first relying party in 322.Fa rp 323has an 324.Fa idx 325(index) value of 0. 326.Sh RETURN VALUES 327The 328.Fn fido_credman_get_dev_metadata , 329.Fn fido_credman_get_dev_rk , 330.Fn fido_credman_set_dev_rk , 331.Fn fido_credman_del_dev_rk , 332and 333.Fn fido_credman_get_dev_rp 334functions return 335.Dv FIDO_OK 336on success. 337On error, a different error code defined in 338.In fido/err.h 339is returned. 340Functions returning pointers are not guaranteed to succeed, and 341should have their return values checked for NULL. 342.Sh SEE ALSO 343.Xr fido_cbor_info_new 3 , 344.Xr fido_cred_new 3 , 345.Xr fido_dev_supports_credman 3 346.Sh CAVEATS 347Resident credentials are called 348.Dq discoverable credentials 349in CTAP 2.1. 350