fido_assert_set_authdata(3)

1FIDO_ASSERT_SET_AUTHD... BSD Library Functions Manual FIDO_ASSERT_SET_AUTHD...
2

NAME

4     fido_assert_set_authdata, fido_assert_set_authdata_raw,
5     fido_assert_set_clientdata, fido_assert_set_clientdata_hash,
6     fido_assert_set_count, fido_assert_set_extensions,
7     fido_assert_set_hmac_salt, fido_assert_set_hmac_secret,
8     fido_assert_set_up, fido_assert_set_uv, fido_assert_set_rp,
9     fido_assert_set_sig — set parameters of a FIDO 2 assertion
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_assert_set_authdata(fido_assert_t *assert, size_t idx,
22         const unsigned char *ptr, size_t len);
23
24     int
25     fido_assert_set_authdata_raw(fido_assert_t *assert, size_t idx,
26         const unsigned char *ptr, size_t len);
27
28     int
29     fido_assert_set_clientdata(fido_assert_t *assert,
30         const unsigned char *ptr, size_t len);
31
32     int
33     fido_assert_set_clientdata_hash(fido_assert_t *assert,
34         const unsigned char *ptr, size_t len);
35
36     int
37     fido_assert_set_count(fido_assert_t *assert, size_t n);
38
39     int
40     fido_assert_set_extensions(fido_assert_t *assert, int flags);
41
42     int
43     fido_assert_set_hmac_salt(fido_assert_t *assert,
44         const unsigned char *ptr, size_t len);
45
46     int
47     fido_assert_set_hmac_secret(fido_assert_t *assert,
48         const unsigned char *ptr, size_t len);
49
50     int
51     fido_assert_set_up(fido_assert_t *assert, fido_opt_t up);
52
53     int
54     fido_assert_set_uv(fido_assert_t *assert, fido_opt_t uv);
55
56     int
57     fido_assert_set_rp(fido_assert_t *assert, const char *id);
58
59     int
60     fido_assert_set_sig(fido_assert_t *assert, size_t idx,
61         const unsigned char *ptr, size_t len);
62

DESCRIPTION

64     The fido_assert_set_authdata set of functions define the various parame‐
65     ters of a FIDO 2 assertion, allowing a fido_assert_t type to be prepared
66     for a subsequent call to fido_dev_get_assert(3) or fido_assert_verify(3).
67     For the complete specification of a FIDO 2 assertion and the format of
68     its constituent parts, please refer to the Web Authentication (webauthn)
69     standard.
70
71     The fido_assert_set_count() function sets the number of assertion state‐
72     ments in assert to n.
73
74     The fido_assert_set_authdata() and fido_assert_set_sig() functions set
75     the authenticator data and signature parts of the statement with index
76     idx of assert to ptr, where ptr points to len bytes.  A copy of ptr is
77     made, and no references to the passed pointer are kept.  Please note that
78     the first assertion statement of assert has an idx of 0.  The authentica‐
79     tor data passed to fido_assert_set_authdata() must be a CBOR-encoded byte
80     string, as obtained from fido_assert_authdata_ptr().  Alternatively, a
81     raw binary blob may be passed to fido_assert_set_authdata_raw().
82
83     The fido_assert_set_clientdata_hash(), fido_assert_set_hmac_salt(), and
84     fido_assert_set_hmac_secret() functions set the client data hash and
85     hmac-salt parts of assert to ptr, where ptr points to len bytes.  A copy
86     of ptr is made, and no references to the passed pointer are kept.
87
88     The fido_assert_set_clientdata() function allows an application to set
89     the client data hash of assert by specifying the assertion's unhashed
90     client data.  This is required by Windows Hello, which calculates the
91     client data hash internally.  For compatibility with Windows Hello, ap‐
92     plications should use fido_assert_set_clientdata() instead of
93     fido_assert_set_clientdata_hash().
94
95     The fido_assert_set_rp() function sets the relying party id of assert,
96     where id is a NUL-terminated UTF-8 string.  The content of id is copied,
97     and no references to the passed pointer are kept.
98
99     The fido_assert_set_extensions() function sets the extensions of assert
100     to the bitmask flags.  At the moment, only the FIDO_EXT_CRED_BLOB,
101     FIDO_EXT_HMAC_SECRET, and FIDO_EXT_LARGEBLOB_KEY extensions are sup‐
102     ported.  If flags is zero, the extensions of assert are cleared.
103
104     The fido_assert_set_up() and fido_assert_set_uv() functions set the up
105     (user presence) and uv (user verification) attributes of assert.  Both
106     are FIDO_OPT_OMIT by default, allowing the authenticator to use its de‐
107     fault settings.
108
109     Use of the fido_assert_set_authdata set of functions may happen in two
110     distinct situations: when asking a FIDO device to produce a series of as‐
111     sertion statements, prior to fido_dev_get_assert(3) (i.e, in the context
112     of a FIDO client), or when verifying assertion statements using
113     fido_assert_verify(3) (i.e, in the context of a FIDO server).
114
115     For a complete description of the generation of a FIDO 2 assertion and
116     its verification, please refer to the FIDO 2 specification.  An example
117     of how to use the fido_assert_set_authdata set of functions can be found
118     in the examples/assert.c file shipped with libfido2.
119
120     fido_assert_set_hmac_secret() is not normally useful in a FIDO client or
121     server — it is provided to enable testing other functionality that relies
122     on retrieving the HMAC secret from an assertion obtained from an authen‐
123     ticator.
124

RETURN VALUES

126     The fido_assert_set_authdata functions return FIDO_OK on success.  The
127     error codes returned by the fido_assert_set_authdata set of functions are
128     defined in <fido/err.h>.
129

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

SEE ALSO