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