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_clientdata_hash, fido_cred_set_rp,
6     fido_cred_set_user, fido_cred_set_extensions, fido_cred_set_prot,
7     fido_cred_set_rk, fido_cred_set_uv, fido_cred_set_fmt, fido_cred_set_type
8     — set parameters of a FIDO 2 credential
9

SYNOPSIS

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

DESCRIPTION

66     The fido_cred_set_authdata set of functions define the various parameters
67     of a FIDO 2 credential, allowing a fido_cred_t type to be prepared for a
68     subsequent call to fido_dev_make_cred(3) or fido_cred_verify(3).  For the
69     complete specification of a FIDO 2 credential and the format of its con‐
70     stituent parts, please refer to the Web Authentication (webauthn) stan‐
71     dard.
72
73     The fido_cred_set_authdata(), fido_cred_set_x509(), fido_cred_set_sig(),
74     and fido_cred_set_clientdata_hash() functions set the authenticator data,
75     attestation certificate, signature and client data hash parts of cred to
76     ptr, where ptr points to len bytes.  A copy of ptr is made, and no refer‐
77     ences to the passed pointer are kept.  The authenticator data passed to
78     fido_cred_set_authdata() must be a CBOR-encoded byte string, as obtained
79     from fido_cred_authdata_ptr().  Alternatively, a raw binary blob may be
80     passed to fido_cred_set_authdata_raw().
81
82     The fido_cred_set_rp() function sets the relying party id and name param‐
83     eters of cred, where id and name are NUL-terminated UTF-8 strings.  The
84     contents of id and name are copied, and no references to the passed
85     pointers are kept.
86
87     The fido_cred_set_user() function sets the user attributes of cred, where
88     user_id points to user_id_len bytes and name, display_name, and icon are
89     NUL-terminated UTF-8 strings.  The contents of user_id, name,
90     display_name, and icon are copied, and no references to the passed point‐
91     ers are kept.  Previously set user attributes are flushed.  The user_id,
92     name, display_name, and icon parameters may be NULL.
93
94     The fido_cred_set_extensions() function sets the extensions of cred to
95     the bitmask flags.  At the moment, only the FIDO_EXT_HMAC_SECRET and
96     FIDO_EXT_CRED_PROTECT extensions are supported.  If flags is zero, the
97     extensions of cred are cleared.
98
99     The fido_cred_set_prot() function sets the protection of cred to the
100     scalar prot.  At the moment, only the FIDO_CRED_PROT_UV_OPTIONAL,
101     FIDO_CRED_PROT_UV_OPTIONAL_WITH_ID, and FIDO_CRED_PROT_UV_REQUIRED pro‐
102     tections are supported.  If prot is zero, the protection of cred is
103     cleared.
104
105     The fido_cred_set_rk() and fido_cred_set_uv() functions set the rk (resi‐
106     dent key) and uv (user verification) attributes of cred.  Both are
107     FIDO_OPT_OMIT by default, allowing the authenticator to use its default
108     settings.
109
110     The fido_cred_set_fmt() function sets the format of cred to fmt, where
111     fmt must be either packed (the format used in FIDO 2) or fido-u2f (the
112     format used by U2F).  A copy of fmt is made, and no references to the
113     passed pointer are kept.  Note that not all authenticators support FIDO2
114     and therefore may not be able to generate packed.
115
116     The fido_cred_set_type() function sets the type of cred to cose_alg,
117     where cose_alg is COSE_ES256, COSE_RS256, or COSE_EDDSA.  The type of a
118     credential may only be set once.  Note that not all authenticators sup‐
119     port COSE_RS256 or COSE_EDDSA.
120
121     Use of the fido_cred_set_authdata set of functions may happen in two dis‐
122     tinct situations: when generating a new credential on a FIDO device,
123     prior to fido_dev_make_cred(3) (i.e, in the context of a FIDO client), or
124     when validating a generated credential using fido_cred_verify(3) (i.e, in
125     the context of a FIDO server).
126
127     For a complete description of the generation of a FIDO 2 credential and
128     its verification, please refer to the FIDO 2 specification.  A concrete
129     utilisation example of the fido_cred_set_authdata set of functions can be
130     found in the cred.c example shipped with libfido2.
131

RETURN VALUES

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

SEE ALSO

137     fido_cred_exclude(3), fido_cred_verify(3), fido_dev_make_cred(3)
138
139BSD                              May 23, 2018                              BSD
Impressum