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