1FIDO_CRED_SET_AUTHDAT... BSD Library Functions Manual FIDO_CRED_SET_AUTHDAT...
2

NAME

4     fido_cred_set_authdata, fido_cred_set_authdata_raw,
5     fido_cred_set_attstmt, fido_cred_set_x509, fido_cred_set_sig,
6     fido_cred_set_id, fido_cred_set_clientdata,
7     fido_cred_set_clientdata_hash, fido_cred_set_rp, fido_cred_set_user,
8     fido_cred_set_extensions, fido_cred_set_blob, fido_cred_set_pin_minlen,
9     fido_cred_set_prot, fido_cred_set_rk, fido_cred_set_uv,
10     fido_cred_set_fmt, fido_cred_set_type — set parameters of a FIDO2 creden‐
11     tial
12

SYNOPSIS

14     #include <fido.h>
15
16     typedef enum {
17             FIDO_OPT_OMIT = 0, /* use authenticator's default */
18             FIDO_OPT_FALSE,    /* explicitly set option to false */
19             FIDO_OPT_TRUE,     /* explicitly set option to true */
20     } fido_opt_t;
21
22     int
23     fido_cred_set_authdata(fido_cred_t *cred, const unsigned char *ptr,
24         size_t len);
25
26     int
27     fido_cred_set_authdata_raw(fido_cred_t *cred, const unsigned char *ptr,
28         size_t len);
29
30     int
31     fido_cred_set_attstmt(fido_cred_t *cred, const unsigned char *ptr,
32         size_t len);
33
34     int
35     fido_cred_set_x509(fido_cred_t *cred, const unsigned char *ptr,
36         size_t len);
37
38     int
39     fido_cred_set_sig(fido_cred_t *cred, const unsigned char *ptr,
40         size_t len);
41
42     int
43     fido_cred_set_id(fido_cred_t *cred, const unsigned char *ptr,
44         size_t len);
45
46     int
47     fido_cred_set_clientdata(fido_cred_t *cred, const unsigned char *ptr,
48         size_t len);
49
50     int
51     fido_cred_set_clientdata_hash(fido_cred_t *cred,
52         const unsigned char *ptr, size_t len);
53
54     int
55     fido_cred_set_rp(fido_cred_t *cred, const char *id, const char *name);
56
57     int
58     fido_cred_set_user(fido_cred_t *cred, const unsigned char *user_id,
59         size_t user_id_len, const char *name, const char *display_name,
60         const char *icon);
61
62     int
63     fido_cred_set_extensions(fido_cred_t *cred, int flags);
64
65     int
66     fido_cred_set_blob(fido_cred_t *cred, const unsigned char *ptr,
67         size_t len);
68
69     int
70     fido_cred_set_pin_minlen(fido_cred_t *cred, size_t len);
71
72     int
73     fido_cred_set_prot(fido_cred_t *cred, int prot);
74
75     int
76     fido_cred_set_rk(fido_cred_t *cred, fido_opt_t rk);
77
78     int
79     fido_cred_set_uv(fido_cred_t *cred, fido_opt_t uv);
80
81     int
82     fido_cred_set_fmt(fido_cred_t *cred, const char *ptr);
83
84     int
85     fido_cred_set_type(fido_cred_t *cred, int cose_alg);
86

DESCRIPTION

