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