fido_credman_metadata_free(3)

1FIDO_CREDMAN_METADATA... BSD Library Functions Manual FIDO_CREDMAN_METADATA...
2

NAME

4     fido_credman_metadata_new, fido_credman_rk_new, fido_credman_rp_new,
5     fido_credman_metadata_free, fido_credman_rk_free, fido_credman_rp_free,
6     fido_credman_rk_existing, fido_credman_rk_remaining, fido_credman_rk,
7     fido_credman_rk_count, fido_credman_rp_id, fido_credman_rp_name,
8     fido_credman_rp_count, fido_credman_rp_id_hash_ptr,
9     fido_credman_rp_id_hash_len, fido_credman_get_dev_metadata,
10     fido_credman_get_dev_rk, fido_credman_del_dev_rk, fido_credman_get_dev_rp
11     — FIDO 2 credential management API
12

SYNOPSIS

14     #include <fido.h>
15     #include <fido/credman.h>
16
17     fido_credman_metadata_t *
18     fido_credman_metadata_new(void);
19
20     fido_credman_rk_t *
21     fido_credman_rk_new(void);
22
23     fido_credman_rp_t *
24     fido_credman_rp_new(void);
25
26     void
27     fido_credman_metadata_free(fido_credman_metadata_t **metadata_p);
28
29     void
30     fido_credman_rk_free(fido_credman_rk_t **rk_p);
31
32     void
33     fido_credman_rp_free(fido_credman_rp_t **rp_p);
34
35     uint64_t
36     fido_credman_rk_existing(const fido_credman_metadata_t *metadata);
37
38     uint64_t
39     fido_credman_rk_remaining(const fido_credman_metadata_t *metadata);
40
41     const fido_cred_t *
42     fido_credman_rk(const fido_credman_rk_t *rk, size_t idx);
43
44     size_t
45     fido_credman_rk_count(const fido_credman_rk_t *rk);
46
47     const char *
48     fido_credman_rp_id(const fido_credman_rp_t *rp, size_t idx);
49
50     const char *
51     fido_credman_rp_name(const fido_credman_rp_t *rp, size_t idx);
52
53     size_t
54     fido_credman_rp_count(const fido_credman_rp_t *rp);
55
56     const unsigned char *
57     fido_credman_rp_id_hash_ptr(const fido_credman_rp_t *rp, size_t idx);
58
59     size_t
60     fido_credman_rp_id_hash_len(const fido_credman_rp_t *, size_t idx);
61
62     int
63     fido_credman_get_dev_metadata(fido_dev_t *dev,
64         fido_credman_metadata_t *metadata, const char *pin);
65
66     int
67     fido_credman_get_dev_rk(fido_dev_t *dev, const char *rp_id,
68         fido_credman_rk_t *rk, const char *pin);
69
70     int
71     fido_credman_del_dev_rk(fido_dev_t *dev, const, unsigned, char,
72         *cred_id", size_t cred_id_len, const char *pin);
73
74     int
75     fido_credman_get_dev_rp(fido_dev_t *dev, fido_credman_rp_t *rp,
76         const char *pin);
77

DESCRIPTION

79     The credential management API of libfido2 allows resident credentials on
80     a FIDO2 authenticator to be listed, inspected, and removed.  Please note
81     that not all FIDO2 authenticators support credential management.  To ob‐
82     tain information on what an authenticator supports, please refer to
83     fido_cbor_info_new(3).
84
85     The fido_credman_metadata_t type abstracts credential management meta‐
86     data.
87
88     The fido_credman_metadata_new() function returns a pointer to a newly al‐
89     located, empty fido_credman_metadata_t type.  If memory cannot be allo‐
90     cated, NULL is returned.
91
92     The fido_credman_metadata_free() function releases the memory backing
93     *metadata_p, where *metadata_p must have been previously allocated by
94     fido_credman_metadata_new().  On return, *metadata_p is set to NULL.  Ei‐
95     ther metadata_p or *metadata_p may be NULL, in which case
96     fido_credman_metadata_free() is a NOP.
97
98     The fido_credman_get_dev_metadata() function populates metadata with in‐
99     formation retrieved from dev.  A valid pin must be provided.
100
101     The fido_credman_rk_existing() function inspects metadata and returns the
102     number of resident credentials on the authenticator.  The
103     fido_credman_rk_remaining() function inspects metadata and returns the
104     estimated number of resident credentials that can be created on the au‐
105     thenticator.
106
107     The fido_credman_rk_t type abstracts the set of resident credentials be‐
108     longing to a given relying party.
109
110     The fido_credman_rk_new() function returns a pointer to a newly allo‐
111     cated, empty fido_credman_rk_t type.  If memory cannot be allocated, NULL
112     is returned.
113
114     The fido_credman_rk_free() function releases the memory backing *rk_p,
115     where *rk_p must have been previously allocated by fido_credman_rk_new().
116     On return, *rk_p is set to NULL.  Either rk_p or *rk_p may be NULL, in
117     which case fido_credman_rk_free() is a NOP.
118
119     The fido_credman_get_dev_rk() function populates rk with the set of resi‐
120     dent credentials belonging to rp_id in dev.  A valid pin must be pro‐
121     vided.
122
123     The fido_credman_rk_count() function returns the number of resident cre‐
124     dentials in rk.  The fido_credman_rk() function returns a pointer to the
125     credential at index idx in rk.  Please note that the first credential in
126     rk has an idx (index) value of 0.
127
128     The fido_credman_del_dev_rk() function deletes the resident credential
129     identified by cred_id from dev, where cred_id points to cred_id_len
130     bytes.  A valid pin must be provided.
131
132     The fido_credman_rp_t type abstracts information about a relying party.
133
134     The fido_credman_rp_new() function returns a pointer to a newly allo‐
135     cated, empty fido_credman_rp_t type.  If memory cannot be allocated, NULL
136     is returned.
137
138     The fido_credman_rp_free() function releases the memory backing *rp_p,
139     where *rp_p must have been previously allocated by fido_credman_rp_new().
140     On return, *rp_p is set to NULL.  Either rp_p or *rp_p may be NULL, in
141     which case fido_credman_rp_free() is a NOP.
142
143     The fido_credman_get_dev_rp() function populates rp with information
144     about relying parties with resident credentials in dev.  A valid pin must
145     be provided.
146
147     The fido_credman_rp_count() function returns the number of relying par‐
148     ties in rp.
149
150     The fido_credman_rp_id() and fido_credman_rp_name() functions return
151     pointers to the id and name of relying party idx in rp.  If not NULL, the
152     values returned by these functions point to NUL-terminated UTF-8 strings.
153     Please note that the first relying party in rp has an idx (index) value
154     of 0.
155
156     The fido_credman_rp_id_hash_ptr() function returns a pointer to the
157     hashed id of relying party idx in rp.  The corresponding length can be
158     obtained by fido_credman_rp_id_hash_len().  Please note that the first
159     relying party in rp has an idx (index) value of 0.
160

RETURN VALUES

162     The fido_credman_get_dev_metadata(), fido_credman_get_dev_rk(),
163     fido_credman_del_dev_rk(), and fido_credman_get_dev_rp() functions return
164     FIDO_OK on success.  On error, a different error code defined in
165     <fido/err.h> is returned.  Functions returning pointers are not guaran‐
166     teed to succeed, and should have their return values checked for NULL.
167

CAVEATS

172     Credential management is a tentative feature of FIDO 2.1.  Applications
173     willing to strictly abide by FIDO 2.0 should refrain from using creden‐
174     tial management.  Applications using credential management should ensure
175     it is supported by the authenticator prior to using the API.  Since FIDO
176     2.1 hasn't been finalised, there is a chance the functionality and asso‐
177     ciated data structures may change.
178
179     Resident credentials are called “discoverable credentials” in FIDO2.1.
180
181BSD                              June 28, 2019                             BSD

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

SEE ALSO

CAVEATS