88     The fido_cred_set_authdata set of functions define the various parameters
89     of a FIDO2 credential, allowing a fido_cred_t type to be prepared for a
90     subsequent call to fido_dev_make_cred(3) or fido_cred_verify(3).  For the
91     complete specification of a FIDO2 credential and the format of its con‐
92     stituent parts, please refer to the Web Authentication (webauthn) stan‐
93     dard.
94
95     The fido_cred_set_authdata(), fido_cred_set_attstmt(),
96     fido_cred_set_x509(), fido_cred_set_sig(), fido_cred_set_id(), and
97     fido_cred_set_clientdata_hash() functions set the authenticator data, at‐
98     testation statement, attestation certificate, attestation signature, id,
99     and client data hash parts of cred to ptr, where ptr points to len bytes.
100     A copy of ptr is made, and no references to the passed pointer are kept.
101
102     The authenticator data passed to fido_cred_set_authdata() must be a CBOR-
103     encoded byte string, as obtained from fido_cred_authdata_ptr().  Alterna‐
104     tively, a raw binary blob may be passed to fido_cred_set_authdata_raw().
105     An application calling fido_cred_set_authdata() does not need to call
106     fido_cred_set_id().  The latter is meant to be used in contexts where the
107     credential's authenticator data is not available.
108
109     The attestation statement passed to fido_cred_set_attstmt() must be a
110     CBOR-encoded map, as obtained from fido_cred_attstmt_ptr().  An applica‐
111     tion calling fido_cred_set_attstmt() does not need to call
112     fido_cred_set_x509() or fido_cred_set_sig().  The latter two are meant to
113     be used in contexts where the credential's complete attestation statement
114     is not available or required.
115
116     The fido_cred_set_clientdata() function allows an application to set the
117     client data hash of cred by specifying the credential's unhashed client
118     data.  This is required by Windows Hello, which calculates the client
119     data hash internally.  For compatibility with Windows Hello, applications
120     should use fido_cred_set_clientdata() instead of
121     fido_cred_set_clientdata_hash().
122
123     The fido_cred_set_rp() function sets the relying party id and name param‐
124     eters of cred, where id and name are NUL-terminated UTF-8 strings.  The
125     contents of id and name are copied, and no references to the passed
126     pointers are kept.
127
128     The fido_cred_set_user() function sets the user attributes of cred, where
129     user_id points to user_id_len bytes and name, display_name, and icon are
130     NUL-terminated UTF-8 strings.  The contents of user_id, name,
131     display_name, and icon are copied, and no references to the passed point‐
132     ers are kept.  Previously set user attributes are flushed.  The user_id,
133     name, display_name, and icon parameters may be NULL.
134
135     The fido_cred_set_extensions() function sets the extensions of cred to
136     the bitmask flags.  At the moment, only the FIDO_EXT_CRED_BLOB,
137     FIDO_EXT_CRED_PROTECT, FIDO_EXT_HMAC_SECRET, FIDO_EXT_MINPINLEN, and
138     FIDO_EXT_LARGEBLOB_KEY extensions are supported.  If flags is zero, the
139     extensions of cred are cleared.
140
141     The fido_cred_set_blob() function sets the “credBlob” to be stored with
142     cred to the data pointed to by ptr, which must be len bytes long.
143
144     The fido_cred_set_pin_minlen() function enables the CTAP 2.1
145     FIDO_EXT_MINPINLEN extension on cred and sets the expected minimum PIN
146     length of cred to len, where len is greater than zero.  If len is zero,
147     the FIDO_EXT_MINPINLEN extension is disabled on cred.
148
149     The fido_cred_set_prot() function enables the CTAP 2.1
150     FIDO_EXT_CRED_PROTECT extension on cred and sets the protection of cred
151     to the scalar prot.  At the moment, only the FIDO_CRED_PROT_UV_OPTIONAL,
152     FIDO_CRED_PROT_UV_OPTIONAL_WITH_ID, and FIDO_CRED_PROT_UV_REQUIRED pro‐
153     tections are supported.  If prot is zero, the protection of cred is
154     cleared.
155
156     The fido_cred_set_rk() and fido_cred_set_uv() functions set the rk
157     (resident/discoverable key) and uv (user verification) attributes of
158     cred.  Both are FIDO_OPT_OMIT by default, allowing the authenticator to
159     use its default settings.
160
161     The fido_cred_set_fmt() function sets the attestation format of cred to
162     fmt, where fmt must be packed (the format used in FIDO2), fido-u2f (the
163     format used by U2F), or none.  A copy of fmt is made, and no references
164     to the passed pointer are kept.  Note that not all authenticators support
165     FIDO2 and therefore may not be able to generate packed.
166
167     The fido_cred_set_type() function sets the type of cred to cose_alg,
168     where cose_alg is COSE_ES256, COSE_RS256, or COSE_EDDSA.  The type of a
169     credential may only be set once.  Note that not all authenticators sup‐
170     port COSE_RS256 or COSE_EDDSA.
171
172     Use of the fido_cred_set_authdata set of functions may happen in two dis‐
173     tinct situations: when generating a new credential on a FIDO2 device,
174     prior to fido_dev_make_cred(3) (i.e, in the context of a FIDO2 client),
175     or when validating a generated credential using fido_cred_verify(3) (i.e,
176     in the context of a FIDO2 server).
177
178     For a complete description of the generation of a FIDO2 credential and
179     its verification, please refer to the FIDO2 specification.  A concrete
180     utilisation example of the fido_cred_set_authdata set of functions can be
181     found in the cred.c example shipped with libfido2.
182

RETURN VALUES

184     The error codes returned by the fido_cred_set_authdata set of functions
185     are defined in <fido/err.h>.  On success, FIDO_OK is returned.
186

SEE ALSO

188     fido_cred_exclude(3), fido_cred_verify(3), fido_dev_make_cred(3)
189
190BSD                              May 23, 2018                              BSD
Impressum