diff options
Diffstat (limited to 'man/fido_assert_set_authdata.3')
-rw-r--r-- | man/fido_assert_set_authdata.3 | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/man/fido_assert_set_authdata.3 b/man/fido_assert_set_authdata.3 new file mode 100644 index 0000000..29a86c1 --- /dev/null +++ b/man/fido_assert_set_authdata.3 | |||
@@ -0,0 +1,194 @@ | |||
1 | .\" Copyright (c) 2018 Yubico AB. All rights reserved. | ||
2 | .\" Use of this source code is governed by a BSD-style | ||
3 | .\" license that can be found in the LICENSE file. | ||
4 | .\" | ||
5 | .Dd $Mdocdate: May 23 2018 $ | ||
6 | .Dt FIDO_ASSERT_SET_AUTHDATA 3 | ||
7 | .Os | ||
8 | .Sh NAME | ||
9 | .Nm fido_assert_set_authdata , | ||
10 | .Nm fido_assert_set_authdata_raw , | ||
11 | .Nm fido_assert_set_clientdata_hash , | ||
12 | .Nm fido_assert_set_count , | ||
13 | .Nm fido_assert_set_extensions , | ||
14 | .Nm fido_assert_set_hmac_salt , | ||
15 | .Nm fido_assert_set_up , | ||
16 | .Nm fido_assert_set_uv , | ||
17 | .Nm fido_assert_set_rp , | ||
18 | .Nm fido_assert_set_sig | ||
19 | .Nd set parameters of a FIDO 2 assertion | ||
20 | .Sh SYNOPSIS | ||
21 | .In fido.h | ||
22 | .Bd -literal | ||
23 | typedef enum { | ||
24 | FIDO_OPT_OMIT = 0, /* use authenticator's default */ | ||
25 | FIDO_OPT_FALSE, /* explicitly set option to false */ | ||
26 | FIDO_OPT_TRUE, /* explicitly set option to true */ | ||
27 | } fido_opt_t; | ||
28 | .Ed | ||
29 | .Ft int | ||
30 | .Fn fido_assert_set_authdata "fido_assert_t *assert" " size_t idx" "const unsigned char *ptr" "size_t len" | ||
31 | .Ft int | ||
32 | .Fn fido_assert_set_authdata_raw "fido_assert_t *assert" " size_t idx" "const unsigned char *ptr" "size_t len" | ||
33 | .Ft int | ||
34 | .Fn fido_assert_set_clientdata_hash "fido_assert_t *assert" "const unsigned char *ptr" "size_t len" | ||
35 | .Ft int | ||
36 | .Fn fido_assert_set_count "fido_assert_t *assert" "size_t n" | ||
37 | .Ft int | ||
38 | .Fn fido_assert_set_extensions "fido_assert_t *assert" "int flags" | ||
39 | .Ft int | ||
40 | .Fn fido_assert_set_hmac_salt "fido_assert_t *assert" "const unsigned char *ptr" "size_t len" | ||
41 | .Ft int | ||
42 | .Fn fido_assert_set_up "fido_assert_t *assert" "fido_opt_t up" | ||
43 | .Ft int | ||
44 | .Fn fido_assert_set_uv "fido_assert_t *assert" "fido_opt_t uv" | ||
45 | .Ft int | ||
46 | .Fn fido_assert_set_rp "fido_assert_t *assert" "const char *id" | ||
47 | .Ft int | ||
48 | .Fn fido_assert_set_sig "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len" | ||
49 | .Sh DESCRIPTION | ||
50 | The | ||
51 | .Nm | ||
52 | set of functions define the various parameters of a FIDO 2 | ||
53 | assertion, allowing a | ||
54 | .Fa fido_assert_t | ||
55 | type to be prepared for a subsequent call to | ||
56 | .Xr fido_dev_get_assert 3 | ||
57 | or | ||
58 | .Xr fido_assert_verify 3 . | ||
59 | For the complete specification of a FIDO 2 assertion and the format | ||
60 | of its constituent parts, please refer to the Web Authentication | ||
61 | (webauthn) standard. | ||
62 | .Pp | ||
63 | The | ||
64 | .Fn fido_assert_set_count | ||
65 | function sets the number of assertion statements in | ||
66 | .Fa assert | ||
67 | to | ||
68 | .Fa n . | ||
69 | .Pp | ||
70 | The | ||
71 | .Fn fido_assert_set_authdata | ||
72 | and | ||
73 | .Fn fido_assert_set_sig | ||
74 | functions set the authenticator data and signature parts of the | ||
75 | statement with index | ||
76 | .Fa idx | ||
77 | of | ||
78 | .Fa assert | ||
79 | to | ||
80 | .Fa ptr , | ||
81 | where | ||
82 | .Fa ptr | ||
83 | points to | ||
84 | .Fa len | ||
85 | bytes. | ||
86 | A copy of | ||
87 | .Fa ptr | ||
88 | is made, and no references to the passed pointer are kept. | ||
89 | Please note that the first assertion statement of | ||
90 | .Fa assert | ||
91 | has an | ||
92 | .Fa idx | ||
93 | of | ||
94 | .Em 0 . | ||
95 | The authenticator data passed to | ||
96 | .Fn fido_assert_set_authdata | ||
97 | must be a CBOR-encoded byte string, as obtained from | ||
98 | .Fn fido_assert_authdata_ptr . | ||
99 | Alternatively, a raw binary blob may be passed to | ||
100 | .Fn fido_assert_set_authdata_raw . | ||
101 | .Pp | ||
102 | The | ||
103 | .Fn fido_assert_set_clientdata_hash | ||
104 | and | ||
105 | .Fn fido_assert_set_hmac_salt | ||
106 | functions set the client data hash and hmac-salt parts of | ||
107 | .Fa assert | ||
108 | to | ||
109 | .Fa ptr , | ||
110 | where | ||
111 | .Fa ptr | ||
112 | points to | ||
113 | .Fa len | ||
114 | bytes. | ||
115 | A copy of | ||
116 | .Fa ptr | ||
117 | is made, and no references to the passed pointer are kept. | ||
118 | .Pp | ||
119 | The | ||
120 | .Fn fido_assert_set_rp | ||
121 | function sets the relying party | ||
122 | .Fa id | ||
123 | of | ||
124 | .Fa assert , | ||
125 | where | ||
126 | .Fa id | ||
127 | is a NUL-terminated UTF-8 string. | ||
128 | The content of | ||
129 | .Fa id | ||
130 | is copied, and no references to the passed pointer are kept. | ||
131 | .Pp | ||
132 | The | ||
133 | .Fn fido_assert_set_extensions | ||
134 | function sets the extensions of | ||
135 | .Fa assert | ||
136 | to the bitmask | ||
137 | .Fa flags . | ||
138 | At the moment, only the | ||
139 | .Dv FIDO_EXT_HMAC_SECRET | ||
140 | extension is supported. | ||
141 | If | ||
142 | .Fa flags | ||
143 | is zero, the extensions of | ||
144 | .Fa assert | ||
145 | are cleared. | ||
146 | .Pp | ||
147 | The | ||
148 | .Fn fido_assert_set_up | ||
149 | and | ||
150 | .Fn fido_assert_set_uv | ||
151 | functions set the | ||
152 | .Fa up | ||
153 | (user presence) and | ||
154 | .Fa uv | ||
155 | (user verification) | ||
156 | attributes of | ||
157 | .Fa assert . | ||
158 | Both are | ||
159 | .Dv FIDO_OPT_OMIT | ||
160 | by default, allowing the authenticator to use its default settings. | ||
161 | .Pp | ||
162 | Use of the | ||
163 | .Nm | ||
164 | set of functions may happen in two distinct situations: | ||
165 | when asking a FIDO device to produce a series of assertion | ||
166 | statements, prior to | ||
167 | .Xr fido_dev_get_assert 3 | ||
168 | (i.e, in the context of a FIDO client), or when verifying assertion | ||
169 | statements using | ||
170 | .Xr fido_assert_verify 3 | ||
171 | (i.e, in the context of a FIDO server). | ||
172 | .Pp | ||
173 | For a complete description of the generation of a FIDO 2 assertion | ||
174 | and its verification, please refer to the FIDO 2 specification. | ||
175 | An example of how to use the | ||
176 | .Nm | ||
177 | set of functions can be found in the | ||
178 | .Pa examples/assert.c | ||
179 | file shipped with | ||
180 | .Em libfido2 . | ||
181 | .Sh RETURN VALUES | ||
182 | The | ||
183 | .Nm | ||
184 | functions return | ||
185 | .Dv FIDO_OK | ||
186 | on success. | ||
187 | The error codes returned by the | ||
188 | .Nm | ||
189 | set of functions are defined in | ||
190 | .In fido/err.h . | ||
191 | .Sh SEE ALSO | ||
192 | .Xr fido_assert_allow_cred 3 , | ||
193 | .Xr fido_assert_verify 3 , | ||
194 | .Xr fido_dev_get_assert 3 | ||