diff options
Diffstat (limited to 'man/fido_cred_set_authdata.3')
-rw-r--r-- | man/fido_cred_set_authdata.3 | 240 |
1 files changed, 240 insertions, 0 deletions
diff --git a/man/fido_cred_set_authdata.3 b/man/fido_cred_set_authdata.3 new file mode 100644 index 0000000..8b087fa --- /dev/null +++ b/man/fido_cred_set_authdata.3 | |||
@@ -0,0 +1,240 @@ | |||
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_CRED_SET_AUTHDATA 3 | ||
7 | .Os | ||
8 | .Sh NAME | ||
9 | .Nm fido_cred_set_authdata , | ||
10 | .Nm fido_cred_set_authdata_raw , | ||
11 | .Nm fido_cred_set_x509 , | ||
12 | .Nm fido_cred_set_sig , | ||
13 | .Nm fido_cred_set_clientdata_hash , | ||
14 | .Nm fido_cred_set_rp , | ||
15 | .Nm fido_cred_set_user , | ||
16 | .Nm fido_cred_set_extensions , | ||
17 | .Nm fido_cred_set_rk , | ||
18 | .Nm fido_cred_set_uv , | ||
19 | .Nm fido_cred_set_fmt , | ||
20 | .Nm fido_cred_set_type | ||
21 | .Nd set parameters of a FIDO 2 credential | ||
22 | .Sh SYNOPSIS | ||
23 | .In fido.h | ||
24 | .Bd -literal | ||
25 | typedef enum { | ||
26 | FIDO_OPT_OMIT = 0, /* use authenticator's default */ | ||
27 | FIDO_OPT_FALSE, /* explicitly set option to false */ | ||
28 | FIDO_OPT_TRUE, /* explicitly set option to true */ | ||
29 | } fido_opt_t; | ||
30 | .Ed | ||
31 | .Ft int | ||
32 | .Fn fido_cred_set_authdata "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" | ||
33 | .Ft int | ||
34 | .Fn fido_cred_set_authdata_raw "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" | ||
35 | .Ft int | ||
36 | .Fn fido_cred_set_x509 "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" | ||
37 | .Ft int | ||
38 | .Fn fido_cred_set_sig "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" | ||
39 | .Ft int | ||
40 | .Fn fido_cred_set_clientdata_hash "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" | ||
41 | .Ft int | ||
42 | .Fn fido_cred_set_rp "fido_cred_t *cred" "const char *id" "const char *name" | ||
43 | .Ft int | ||
44 | .Fn fido_cred_set_user "fido_cred_t *cred" "const unsigned char *user_id" "size_t user_id_len" "const char *name" "const char *display_name" "const char *icon" | ||
45 | .Ft int | ||
46 | .Fn fido_cred_set_extensions "fido_cred_t *cred" "int flags" | ||
47 | .Ft int | ||
48 | .Fn fido_cred_set_rk "fido_cred_t *cred" "fido_opt_t rk" | ||
49 | .Ft int | ||
50 | .Fn fido_cred_set_uv "fido_cred_t *cred" "fido_opt_t uv" | ||
51 | .Ft int | ||
52 | .Fn fido_cred_set_fmt "fido_cred_t *cred" "const char *ptr" | ||
53 | .Ft int | ||
54 | .Fn fido_cred_set_type "fido_cred_t *cred" "int cose_alg" | ||
55 | .Sh DESCRIPTION | ||
56 | The | ||
57 | .Nm | ||
58 | set of functions define the various parameters of a FIDO 2 | ||
59 | credential, allowing a | ||
60 | .Fa fido_cred_t | ||
61 | type to be prepared for a subsequent call to | ||
62 | .Xr fido_dev_make_cred 3 | ||
63 | or | ||
64 | .Xr fido_cred_verify 3 . | ||
65 | For the complete specification of a FIDO 2 credential and the format | ||
66 | of its constituent parts, please refer to the Web Authentication | ||
67 | (webauthn) standard. | ||
68 | .Pp | ||
69 | The | ||
70 | .Fn fido_cred_set_authdata , | ||
71 | .Fn fido_cred_set_x509 , | ||
72 | .Fn fido_cred_set_sig , | ||
73 | and | ||
74 | .Fn fido_cred_set_clientdata_hash | ||
75 | functions set the authenticator data, attestation certificate, | ||
76 | signature and client data hash parts of | ||
77 | .Fa cred | ||
78 | to | ||
79 | .Fa ptr , | ||
80 | where | ||
81 | .Fa ptr | ||
82 | points to | ||
83 | .Fa len | ||
84 | bytes. | ||
85 | A copy of | ||
86 | .Fa ptr | ||
87 | is made, and no references to the passed pointer are kept. | ||
88 | The authenticator data passed to | ||
89 | .Fn fido_cred_set_authdata | ||
90 | must be a CBOR-encoded byte string, as obtained from | ||
91 | .Fn fido_cred_authdata_ptr . | ||
92 | Alternatively, a raw binary blob may be passed to | ||
93 | .Fn fido_cred_set_authdata_raw . | ||
94 | .Pp | ||
95 | The | ||
96 | .Fn fido_cred_set_rp | ||
97 | function sets the relying party | ||
98 | .Fa id | ||
99 | and | ||
100 | .Fa name | ||
101 | parameters of | ||
102 | .Fa cred , | ||
103 | where | ||
104 | .Fa id | ||
105 | and | ||
106 | .Fa name | ||
107 | are NUL-terminated UTF-8 strings. | ||
108 | The contents of | ||
109 | .Fa id | ||
110 | and | ||
111 | .Fa name | ||
112 | are copied, and no references to the passed pointers are kept. | ||
113 | .Pp | ||
114 | The | ||
115 | .Fn fido_cred_set_user | ||
116 | function sets the user attributes of | ||
117 | .Fa cred , | ||
118 | where | ||
119 | .Fa user_id | ||
120 | points to | ||
121 | .Fa user_id_len | ||
122 | bytes and | ||
123 | .Fa name , | ||
124 | .Fa display_name , | ||
125 | and | ||
126 | .Fa icon | ||
127 | are NUL-terminated UTF-8 strings. | ||
128 | The contents of | ||
129 | .Fa user_id , | ||
130 | .Fa name , | ||
131 | .Fa display_name , | ||
132 | and | ||
133 | .Fa icon | ||
134 | are copied, and no references to the passed pointers are kept. | ||
135 | Previously set user attributes are flushed. | ||
136 | The | ||
137 | .Fa user_id , | ||
138 | .Fa name , | ||
139 | .Fa display_name , | ||
140 | and | ||
141 | .Fa icon | ||
142 | parameters may be NULL. | ||
143 | .Pp | ||
144 | The | ||
145 | .Fn fido_cred_set_extensions | ||
146 | function sets the extensions of | ||
147 | .Fa cred | ||
148 | to the bitmask | ||
149 | .Fa flags . | ||
150 | At the moment, only the | ||
151 | .Dv FIDO_EXT_HMAC_SECRET | ||
152 | extension is supported. | ||
153 | If | ||
154 | .Fa flags | ||
155 | is zero, the extensions of | ||
156 | .Fa cred | ||
157 | are cleared. | ||
158 | .Pp | ||
159 | The | ||
160 | .Fn fido_cred_set_rk | ||
161 | and | ||
162 | .Fn fido_cred_set_uv | ||
163 | functions set the | ||
164 | .Em rk | ||
165 | (resident key) | ||
166 | and | ||
167 | .Em uv | ||
168 | (user verification) | ||
169 | attributes of | ||
170 | .Fa cred . | ||
171 | Both are | ||
172 | .Dv FIDO_OPT_OMIT | ||
173 | by default, allowing the authenticator to use its default settings. | ||
174 | .Pp | ||
175 | The | ||
176 | .Fn fido_cred_set_fmt | ||
177 | function sets the format of | ||
178 | .Fa cred | ||
179 | to | ||
180 | .Fa fmt , | ||
181 | where | ||
182 | .Fa fmt | ||
183 | must be either | ||
184 | .Vt "packed" | ||
185 | (the format used in FIDO 2) | ||
186 | or | ||
187 | .Vt "fido-u2f" | ||
188 | (the format used by U2F). | ||
189 | A copy of | ||
190 | .Fa fmt | ||
191 | is made, and no references to the passed pointer are kept. | ||
192 | Note that not all authenticators support FIDO2 and therefore may not | ||
193 | be able to generate | ||
194 | .Vt "packed" . | ||
195 | .Pp | ||
196 | The | ||
197 | .Fn fido_cred_set_type | ||
198 | function sets the type of | ||
199 | .Fa cred to | ||
200 | .Fa cose_alg , | ||
201 | where | ||
202 | .Fa cose_alg | ||
203 | is | ||
204 | .Dv COSE_ES256 , | ||
205 | .Dv COSE_RS256 , | ||
206 | or | ||
207 | .Dv COSE_EDDSA . | ||
208 | The type of a credential may only be set once. | ||
209 | Note that not all authenticators support COSE_RS256 or COSE_EDDSA. | ||
210 | .Pp | ||
211 | Use of the | ||
212 | .Nm | ||
213 | set of functions may happen in two distinct situations: | ||
214 | when generating a new credential on a FIDO device, prior to | ||
215 | .Xr fido_dev_make_cred 3 | ||
216 | (i.e, in the context of a FIDO client), or when validating | ||
217 | a generated credential using | ||
218 | .Xr fido_cred_verify 3 | ||
219 | (i.e, in the context of a FIDO server). | ||
220 | .Pp | ||
221 | For a complete description of the generation of a FIDO 2 credential | ||
222 | and its verification, please refer to the FIDO 2 specification. | ||
223 | A concrete utilisation example of the | ||
224 | .Nm | ||
225 | set of functions can be found in the | ||
226 | .Pa cred.c | ||
227 | example shipped with | ||
228 | .Em libfido2 . | ||
229 | .Sh RETURN VALUES | ||
230 | The error codes returned by the | ||
231 | .Nm | ||
232 | set of functions are defined in | ||
233 | .In fido/err.h . | ||
234 | On success, | ||
235 | .Dv FIDO_OK | ||
236 | is returned. | ||
237 | .Sh SEE ALSO | ||
238 | .Xr fido_cred_exclude 3 , | ||
239 | .Xr fido_cred_verify 3 , | ||
240 | .Xr fido_dev_make_cred 3 | ||