fido_cred_set_user(3)

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

NAME

4     fido_cred_set_authdata, fido_cred_set_authdata_raw, fido_cred_set_x509,
5     fido_cred_set_sig, fido_cred_set_id, fido_cred_set_clientdata,
6     fido_cred_set_clientdata_hash, fido_cred_set_rp, fido_cred_set_user,
7     fido_cred_set_extensions, fido_cred_set_blob, fido_cred_set_prot,
8     fido_cred_set_rk, fido_cred_set_uv, fido_cred_set_fmt, fido_cred_set_type
9     — set parameters of a FIDO 2 credential
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUES

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

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

SEE ALSO