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
|
.\" 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: October 22 2019 $
.Dt FIDO_ASSERT_NEW 3
.Os
.Sh NAME
.Nm fido_assert_new ,
.Nm fido_assert_free ,
.Nm fido_assert_count ,
.Nm fido_assert_user_display_name ,
.Nm fido_assert_user_icon ,
.Nm fido_assert_user_name ,
.Nm fido_assert_authdata_ptr ,
.Nm fido_assert_clientdata_hash_ptr ,
.Nm fido_assert_hmac_secret_ptr ,
.Nm fido_assert_user_id_ptr ,
.Nm fido_assert_sig_ptr ,
.Nm fido_assert_authdata_len ,
.Nm fido_assert_clientdata_hash_len ,
.Nm fido_assert_hmac_secret_len ,
.Nm fido_assert_user_id_len ,
.Nm fido_assert_sig_len ,
.Nm fido_assert_sigcount
.Nd FIDO 2 assertion API
.Sh SYNOPSIS
.In fido.h
.Ft fido_assert_t *
.Fn fido_assert_new "void"
.Ft void
.Fn fido_assert_free "fido_assert_t **assert_p"
.Ft size_t
.Fn fido_assert_count "const fido_assert_t *assert"
.Ft const char *
.Fn fido_assert_user_display_name "const fido_assert_t *assert" "size_t idx"
.Ft const char *
.Fn fido_assert_user_icon "const fido_assert_t *assert" "size_t idx"
.Ft const char *
.Fn fido_assert_user_name "const fido_assert_t *assert" "size_t idx"
.Ft const unsigned char *
.Fn fido_assert_authdata_ptr "const fido_assert_t *assert" "size_t idx"
.Ft const unsigned char *
.Fn fido_assert_clientdata_hash_ptr "const fido_assert_t *assert"
.Ft const unsigned char *
.Fn fido_assert_hmac_secret_ptr "const fido_assert_t *assert" "size_t idx"
.Ft const unsigned char *
.Fn fido_assert_user_id_ptr "const fido_assert_t *assert" "size_t idx"
.Ft const unsigned char *
.Fn fido_assert_sig_ptr "const fido_assert_t *assert" "size_t idx"
.Ft size_t
.Fn fido_assert_authdata_len "const fido_assert_t *assert" "size_t idx"
.Ft size_t
.Fn fido_assert_clientdata_hash_len "const fido_assert_t *assert"
.Ft size_t
.Fn fido_assert_hmac_secret_len "const fido_assert_t *assert" "size_t idx"
.Ft size_t
.Fn fido_assert_user_id_len "const fido_assert_t *assert" "size_t idx"
.Ft size_t
.Fn fido_assert_sig_len "const fido_assert_t *assert" "size_t idx"
.Ft uint32_t
.Fn fido_assert_sigcount "const fido_assert_t *assert" "size_t idx"
.Sh DESCRIPTION
FIDO 2 assertions are abstracted in
.Em libfido2
by the
.Vt fido_assert_t
type.
The functions described in this page allow a
.Vt fido_assert_t
type to be allocated, deallocated, and inspected.
For other operations on
.Vt fido_assert_t ,
please refer to
.Xr fido_assert_set_authdata 3 ,
.Xr fido_assert_allow_cred 3 ,
.Xr fido_assert_verify 3 ,
and
.Xr fido_dev_get_assert 3 .
.Pp
The
.Fn fido_assert_new
function returns a pointer to a newly allocated, empty
.Vt fido_assert_t
type.
If memory cannot be allocated, NULL is returned.
.Pp
The
.Fn fido_assert_free
function releases the memory backing
.Fa *assert_p ,
where
.Fa *assert_p
must have been previously allocated by
.Fn fido_assert_new .
On return,
.Fa *assert_p
is set to NULL.
Either
.Fa assert_p
or
.Fa *assert_p
may be NULL, in which case
.Fn fido_assert_free
is a NOP.
.Pp
The
.Fn fido_assert_count
function returns the number of statements in
.Fa assert .
.Pp
The
.Fn fido_assert_user_display_name ,
.Fn fido_assert_user_icon ,
and
.Fn fido_assert_user_name ,
functions return pointers to the user display name, icon, and
name attributes of statement
.Fa idx
in
.Fa assert .
If not NULL, the values returned by these functions point to
NUL-terminated UTF-8 strings.
.Pp
The
.Fn fido_assert_user_id_ptr ,
.Fn fido_assert_authdata_ptr ,
.Fn fido_assert_hmac_secret_ptr ,
and
.Fn fido_assert_sig_ptr
functions return pointers to the user ID, authenticator data,
hmac-secret, and signature attributes of statement
.Fa idx
in
.Fa assert .
The
.Fn fido_assert_user_id_len ,
.Fn fido_assert_authdata_len ,
.Fn fido_assert_hmac_secret_len ,
and
.Fn fido_assert_sig_len
functions can be used to retrieve the corresponding length of a
specific attribute.
.Pp
The
.Fn fido_assert_sigcount
function can be used to obtain the signature counter of statement
.Fa idx
in
.Fa assert .
.Pp
Please note that the first statement in
.Fa assert
has an
.Fa idx
(index) value of 0.
.Pp
The authenticator data and signature parts of an assertion
statement are typically passed to a FIDO 2 server for verification.
.Pp
The
.Fn fido_assert_clientdata_hash_ptr
function returns a pointer to the client data hash of
.Fa assert .
The corresponding length can be obtained by
.Fn fido_assert_clientdata_hash_len .
.Sh RETURN VALUES
The
.Fn fido_assert_user_display_name ,
.Fn fido_assert_user_icon ,
.Fn fido_assert_user_name ,
.Fn fido_assert_authdata_ptr ,
.Fn fido_assert_clientdata_hash_ptr ,
.Fn fido_assert_user_id_ptr ,
and
.Fn fido_assert_sig_ptr
functions return NULL if the respective field in
.Fa assert
is not set.
If not NULL, returned pointers are guaranteed to exist until any API
function that takes
.Fa assert
without the
.Em const
qualifier is invoked.
.Sh SEE ALSO
.Xr fido_assert_allow_cred 3 ,
.Xr fido_assert_set_authdata 3 ,
.Xr fido_assert_verify 3 ,
.Xr fido_dev_get_assert 3
|