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_set_dev_rk,
11     fido_credman_del_dev_rk, fido_credman_get_dev_rp — FIDO 2 credential man‐
12     agement API
13

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUES

173     The fido_credman_get_dev_metadata(), fido_credman_get_dev_rk(),
174     fido_credman_set_dev_rk(), fido_credman_del_dev_rk(), and
175     fido_credman_get_dev_rp() functions return FIDO_OK on success.  On error,
176     a different error code defined in <fido/err.h> is returned.  Functions
177     returning pointers are not guaranteed to succeed, and should have their
178     return values checked for NULL.
179

SEE ALSO

181     fido_cbor_info_new(3), fido_cred_new(3), fido_dev_supports_credman(3)
182

CAVEATS

184     Resident credentials are called “discoverable credentials” in FIDO 2.1.
185
186BSD                              June 28, 2019                             BSD
Impressum