summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
authornicoo <nicoo@debian.org>2020-02-12 13:43:18 +0100
committerNicolas Braud-Santoni <nicolas@braud-santoni.eu>2020-02-12 13:43:18 +0100
commit88a8bdd35ca7fb0c1ce70abdd8262d958fedafc1 (patch)
treece42d9d46d371c05eed82d8bb1e8aa7b2522a769 /man
parent4e06e4554b69e678110563b1cf00a258a202dd7b (diff)
parentc79050aa44b8836d836c5dd22a383a073c28b74b (diff)
Merge upstream release 1.3.0 into debian/sid
Diffstat (limited to 'man')
-rw-r--r--man/CMakeLists.txt314
-rw-r--r--man/NOTES4
-rw-r--r--man/dyc.css14
-rw-r--r--man/eddsa_pk_new.3122
-rw-r--r--man/es256_pk_new.3122
-rw-r--r--man/fido2-assert.1220
-rw-r--r--man/fido2-cred.1238
-rw-r--r--man/fido2-token.1158
-rw-r--r--man/fido_assert_allow_cred.347
-rw-r--r--man/fido_assert_new.3190
-rw-r--r--man/fido_assert_set_authdata.3194
-rw-r--r--man/fido_assert_verify.379
-rw-r--r--man/fido_bio_dev_get_info.3120
-rw-r--r--man/fido_bio_enroll_new.395
-rw-r--r--man/fido_bio_info_new.381
-rw-r--r--man/fido_bio_template.3169
-rw-r--r--man/fido_cbor_info_new.3153
-rw-r--r--man/fido_cred_exclude.360
-rw-r--r--man/fido_cred_new.3157
-rw-r--r--man/fido_cred_set_authdata.3240
-rw-r--r--man/fido_cred_verify.364
-rw-r--r--man/fido_credman_metadata_new.3299
-rw-r--r--man/fido_dev_get_assert.376
-rw-r--r--man/fido_dev_info_manifest.3143
-rw-r--r--man/fido_dev_make_cred.377
-rw-r--r--man/fido_dev_open.3159
-rw-r--r--man/fido_dev_set_io_functions.395
-rw-r--r--man/fido_dev_set_pin.388
-rw-r--r--man/fido_init.340
-rw-r--r--man/fido_strerr.327
-rw-r--r--man/rs256_pk_new.3122
-rw-r--r--man/style.css24
32 files changed, 3991 insertions, 0 deletions
diff --git a/man/CMakeLists.txt b/man/CMakeLists.txt
new file mode 100644
index 0000000..c903ab8
--- /dev/null
+++ b/man/CMakeLists.txt
@@ -0,0 +1,314 @@
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
5find_program(MANDOC_PATH mandoc)
6message(STATUS "MANDOC_PATH: ${MANDOC_PATH}")
7
8if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
9 find_program(GZIP_PATH gzip)
10 message(STATUS "GZIP_PATH: ${GZIP_PATH}")
11endif()
12
13list(APPEND MAN_SOURCES
14 eddsa_pk_new.3
15 es256_pk_new.3
16 fido2-assert.1
17 fido2-cred.1
18 fido2-token.1
19 fido_init.3
20 fido_assert_new.3
21 fido_assert_allow_cred.3
22 fido_assert_set_authdata.3
23 fido_assert_verify.3
24 fido_bio_dev_get_info.3
25 fido_bio_enroll_new.3
26 fido_bio_info_new.3
27 fido_bio_template.3
28 fido_cbor_info_new.3
29 fido_cred_new.3
30 fido_cred_exclude.3
31 fido_credman_metadata_new.3
32 fido_cred_set_authdata.3
33 fido_cred_verify.3
34 fido_dev_get_assert.3
35 fido_dev_info_manifest.3
36 fido_dev_make_cred.3
37 fido_dev_open.3
38 fido_dev_set_io_functions.3
39 fido_dev_set_pin.3
40 fido_strerr.3
41 rs256_pk_new.3
42)
43
44list(APPEND MAN_ALIAS
45 eddsa_pk_new eddsa_pk_free
46 eddsa_pk_new eddsa_pk_from_ptr
47 eddsa_pk_new eddsa_pk_to_EVP_PKEY
48 es256_pk_new es256_pk_free
49 es256_pk_new es256_pk_from_EC_KEY
50 es256_pk_new es256_pk_from_ptr
51 es256_pk_new es256_pk_to_EVP_PKEY
52 fido_assert_new fido_assert_authdata_len
53 fido_assert_new fido_assert_authdata_ptr
54 fido_assert_new fido_assert_clientdata_hash_len
55 fido_assert_new fido_assert_clientdata_hash_ptr
56 fido_assert_new fido_assert_count
57 fido_assert_new fido_assert_free
58 fido_assert_new fido_assert_hmac_secret_len
59 fido_assert_new fido_assert_hmac_secret_ptr
60 fido_assert_new fido_assert_sigcount
61 fido_assert_new fido_assert_sig_len
62 fido_assert_new fido_assert_sig_ptr
63 fido_assert_new fido_assert_user_display_name
64 fido_assert_new fido_assert_user_icon
65 fido_assert_new fido_assert_user_id_len
66 fido_assert_new fido_assert_user_id_ptr
67 fido_assert_new fido_assert_user_name
68 fido_assert_set_authdata fido_assert_set_clientdata_hash
69 fido_assert_set_authdata fido_assert_set_count
70 fido_assert_set_authdata fido_assert_set_extensions
71 fido_assert_set_authdata fido_assert_set_hmac_salt
72 fido_assert_set_authdata fido_assert_set_rp
73 fido_assert_set_authdata fido_assert_set_sig
74 fido_assert_set_authdata fido_assert_set_up
75 fido_assert_set_authdata fido_assert_set_uv
76 fido_bio_dev_get_info fido_bio_dev_enroll_begin
77 fido_bio_dev_get_info fido_bio_dev_enroll_cancel
78 fido_bio_dev_get_info fido_bio_dev_enroll_continue
79 fido_bio_dev_get_info fido_bio_dev_enroll_remove
80 fido_bio_dev_get_info fido_bio_dev_get_template_array
81 fido_bio_dev_get_info fido_bio_dev_set_template_name
82 fido_bio_enroll_new fido_bio_enroll_free
83 fido_bio_enroll_new fido_bio_enroll_last_status
84 fido_bio_enroll_new fido_bio_enroll_remaining_samples
85 fido_bio_info_new fido_bio_info_free
86 fido_bio_info_new fido_bio_info_max_samples
87 fido_bio_info_new fido_bio_info_type
88 fido_bio_template fido_bio_template_array_count
89 fido_bio_template fido_bio_template_array_free
90 fido_bio_template fido_bio_template_array_new
91 fido_bio_template fido_bio_template_free
92 fido_bio_template fido_bio_template_id_len
93 fido_bio_template fido_bio_template_id_ptr
94 fido_bio_template fido_bio_template_name
95 fido_bio_template fido_bio_template_new
96 fido_bio_template fido_bio_template_set_id
97 fido_bio_template fido_bio_template_set_name
98 fido_cbor_info_new fido_cbor_info_aaguid_len
99 fido_cbor_info_new fido_cbor_info_aaguid_ptr
100 fido_cbor_info_new fido_cbor_info_extensions_len
101 fido_cbor_info_new fido_cbor_info_extensions_ptr
102 fido_cbor_info_new fido_cbor_info_free
103 fido_cbor_info_new fido_cbor_info_maxmsgsiz
104 fido_cbor_info_new fido_cbor_info_options_len
105 fido_cbor_info_new fido_cbor_info_options_name_ptr
106 fido_cbor_info_new fido_cbor_info_options_value_ptr
107 fido_cbor_info_new fido_cbor_info_protocols_len
108 fido_cbor_info_new fido_cbor_info_protocols_ptr
109 fido_cbor_info_new fido_cbor_info_versions_len
110 fido_cbor_info_new fido_cbor_info_versions_ptr
111 fido_cbor_info_new fido_dev_get_cbor_info
112 fido_cred_new fido_cred_authdata_len
113 fido_cred_new fido_cred_authdata_ptr
114 fido_cred_new fido_cred_clientdata_hash_len
115 fido_cred_new fido_cred_clientdata_hash_ptr
116 fido_cred_new fido_cred_fmt
117 fido_cred_new fido_cred_free
118 fido_cred_new fido_cred_id_len
119 fido_cred_new fido_cred_id_ptr
120 fido_cred_new fido_cred_pubkey_len
121 fido_cred_new fido_cred_pubkey_ptr
122 fido_cred_new fido_cred_sig_len
123 fido_cred_new fido_cred_sig_ptr
124 fido_cred_new fido_cred_x5c_len
125 fido_cred_new fido_cred_x5c_ptr
126 fido_credman_metadata_new fido_credman_del_dev_rk
127 fido_credman_metadata_new fido_credman_get_dev_metadata
128 fido_credman_metadata_new fido_credman_get_dev_rk
129 fido_credman_metadata_new fido_credman_get_dev_rp
130 fido_credman_metadata_new fido_credman_metadata_free
131 fido_credman_metadata_new fido_credman_rk
132 fido_credman_metadata_new fido_credman_rk_count
133 fido_credman_metadata_new fido_credman_rk_existing
134 fido_credman_metadata_new fido_credman_rk_free
135 fido_credman_metadata_new fido_credman_rk_new
136 fido_credman_metadata_new fido_credman_rk_remaining
137 fido_credman_metadata_new fido_credman_rp_count
138 fido_credman_metadata_new fido_credman_rp_free
139 fido_credman_metadata_new fido_credman_rp_id
140 fido_credman_metadata_new fido_credman_rp_id_hash_len
141 fido_credman_metadata_new fido_credman_rp_id_hash_ptr
142 fido_credman_metadata_new fido_credman_rp_name
143 fido_credman_metadata_new fido_credman_rp_new
144 fido_cred_set_authdata fido_cred_set_authdata_raw
145 fido_cred_set_authdata fido_cred_set_clientdata_hash
146 fido_cred_set_authdata fido_cred_set_extensions
147 fido_cred_set_authdata fido_cred_set_fmt
148 fido_cred_set_authdata fido_cred_set_rk
149 fido_cred_set_authdata fido_cred_set_rp
150 fido_cred_set_authdata fido_cred_set_sig
151 fido_cred_set_authdata fido_cred_set_type
152 fido_cred_set_authdata fido_cred_set_user
153 fido_cred_set_authdata fido_cred_set_uv
154 fido_cred_set_authdata fido_cred_set_x509
155 fido_dev_info_manifest fido_dev_info_free
156 fido_dev_info_manifest fido_dev_info_manufacturer_string
157 fido_dev_info_manifest fido_dev_info_new
158 fido_dev_info_manifest fido_dev_info_path
159 fido_dev_info_manifest fido_dev_info_product
160 fido_dev_info_manifest fido_dev_info_product_string
161 fido_dev_info_manifest fido_dev_info_ptr
162 fido_dev_info_manifest fido_dev_info_vendor
163 fido_dev_open fido_dev_build
164 fido_dev_open fido_dev_cancel
165 fido_dev_open fido_dev_close
166 fido_dev_open fido_dev_flags
167 fido_dev_open fido_dev_force_fido2
168 fido_dev_open fido_dev_force_u2f
169 fido_dev_open fido_dev_free
170 fido_dev_open fido_dev_is_fido2
171 fido_dev_open fido_dev_major
172 fido_dev_open fido_dev_minor
173 fido_dev_open fido_dev_new
174 fido_dev_open fido_dev_protocol
175 fido_dev_set_pin fido_dev_get_retry_count
176 fido_dev_set_pin fido_dev_reset
177 rs256_pk_new rs256_pk_free
178 rs256_pk_new rs256_pk_from_ptr
179 rs256_pk_new rs256_pk_from_RSA
180 rs256_pk_new rs256_pk_to_EVP_PKEY
181)
182
183list(LENGTH MAN_ALIAS MAN_ALIAS_LEN)
184math(EXPR MAN_ALIAS_MAX "${MAN_ALIAS_LEN} - 2")
185
186# man_copy
187foreach(f ${MAN_SOURCES})
188 add_custom_command(OUTPUT ${f}
189 COMMAND cp -f ${CMAKE_SOURCE_DIR}/man/${f} .
190 DEPENDS ${f})
191 list(APPEND COPY_FILES ${f})
192endforeach()
193
194# man_lint
195foreach(f ${MAN_SOURCES})
196 add_custom_command(OUTPUT ${f}.lint
197 COMMAND mandoc -T lint -W warning ${f} > ${f}.lint
198 DEPENDS ${f})
199 list(APPEND LINT_FILES ${f}.lint)
200endforeach()
201
202# man_html
203foreach(f ${MAN_SOURCES})
204 string(REGEX REPLACE ".[13]" "" g ${f})
205 add_custom_command(OUTPUT ${g}.html
206 COMMAND mandoc -T html -O man="%N.html",style=style.css -I os="Yubico AB" ${f} > ${g}.html
207 DEPENDS ${f})
208 list(APPEND HTML_FILES ${g}.html)
209endforeach()
210
211# man_html_partial
212foreach(f ${MAN_SOURCES})
213 string(REGEX REPLACE ".[13]" "" g ${f})
214 add_custom_command(OUTPUT ${g}.partial
215 COMMAND cat ${CMAKE_SOURCE_DIR}/man/dyc.css > ${g}.partial
216 COMMAND mandoc -T html -O man="%N.html",fragment ${f} >> ${g}.partial
217 DEPENDS ${f})
218 list(APPEND HTML_PARTIAL_FILES ${g}.partial)
219endforeach()
220
221# man_gzip
222foreach(f ${MAN_SOURCES})
223 add_custom_command(OUTPUT ${f}.gz
224 COMMAND gzip -c ${f} > ${f}.gz
225 DEPENDS ${f})
226 list(APPEND GZ_FILES ${f}.gz)
227endforeach()
228
229macro(define_symlink_target NAME EXT)
230 foreach(i RANGE 0 ${MAN_ALIAS_MAX} 2)
231 math(EXPR j "${i} + 1")
232 list(GET MAN_ALIAS ${i} SRC)
233 list(GET MAN_ALIAS ${j} DST)
234 add_custom_command(OUTPUT ${DST}.${EXT}
235 COMMAND ln -sf ${SRC}.${EXT} ${DST}.${EXT})
236 list(APPEND ${NAME}_LINK_FILES ${DST}.${EXT})
237 endforeach()
238 add_custom_target(${NAME} DEPENDS ${${NAME}_LINK_FILES})
239endmacro()
240
241add_custom_target(man_copy DEPENDS ${COPY_FILES})
242add_custom_target(man_lint DEPENDS ${LINT_FILES})
243add_custom_target(man_html DEPENDS ${HTML_FILES})
244add_custom_target(man_html_partial DEPENDS ${HTML_PARTIAL_FILES})
245add_custom_target(man_gzip DEPENDS ${GZ_FILES})
246
247define_symlink_target(man_symlink 3)
248define_symlink_target(man_symlink_html html)
249define_symlink_target(man_symlink_html_partial partial)
250define_symlink_target(man_symlink_gzip 3.gz)
251
252add_dependencies(man_symlink man_copy)
253add_dependencies(man_lint man_symlink)
254add_dependencies(man_html man_lint)
255add_dependencies(man_symlink_html man_html)
256add_dependencies(man_html_partial man_lint)
257add_dependencies(man_symlink_html_partial man_html_partial)
258add_custom_target(man ALL)
259
260if(MANDOC_PATH)
261 add_dependencies(man man_symlink_html)
262 add_dependencies(man_gzip man_lint)
263 install(FILES ${CMAKE_SOURCE_DIR}/man/style.css
264 DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/libfido2)
265 foreach(f ${MAN_SOURCES})
266 string(REGEX REPLACE ".[13]" "" f ${f})
267 install(FILES ${CMAKE_BINARY_DIR}/man/${f}.html
268 DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/libfido2)
269 endforeach()
270 foreach(i RANGE 0 ${MAN_ALIAS_MAX} 2)
271 math(EXPR j "${i} + 1")
272 list(GET MAN_ALIAS ${j} DST)
273 install(FILES ${CMAKE_BINARY_DIR}/man/${DST}.html
274 DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/libfido2)
275 endforeach()
276endif()
277
278if(GZIP_PATH)
279 add_dependencies(man_gzip man_copy)
280 add_dependencies(man_symlink_gzip man_gzip)
281 add_dependencies(man man_symlink_gzip)
282 foreach(f ${MAN_SOURCES})
283 if (${f} MATCHES ".1$")
284 install(FILES ${CMAKE_BINARY_DIR}/man/${f}.gz
285 DESTINATION "${CMAKE_INSTALL_PREFIX}/share/man/man1")
286 elseif(${f} MATCHES ".3$")
287 install(FILES ${CMAKE_BINARY_DIR}/man/${f}.gz
288 DESTINATION "${CMAKE_INSTALL_PREFIX}/share/man/man3")
289 endif()
290 endforeach()
291 foreach(i RANGE 0 ${MAN_ALIAS_MAX} 2)
292 math(EXPR j "${i} + 1")
293 list(GET MAN_ALIAS ${j} DST)
294 install(FILES ${CMAKE_BINARY_DIR}/man/${DST}.3.gz
295 DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man/man3)
296 endforeach()
297elseif(NOT MSVC)
298 add_dependencies(man man_symlink)
299 foreach(f ${MAN_SOURCES})
300 if (${f} MATCHES ".1$")
301 install(FILES ${CMAKE_BINARY_DIR}/man/${f}
302 DESTINATION "${CMAKE_INSTALL_PREFIX}/man/man1")
303 elseif(${f} MATCHES ".3$")
304 install(FILES ${CMAKE_BINARY_DIR}/man/${f}
305 DESTINATION "${CMAKE_INSTALL_PREFIX}/man/man3")
306 endif()
307 endforeach()
308 foreach(i RANGE 0 ${MAN_ALIAS_MAX} 2)
309 math(EXPR j "${i} + 1")
310 list(GET MAN_ALIAS ${j} DST)
311 install(FILES ${CMAKE_BINARY_DIR}/man/${DST}.3
312 DESTINATION ${CMAKE_INSTALL_PREFIX}/man/man3)
313 endforeach()
314endif()
diff --git a/man/NOTES b/man/NOTES
new file mode 100644
index 0000000..4a461ff
--- /dev/null
+++ b/man/NOTES
@@ -0,0 +1,4 @@
1To generate .partial files for https://developers.yubico.com/:
2
3$ make -C build man_symlink_html_partial
4$ (cd build/man && pax -p p -r -w *.partial /tmp/partial)
diff --git a/man/dyc.css b/man/dyc.css
new file mode 100644
index 0000000..1ff5b59
--- /dev/null
+++ b/man/dyc.css
@@ -0,0 +1,14 @@
1<style>
2 table.head, table.foot { width: 100%; }
3 td.head-rtitle, td.foot-os { text-align: right; }
4 td.head-vol { text-align: center; }
5 div.Pp { margin: 1ex 0ex; }
6 div.Nd, div.Bf, div.Op { display: inline; }
7 span.Pa, span.Ad { font-style: italic; }
8 span.Ms { font-weight: bold; }
9 dl.Bl-diag > dt { font-weight: bold; }
10 code.Nm, code.Fl, code.Cm, code.Ic, code.In, code.Fd, code.Fn,
11 code.Cd { font-weight: bold; font-family: monospace; }
12 var { font-family: monospace; }
13 .Sh { font-size: 1.5em; padding-top: 1em; padding-bottom: 1em; }
14</style>
diff --git a/man/eddsa_pk_new.3 b/man/eddsa_pk_new.3
new file mode 100644
index 0000000..65bf9a9
--- /dev/null
+++ b/man/eddsa_pk_new.3
@@ -0,0 +1,122 @@
1.\" Copyright (c) 2019 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 15 2019 $
6.Dt EDDSA_PK_NEW 3
7.Os
8.Sh NAME
9.Nm eddsa_pk_new ,
10.Nm eddsa_pk_free ,
11.Nm eddsa_pk_from_EVP_PKEY ,
12.Nm eddsa_pk_from_ptr ,
13.Nm eddsa_pk_to_EVP_PKEY
14.Nd FIDO 2 COSE EDDSA API
15.Sh SYNOPSIS
16.In openssl/evp.h
17.In fido/eddsa.h
18.Ft eddsa_pk_t *
19.Fn eddsa_pk_new "void"
20.Ft void
21.Fn eddsa_pk_free "eddsa_pk_t **pkp"
22.Ft int
23.Fn eddsa_pk_from_EVP_PKEY "eddsa_pk_t *pk" "const EVP_PKEY *pkey"
24.Ft int
25.Fn eddsa_pk_from_ptr "eddsa_pk_t *pk" "const void *ptr" "size_t len"
26.Ft EVP_PKEY *
27.Fn eddsa_pk_to_EVP_PKEY "const eddsa_pk_t *pk"
28.Sh DESCRIPTION
29EDDSA is the name given in the CBOR Object Signing and Encryption
30(COSE) RFC to EDDSA over Curve25519 with SHA-512.
31The COSE EDDSA API of
32.Em libfido2
33is an auxiliary API with routines to convert between the different
34EDDSA public key types used in
35.Em libfido2
36and
37.Em OpenSSL .
38.Pp
39In
40.Em libfido2 ,
41EDDSA public keys are abstracted by the
42.Vt eddsa_pk_t
43type.
44.Pp
45The
46.Fn eddsa_pk_new
47function returns a pointer to a newly allocated, empty
48.Vt eddsa_pk_t
49type.
50If memory cannot be allocated, NULL is returned.
51.Pp
52The
53.Fn eddsa_pk_free
54function releases the memory backing
55.Fa *pkp ,
56where
57.Fa *pkp
58must have been previously allocated by
59.Fn eddsa_pk_new .
60On return,
61.Fa *pkp
62is set to NULL.
63Either
64.Fa pkp
65or
66.Fa *pkp
67may be NULL, in which case
68.Fn eddsa_pk_free
69is a NOP.
70.Pp
71The
72.Fn eddsa_pk_from_EVP_PKEY
73function fills
74.Fa pk
75with the contents of
76.Fa pkey .
77No references to
78.Fa pkey
79are kept.
80.Pp
81The
82.Fn eddsa_pk_from_ptr
83function fills
84.Fa pk
85with the contents of
86.Fa ptr ,
87where
88.Fa ptr
89points to
90.Fa len
91bytes.
92No references to
93.Fa ptr
94are kept.
95.Pp
96The
97.Fn eddsa_pk_to_EVP_PKEY
98function converts
99.Fa pk
100to a newly allocated
101.Fa EVP_PKEY
102type with a reference count of 1.
103No internal references to the returned pointer are kept.
104If an error occurs,
105.Fn eddsa_pk_to_EVP_PKEY
106returns NULL.
107.Sh RETURN VALUES
108The
109.Fn eddsa_pk_from_EC_KEY
110and
111.Fn eddsa_pk_from_ptr
112functions return
113.Dv FIDO_OK
114on success.
115On error, a different error code defined in
116.In fido/err.h
117is returned.
118.Sh SEE ALSO
119.Xr es256_pk_new 3 ,
120.Xr fido_assert_verify 3 ,
121.Xr fido_cred_pubkey_ptr 3 ,
122.Xr rs256_pk_new 3
diff --git a/man/es256_pk_new.3 b/man/es256_pk_new.3
new file mode 100644
index 0000000..48eda0b
--- /dev/null
+++ b/man/es256_pk_new.3
@@ -0,0 +1,122 @@
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 24 2018 $
6.Dt ES256_PK_NEW 3
7.Os
8.Sh NAME
9.Nm es256_pk_new ,
10.Nm es256_pk_free ,
11.Nm es256_pk_from_EC_KEY ,
12.Nm es256_pk_from_ptr ,
13.Nm es256_pk_to_EVP_PKEY
14.Nd FIDO 2 COSE ES256 API
15.Sh SYNOPSIS
16.In openssl/ec.h
17.In fido/es256.h
18.Ft es256_pk_t *
19.Fn es256_pk_new "void"
20.Ft void
21.Fn es256_pk_free "es256_pk_t **pkp"
22.Ft int
23.Fn es256_pk_from_EC_KEY "es256_pk_t *pk" "const EC_KEY *ec"
24.Ft int
25.Fn es256_pk_from_ptr "es256_pk_t *pk" "const void *ptr" "size_t len"
26.Ft EVP_PKEY *
27.Fn es256_pk_to_EVP_PKEY "const es256_pk_t *pk"
28.Sh DESCRIPTION
29ES256 is the name given in the CBOR Object Signing and Encryption
30(COSE) RFC to ECDSA over P-256 with SHA-256.
31The COSE ES256 API of
32.Em libfido2
33is an auxiliary API with routines to convert between the different
34ECDSA public key types used in
35.Em libfido2
36and
37.Em OpenSSL .
38.Pp
39In
40.Em libfido2 ,
41ES256 public keys are abstracted by the
42.Vt es256_pk_t
43type.
44.Pp
45The
46.Fn es256_pk_new
47function returns a pointer to a newly allocated, empty
48.Vt es256_pk_t
49type.
50If memory cannot be allocated, NULL is returned.
51.Pp
52The
53.Fn es256_pk_free
54function releases the memory backing
55.Fa *pkp ,
56where
57.Fa *pkp
58must have been previously allocated by
59.Fn es256_pk_new .
60On return,
61.Fa *pkp
62is set to NULL.
63Either
64.Fa pkp
65or
66.Fa *pkp
67may be NULL, in which case
68.Fn es256_pk_free
69is a NOP.
70.Pp
71The
72.Fn es256_pk_from_EC_KEY
73function fills
74.Fa pk
75with the contents of
76.Fa ec .
77No references to
78.Fa ec
79are kept.
80.Pp
81The
82.Fn es256_pk_from_ptr
83function fills
84.Fa pk
85with the contents of
86.Fa ptr ,
87where
88.Fa ptr
89points to
90.Fa len
91bytes.
92No references to
93.Fa ptr
94are kept.
95.Pp
96The
97.Fn es256_pk_to_EVP_PKEY
98function converts
99.Fa pk
100to a newly allocated
101.Fa EVP_PKEY
102type with a reference count of 1.
103No internal references to the returned pointer are kept.
104If an error occurs,
105.Fn es256_pk_to_EVP_PKEY
106returns NULL.
107.Sh RETURN VALUES
108The
109.Fn es256_pk_from_EC_KEY
110and
111.Fn es256_pk_from_ptr
112functions return
113.Dv FIDO_OK
114on success.
115On error, a different error code defined in
116.In fido/err.h
117is returned.
118.Sh SEE ALSO
119.Xr eddsa_pk_new 3 ,
120.Xr fido_assert_verify 3 ,
121.Xr fido_cred_pubkey_ptr 3 ,
122.Xr rs256_pk_new 3
diff --git a/man/fido2-assert.1 b/man/fido2-assert.1
new file mode 100644
index 0000000..67883e2
--- /dev/null
+++ b/man/fido2-assert.1
@@ -0,0 +1,220 @@
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: November 5 2019 $
6.Dt FIDO2-ASSERT 1
7.Os
8.Sh NAME
9.Nm fido2-assert
10.Nd get/verify a FIDO 2 assertion
11.Sh SYNOPSIS
12.Nm
13.Fl G
14.Op Fl dhpruv
15.Op Fl i Ar input_file
16.Op Fl o Ar output_file
17.Ar device
18.Nm
19.Fl V
20.Op Fl dhpv
21.Op Fl i Ar input_file
22.Ar key_file
23.Op Ar type
24.Sh DESCRIPTION
25.Nm
26gets or verifies a FIDO 2 assertion.
27.Pp
28The input of
29.Nm
30is defined by the parameters of the assertion to be obtained/verified.
31See the
32.Sx INPUT FORMAT
33section for details.
34.Pp
35The output of
36.Nm
37is defined by the result of the selected operation.
38See the
39.Sx OUTPUT FORMAT
40section for details.
41.Pp
42If an assertion is successfully obtained or verified,
43.Nm
44exits 0.
45Otherwise,
46.Nm
47exits 1.
48.Pp
49The options are as follows:
50.Bl -tag -width Ds
51.It Fl G
52Tells
53.Nm
54to obtain a new assertion from
55.Ar device .
56.It Fl V
57Tells
58.Nm
59to verify an assertion using the PEM-encoded public key in
60.Ar key_file
61of type
62.Ar type ,
63where
64.Ar type
65may be
66.Em es256
67(denoting ECDSA over NIST P-256 with SHA-256),
68.Em rs256
69(denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or
70.Em eddsa
71(denoting EDDSA over Curve25519 with SHA-512).
72If
73.Ar type
74is not specified,
75.Em es256
76is assumed.
77.It Fl h
78If obtaining an assertion, enable the FIDO2 hmac-secret
79extension.
80If verifying an assertion, check whether the extension data bit was
81signed by the authenticator.
82.It Fl d
83Causes
84.Nm
85to emit debugging output on
86.Em stderr .
87.It Fl i Ar input_file
88Tells
89.Nm
90to read the parameters of the assertion from
91.Ar input_file
92instead of
93.Em stdin .
94.It Fl o Ar output_file
95Tells
96.Nm
97to write output on
98.Ar output_file
99instead of
100.Em stdout .
101.It Fl p
102If obtaining an assertion, request user presence.
103If verifying an assertion, check whether the user presence bit was
104signed by the authenticator.
105.It Fl r
106Obtain an assertion using a resident credential.
107If
108.Fl r
109is specified,
110.Nm
111will not expect a credential id in its input, and may output
112multiple assertions.
113.It Fl u
114Obtain an assertion using U2F.
115By default,
116.Nm
117will use FIDO2 if supported by the authenticator, and fallback to
118U2F otherwise.
119.It Fl v
120If obtaining an assertion, prompt the user for a PIN and request
121user verification from the authenticator.
122If a
123.Em tty
124is available,
125.Nm
126will use it to obtain the PIN.
127Otherwise,
128.Em stdin
129is used.
130If verifying an assertion, check whether the user verification bit
131was signed by the authenticator.
132.El
133.Sh INPUT FORMAT
134The input of
135.Nm
136consists of base64 blobs and UTF-8 strings separated
137by newline characters ('\\n').
138.Pp
139When obtaining an assertion,
140.Nm
141expects its input to consist of:
142.Pp
143.Bl -enum -offset indent -compact
144.It
145client data hash (base64 blob);
146.It
147relying party id (UTF-8 string);
148.It
149credential id, if credential not resident (base64 blob);
150.It
151hmac salt, if the FIDO2 hmac-secret extension is enabled
152(base64 blob);
153.El
154.Pp
155When verifying an assertion,
156.Nm
157expects its input to consist of:
158.Pp
159.Bl -enum -offset indent -compact
160.It
161client data hash (base64 blob);
162.It
163relying party id (UTF-8 string);
164.It
165authenticator data (base64 blob);
166.It
167assertion signature (base64 blob);
168.El
169.Pp
170UTF-8 strings passed to
171.Nm
172must not contain embedded newline or NUL characters.
173.Sh OUTPUT FORMAT
174The output of
175.Nm
176consists of base64 blobs and UTF-8 strings separated
177by newline characters ('\\n').
178.Pp
179For each generated assertion,
180.Nm
181outputs:
182.Pp
183.Bl -enum -offset indent -compact
184.It
185client data hash (base64 blob);
186.It
187relying party id (UTF-8 string);
188.It
189authenticator data (base64 blob);
190.It
191assertion signature (base64 blob);
192.It
193user id, if credential resident (base64 blob);
194.It
195hmac secret, if the FIDO2 hmac-secret extension is enabled
196(base64 blob);
197.El
198.Pp
199When verifying an assertion,
200.Nm
201produces no output.
202.Sh EXAMPLES
203Assuming
204.Pa cred
205contains a
206.Em es256
207credential created according to the steps outlined in
208.Xr fido2-cred 1 ,
209obtain an assertion from an authenticator at
210.Pa /dev/hidraw5
211and verify it:
212.Pp
213.Dl $ echo assertion challenge | openssl sha256 -binary | base64 > assert_param
214.Dl $ echo relying party >> assert_param
215.Dl $ head -1 cred >> assert_param
216.Dl $ tail -n +2 cred > pubkey
217.Dl $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V pubkey es256
218.Sh SEE ALSO
219.Xr fido2-cred 1 ,
220.Xr fido2-token 1
diff --git a/man/fido2-cred.1 b/man/fido2-cred.1
new file mode 100644
index 0000000..d9bf7d2
--- /dev/null
+++ b/man/fido2-cred.1
@@ -0,0 +1,238 @@
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: November 5 2019 $
6.Dt FIDO2-CRED 1
7.Os
8.Sh NAME
9.Nm fido2-cred
10.Nd make/verify a FIDO 2 credential
11.Sh SYNOPSIS
12.Nm
13.Fl M
14.Op Fl dhqruv
15.Op Fl i Ar input_file
16.Op Fl o Ar output_file
17.Ar device
18.Op Ar type
19.Nm
20.Fl V
21.Op Fl dhv
22.Op Fl i Ar input_file
23.Op Fl o Ar output_file
24.Op Ar type
25.Sh DESCRIPTION
26.Nm
27makes or verifies a FIDO 2 credential.
28.Pp
29A credential
30.Ar type
31may be
32.Em es256
33(denoting ECDSA over NIST P-256 with SHA-256),
34.Em rs256
35(denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or
36.Em eddsa
37(denoting EDDSA over Curve25519 with SHA-512).
38If
39.Ar type
40is not specified,
41.Em es256
42is assumed.
43.Pp
44When making a credential, the authenticator may require the user
45to authenticate with a PIN.
46If the
47.Fl q
48option is not specified,
49.Nm
50will prompt the user for the PIN.
51If a
52.Em tty
53is available,
54.Nm
55will use it to obtain the PIN.
56Otherwise,
57.Em stdin
58is used.
59.Pp
60The input of
61.Nm
62is defined by the parameters of the credential to be made/verified.
63See the
64.Sx INPUT FORMAT
65section for details.
66.Pp
67The output of
68.Nm
69is defined by the result of the selected operation.
70See the
71.Sx OUTPUT FORMAT
72section for details.
73.Pp
74If a credential is successfully created or verified,
75.Nm
76exits 0.
77Otherwise,
78.Nm
79exits 1.
80.Pp
81The options are as follows:
82.Bl -tag -width Ds
83.It Fl M
84Tells
85.Nm
86to make a new credential on
87.Ar device .
88.It Fl V
89Tells
90.Nm
91to verify a credential.
92.It Fl d
93Causes
94.Nm
95to emit debugging output on
96.Em stderr .
97.It Fl h
98If making a credential, enable the FIDO2 hmac-secret extension.
99If verifying a credential, check whether the extension data bit was
100signed by the authenticator.
101.It Fl i Ar input_file
102Tells
103.Nm
104to read the parameters of the credential from
105.Ar input_file
106instead of
107.Em stdin .
108.It Fl o Ar output_file
109Tells
110.Nm
111to write output on
112.Ar output_file
113instead of
114.Em stdout .
115.It Fl q
116Tells
117.Nm
118to be quiet.
119If a PIN is required and
120.Fl q
121is specified,
122.Nm
123will fail.
124.It Fl r
125Create a resident credential.
126.It Fl u
127Create a U2F credential.
128By default,
129.Nm
130will use FIDO2 if supported by the authenticator, and fallback to
131U2F otherwise.
132.It Fl v
133If making a credential, request user verification.
134If verifying a credential, check whether the user verification bit
135was signed by the authenticator.
136.El
137.Sh INPUT FORMAT
138The input of
139.Nm
140consists of base64 blobs and UTF-8 strings separated
141by newline characters ('\\n').
142.Pp
143When making a credential,
144.Nm
145expects its input to consist of:
146.Pp
147.Bl -enum -offset indent -compact
148.It
149client data hash (base64 blob);
150.It
151relying party id (UTF-8 string);
152.It
153user name (UTF-8 string);
154.It
155user id (base64 blob).
156.El
157.Pp
158When verifying a credential,
159.Nm
160expects its input to consist of:
161.Pp
162.Bl -enum -offset indent -compact
163.It
164client data hash (base64 blob);
165.It
166relying party id (UTF-8 string);
167.It
168credential format (UTF-8 string);
169.It
170authenticator data (base64 blob);
171.It
172credential id (base64 blob);
173.It
174attestation signature (base64 blob);
175.It
176attestation certificate (optional, base64 blob).
177.El
178.Pp
179UTF-8 strings passed to
180.Nm
181must not contain embedded newline or NUL characters.
182.Sh OUTPUT FORMAT
183The output of
184.Nm
185consists of base64 blobs, UTF-8 strings, and PEM-encoded public
186keys separated by newline characters ('\\n').
187.Pp
188Upon the successful generation of a credential,
189.Nm
190outputs:
191.Pp
192.Bl -enum -offset indent -compact
193.It
194client data hash (base64 blob);
195.It
196relying party id (UTF-8 string);
197.It
198credential format (UTF-8 string);
199.It
200authenticator data (base64 blob);
201.It
202credential id (base64 blob);
203.It
204attestation signature (base64 blob);
205.It
206attestation certificate, if present (base64 blob).
207.El
208.Pp
209Upon the successful verification of a credential,
210.Nm
211outputs:
212.Pp
213.Bl -enum -offset indent -compact
214.It
215credential id (base64 blob);
216.It
217PEM-encoded credential key.
218.El
219.Sh EXAMPLES
220Create a new
221.Em es256
222credential on
223.Pa /dev/hidraw5 ,
224verify it, and save the id and the public key of the credential in
225.Em cred :
226.Pp
227.Dl $ echo credential challenge | openssl sha256 -binary | base64 > cred_param
228.Dl $ echo relying party >> cred_param
229.Dl $ echo user name >> cred_param
230.Dl $ dd if=/dev/urandom bs=1 count=32 | base64 >> cred_param
231.Dl $ fido2-cred -M -i cred_param /dev/hidraw5 | fido2-cred -V -o cred
232.Sh SEE ALSO
233.Xr fido2-assert 1 ,
234.Xr fido2-token 1
235.Sh CAVEATS
236Please note that
237.Nm
238handles Basic Attestation and Self Attestation transparently.
diff --git a/man/fido2-token.1 b/man/fido2-token.1
new file mode 100644
index 0000000..d5a5734
--- /dev/null
+++ b/man/fido2-token.1
@@ -0,0 +1,158 @@
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: September 13 2019 $
6.Dt FIDO2-TOKEN 1
7.Os
8.Sh NAME
9.Nm fido2-token
10.Nd find and manage a FIDO 2 authenticator
11.Sh SYNOPSIS
12.Nm
13.Op Fl CR
14.Op Fl d
15.Ar device
16.Nm
17.Fl D
18.Op Fl de
19.Fl i
20.Ar id
21.Ar device
22.Nm
23.Fl I
24.Op Fl cd
25.Op Fl k Ar rp_id Fl i Ar cred_id
26.Ar device
27.Nm
28.Fl L
29.Op Fl der
30.Op Fl k Ar rp_id
31.Op device
32.Nm
33.Fl S
34.Op Fl de
35.Op Fl i Ar template_id Fl n Ar template_name
36.Ar device
37.Nm
38.Fl V
39.Sh DESCRIPTION
40.Nm
41manages a FIDO 2 authenticator.
42.Pp
43The options are as follows:
44.Bl -tag -width Ds
45.It Fl C Ar device
46Changes the PIN of
47.Ar device .
48The user will be prompted for the current and new PINs.
49.It Fl D Fl i Ar id Ar device
50Deletes the resident credential specified by
51.Ar id
52from
53.Ar device ,
54where
55.Ar id
56is the credential's base64-encoded id.
57The user will be prompted for the PIN.
58.It Fl D Fl e Fl i Ar id Ar device
59Deletes the biometric enrollment specified by
60.Ar id
61from
62.Ar device ,
63where
64.Ar id
65is the enrollment's template base64-encoded id.
66The user will be prompted for the PIN.
67.It Fl I Ar device
68Retrieves information on
69.Ar device .
70.It Fl I Fl c Ar device
71Retrieves resident credential metadata from
72.Ar device .
73The user will be prompted for the PIN.
74.It Fl I Fl k Ar rp_id Fl i Ar cred_id Ar device
75Prints the credential id (base64-encoded) and public key
76(PEM encoded) of the resident credential specified by
77.Ar rp_id
78and
79.Ar cred_id ,
80where
81.Ar rp_id
82is a UTF-8 relying party id, and
83.Ar cred_id
84is a base64-encoded credential id.
85The user will be prompted for the PIN.
86.It Fl L
87Produces a list of authenticators found by the operating system.
88.It Fl L Fl e Ar device
89Produces a list of biometric enrollments on
90.Ar device .
91The user will be prompted for the PIN.
92.It Fl L Fl r Ar device
93Produces a list of relying parties with resident credentials on
94.Ar device .
95The user will be prompted for the PIN.
96.It Fl L Fl k Ar rp_id Ar device
97Produces a list of resident credentials corresponding to
98relying party
99.Ar rp_id
100on
101.Ar device .
102The user will be prompted for the PIN.
103.It Fl R
104Performs a reset on
105.Ar device .
106.Nm
107will NOT prompt for confirmation.
108.It Fl S
109Sets the PIN of
110.Ar device .
111The user will be prompted for the PIN.
112.It Fl S Fl e Ar device
113Performs a new biometric enrollment on
114.Ar device .
115The user will be prompted for the PIN.
116.It Fl S Fl e Fl i Ar template_id Fl n Ar template_name Ar device
117Sets the friendly name of the biometric enrollment specified by
118.Ar template_id
119to
120.Ar template_name
121on
122.Ar device ,
123where
124.Ar template_id
125is base64-encoded and
126.Ar template_name
127is a UTF-8 string.
128The user will be prompted for the PIN.
129.It Fl V
130Prints version information.
131.It Fl d
132Causes
133.Nm
134to emit debugging output on
135.Em stderr .
136.El
137.Pp
138If a
139.Em tty
140is available,
141.Nm
142will use it to prompt for PINs.
143Otherwise,
144.Em stdin
145is used.
146.Pp
147.Nm
148exits 0 on success and 1 on error.
149.Sh SEE ALSO
150.Xr fido2-assert 1 ,
151.Xr fido2-cred 1
152.Sh CAVEATS
153The actual user-flow to perform a reset is outside the scope of the
154FIDO2 specification, and may therefore vary depending on the
155authenticator.
156Yubico authenticators do not allow resets after 5 seconds from
157power-up, and expect a reset to be confirmed by the user through
158touch within 30 seconds.
diff --git a/man/fido_assert_allow_cred.3 b/man/fido_assert_allow_cred.3
new file mode 100644
index 0000000..bbe6e4d
--- /dev/null
+++ b/man/fido_assert_allow_cred.3
@@ -0,0 +1,47 @@
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_ALLOW_CRED 3
7.Os
8.Sh NAME
9.Nm fido_assert_allow_cred
10.Nd appends a credential ID to the list of credentials allowed in an assertion
11.Sh SYNOPSIS
12.In fido.h
13.Ft int
14.Fn fido_assert_allow_cred "fido_assert_t *assert" "const unsigned char *ptr" "size_t len"
15.Sh DESCRIPTION
16The
17.Fn fido_assert_allow_cred
18function adds
19.Fa ptr
20to the list of credentials allowed in
21.Fa assert ,
22where
23.Fa ptr
24points to a credential ID of
25.Fa len
26bytes.
27A copy of
28.Fa ptr
29is made, and no references to the passed pointer are kept.
30If
31.Fn fido_assert_allow_cred
32fails, the existing list of allowed credentials is preserved.
33.Pp
34For the format of a FIDO 2 credential ID, please refer to the
35Web Authentication (webauthn) standard.
36.Sh RETURN VALUES
37The error codes returned by
38.Fn fido_assert_allow_cred
39are defined in
40.In fido/err.h .
41On success,
42.Dv FIDO_OK
43is returned.
44.Sh SEE ALSO
45.Xr fido_assert_new 3 ,
46.Xr fido_assert_set_authdata 3 ,
47.Xr fido_dev_get_assert 3
diff --git a/man/fido_assert_new.3 b/man/fido_assert_new.3
new file mode 100644
index 0000000..0c2f92f
--- /dev/null
+++ b/man/fido_assert_new.3
@@ -0,0 +1,190 @@
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: October 22 2019 $
6.Dt FIDO_ASSERT_NEW 3
7.Os
8.Sh NAME
9.Nm fido_assert_new ,
10.Nm fido_assert_free ,
11.Nm fido_assert_count ,
12.Nm fido_assert_user_display_name ,
13.Nm fido_assert_user_icon ,
14.Nm fido_assert_user_name ,
15.Nm fido_assert_authdata_ptr ,
16.Nm fido_assert_clientdata_hash_ptr ,
17.Nm fido_assert_hmac_secret_ptr ,
18.Nm fido_assert_user_id_ptr ,
19.Nm fido_assert_sig_ptr ,
20.Nm fido_assert_authdata_len ,
21.Nm fido_assert_clientdata_hash_len ,
22.Nm fido_assert_hmac_secret_len ,
23.Nm fido_assert_user_id_len ,
24.Nm fido_assert_sig_len ,
25.Nm fido_assert_sigcount
26.Nd FIDO 2 assertion API
27.Sh SYNOPSIS
28.In fido.h
29.Ft fido_assert_t *
30.Fn fido_assert_new "void"
31.Ft void
32.Fn fido_assert_free "fido_assert_t **assert_p"
33.Ft size_t
34.Fn fido_assert_count "const fido_assert_t *assert"
35.Ft const char *
36.Fn fido_assert_user_display_name "const fido_assert_t *assert" "size_t idx"
37.Ft const char *
38.Fn fido_assert_user_icon "const fido_assert_t *assert" "size_t idx"
39.Ft const char *
40.Fn fido_assert_user_name "const fido_assert_t *assert" "size_t idx"
41.Ft const unsigned char *
42.Fn fido_assert_authdata_ptr "const fido_assert_t *assert" "size_t idx"
43.Ft const unsigned char *
44.Fn fido_assert_clientdata_hash_ptr "const fido_assert_t *assert"
45.Ft const unsigned char *
46.Fn fido_assert_hmac_secret_ptr "const fido_assert_t *assert" "size_t idx"
47.Ft const unsigned char *
48.Fn fido_assert_user_id_ptr "const fido_assert_t *assert" "size_t idx"
49.Ft const unsigned char *
50.Fn fido_assert_sig_ptr "const fido_assert_t *assert" "size_t idx"
51.Ft size_t
52.Fn fido_assert_authdata_len "const fido_assert_t *assert" "size_t idx"
53.Ft size_t
54.Fn fido_assert_clientdata_hash_len "const fido_assert_t *assert"
55.Ft size_t
56.Fn fido_assert_hmac_secret_len "const fido_assert_t *assert" "size_t idx"
57.Ft size_t
58.Fn fido_assert_user_id_len "const fido_assert_t *assert" "size_t idx"
59.Ft size_t
60.Fn fido_assert_sig_len "const fido_assert_t *assert" "size_t idx"
61.Ft uint32_t
62.Fn fido_assert_sigcount "const fido_assert_t *assert" "size_t idx"
63.Sh DESCRIPTION
64FIDO 2 assertions are abstracted in
65.Em libfido2
66by the
67.Vt fido_assert_t
68type.
69The functions described in this page allow a
70.Vt fido_assert_t
71type to be allocated, deallocated, and inspected.
72For other operations on
73.Vt fido_assert_t ,
74please refer to
75.Xr fido_assert_set_authdata 3 ,
76.Xr fido_assert_allow_cred 3 ,
77.Xr fido_assert_verify 3 ,
78and
79.Xr fido_dev_get_assert 3 .
80.Pp
81The
82.Fn fido_assert_new
83function returns a pointer to a newly allocated, empty
84.Vt fido_assert_t
85type.
86If memory cannot be allocated, NULL is returned.
87.Pp
88The
89.Fn fido_assert_free
90function releases the memory backing
91.Fa *assert_p ,
92where
93.Fa *assert_p
94must have been previously allocated by
95.Fn fido_assert_new .
96On return,
97.Fa *assert_p
98is set to NULL.
99Either
100.Fa assert_p
101or
102.Fa *assert_p
103may be NULL, in which case
104.Fn fido_assert_free
105is a NOP.
106.Pp
107The
108.Fn fido_assert_count
109function returns the number of statements in
110.Fa assert .
111.Pp
112The
113.Fn fido_assert_user_display_name ,
114.Fn fido_assert_user_icon ,
115and
116.Fn fido_assert_user_name ,
117functions return pointers to the user display name, icon, and
118name attributes of statement
119.Fa idx
120in
121.Fa assert .
122If not NULL, the values returned by these functions point to
123NUL-terminated UTF-8 strings.
124.Pp
125The
126.Fn fido_assert_user_id_ptr ,
127.Fn fido_assert_authdata_ptr ,
128.Fn fido_assert_hmac_secret_ptr ,
129and
130.Fn fido_assert_sig_ptr
131functions return pointers to the user ID, authenticator data,
132hmac-secret, and signature attributes of statement
133.Fa idx
134in
135.Fa assert .
136The
137.Fn fido_assert_user_id_len ,
138.Fn fido_assert_authdata_len ,
139.Fn fido_assert_hmac_secret_len ,
140and
141.Fn fido_assert_sig_len
142functions can be used to retrieve the corresponding length of a
143specific attribute.
144.Pp
145The
146.Fn fido_assert_sigcount
147function can be used to obtain the signature counter of statement
148.Fa idx
149in
150.Fa assert .
151.Pp
152Please note that the first statement in
153.Fa assert
154has an
155.Fa idx
156(index) value of 0.
157.Pp
158The authenticator data and signature parts of an assertion
159statement are typically passed to a FIDO 2 server for verification.
160.Pp
161The
162.Fn fido_assert_clientdata_hash_ptr
163function returns a pointer to the client data hash of
164.Fa assert .
165The corresponding length can be obtained by
166.Fn fido_assert_clientdata_hash_len .
167.Sh RETURN VALUES
168The
169.Fn fido_assert_user_display_name ,
170.Fn fido_assert_user_icon ,
171.Fn fido_assert_user_name ,
172.Fn fido_assert_authdata_ptr ,
173.Fn fido_assert_clientdata_hash_ptr ,
174.Fn fido_assert_user_id_ptr ,
175and
176.Fn fido_assert_sig_ptr
177functions return NULL if the respective field in
178.Fa assert
179is not set.
180If not NULL, returned pointers are guaranteed to exist until any API
181function that takes
182.Fa assert
183without the
184.Em const
185qualifier is invoked.
186.Sh SEE ALSO
187.Xr fido_assert_allow_cred 3 ,
188.Xr fido_assert_set_authdata 3 ,
189.Xr fido_assert_verify 3 ,
190.Xr fido_dev_get_assert 3
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
23typedef 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
50The
51.Nm
52set of functions define the various parameters of a FIDO 2
53assertion, allowing a
54.Fa fido_assert_t
55type to be prepared for a subsequent call to
56.Xr fido_dev_get_assert 3
57or
58.Xr fido_assert_verify 3 .
59For the complete specification of a FIDO 2 assertion and the format
60of its constituent parts, please refer to the Web Authentication
61(webauthn) standard.
62.Pp
63The
64.Fn fido_assert_set_count
65function sets the number of assertion statements in
66.Fa assert
67to
68.Fa n .
69.Pp
70The
71.Fn fido_assert_set_authdata
72and
73.Fn fido_assert_set_sig
74functions set the authenticator data and signature parts of the
75statement with index
76.Fa idx
77of
78.Fa assert
79to
80.Fa ptr ,
81where
82.Fa ptr
83points to
84.Fa len
85bytes.
86A copy of
87.Fa ptr
88is made, and no references to the passed pointer are kept.
89Please note that the first assertion statement of
90.Fa assert
91has an
92.Fa idx
93of
94.Em 0 .
95The authenticator data passed to
96.Fn fido_assert_set_authdata
97must be a CBOR-encoded byte string, as obtained from
98.Fn fido_assert_authdata_ptr .
99Alternatively, a raw binary blob may be passed to
100.Fn fido_assert_set_authdata_raw .
101.Pp
102The
103.Fn fido_assert_set_clientdata_hash
104and
105.Fn fido_assert_set_hmac_salt
106functions set the client data hash and hmac-salt parts of
107.Fa assert
108to
109.Fa ptr ,
110where
111.Fa ptr
112points to
113.Fa len
114bytes.
115A copy of
116.Fa ptr
117is made, and no references to the passed pointer are kept.
118.Pp
119The
120.Fn fido_assert_set_rp
121function sets the relying party
122.Fa id
123of
124.Fa assert ,
125where
126.Fa id
127is a NUL-terminated UTF-8 string.
128The content of
129.Fa id
130is copied, and no references to the passed pointer are kept.
131.Pp
132The
133.Fn fido_assert_set_extensions
134function sets the extensions of
135.Fa assert
136to the bitmask
137.Fa flags .
138At the moment, only the
139.Dv FIDO_EXT_HMAC_SECRET
140extension is supported.
141If
142.Fa flags
143is zero, the extensions of
144.Fa assert
145are cleared.
146.Pp
147The
148.Fn fido_assert_set_up
149and
150.Fn fido_assert_set_uv
151functions set the
152.Fa up
153(user presence) and
154.Fa uv
155(user verification)
156attributes of
157.Fa assert .
158Both are
159.Dv FIDO_OPT_OMIT
160by default, allowing the authenticator to use its default settings.
161.Pp
162Use of the
163.Nm
164set of functions may happen in two distinct situations:
165when asking a FIDO device to produce a series of assertion
166statements, prior to
167.Xr fido_dev_get_assert 3
168(i.e, in the context of a FIDO client), or when verifying assertion
169statements using
170.Xr fido_assert_verify 3
171(i.e, in the context of a FIDO server).
172.Pp
173For a complete description of the generation of a FIDO 2 assertion
174and its verification, please refer to the FIDO 2 specification.
175An example of how to use the
176.Nm
177set of functions can be found in the
178.Pa examples/assert.c
179file shipped with
180.Em libfido2 .
181.Sh RETURN VALUES
182The
183.Nm
184functions return
185.Dv FIDO_OK
186on success.
187The error codes returned by the
188.Nm
189set 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
diff --git a/man/fido_assert_verify.3 b/man/fido_assert_verify.3
new file mode 100644
index 0000000..82e64e1
--- /dev/null
+++ b/man/fido_assert_verify.3
@@ -0,0 +1,79 @@
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 24 2018 $
6.Dt FIDO_ASSERT_VERIFY 3
7.Os
8.Sh NAME
9.Nm fido_assert_verify
10.Nd verifies the signature of a FIDO 2 assertion statement
11.Sh SYNOPSIS
12.In fido.h
13.Ft int
14.Fn fido_assert_verify "fido_assert_t *assert" "size_t idx" "int cose_alg" "const void *pk"
15.Sh DESCRIPTION
16The
17.Fn fido_assert_verify
18function verifies whether the signature contained in statement index
19.Fa idx
20of
21.Fa assert
22matches the parameters of the assertion.
23Before using
24.Fn fido_assert_verify
25in a sensitive context, the reader is strongly encouraged to make
26herself familiar with the FIDO 2 assertion statement process
27as defined in the Web Authentication (webauthn) standard.
28.Pp
29A brief description follows:
30.Pp
31The
32.Fn fido_assert_verify
33function verifies whether the client data hash, relying party ID,
34user presence and user verification attributes of
35.Fa assert
36have been attested by the holder of the private counterpart of
37the public key
38.Fa pk
39of COSE type
40.Fa cose_alg ,
41where
42.Fa cose_alg
43is
44.Dv COSE_ES256 ,
45.Dv COSE_RS256 ,
46or
47.Dv COSE_EDDSA ,
48and
49.Fa pk
50points to a
51.Vt es256_pk_t ,
52.Vt rs256_pk_t ,
53or
54.Vt eddsa_pk_t
55type accordingly.
56.Pp
57Please note that the first statement in
58.Fa assert
59has an
60.Fa idx
61of 0.
62.Sh RETURN VALUES
63The error codes returned by
64.Fn fido_assert_verify
65are defined in
66.In fido/err.h .
67If
68statement
69.Fa idx
70of
71.Fa assert
72passes verification with
73.Fa pk ,
74then
75.Dv FIDO_OK
76is returned.
77.Sh SEE ALSO
78.Xr fido_assert_new 3 ,
79.Xr fido_assert_set_authdata 3
diff --git a/man/fido_bio_dev_get_info.3 b/man/fido_bio_dev_get_info.3
new file mode 100644
index 0000000..bde1396
--- /dev/null
+++ b/man/fido_bio_dev_get_info.3
@@ -0,0 +1,120 @@
1.\" Copyright (c) 2019 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: September 13 2019 $
6.Dt FIDO_BIO_DEV_GET_INFO 3
7.Os
8.Sh NAME
9.Nm fido_bio_dev_get_info ,
10.Nm fido_bio_dev_enroll_begin ,
11.Nm fido_bio_dev_enroll_continue ,
12.Nm fido_bio_dev_enroll_cancel ,
13.Nm fido_bio_dev_enroll_remove ,
14.Nm fido_bio_dev_get_template_array ,
15.Nm fido_bio_dev_set_template_name
16.Nd FIDO 2 biometric authenticator API
17.Sh SYNOPSIS
18.In fido.h
19.In fido/bio.h
20.Ft int
21.Fn fido_bio_dev_get_info "fido_dev_t *dev" "fido_bio_info_t *info"
22.Ft int
23.Fn fido_bio_dev_enroll_begin "fido_dev_t *dev" "fido_bio_template_t *template" "fido_bio_enroll_t *enroll" "uint32_t timeout_ms" "const char *pin"
24.Ft int
25.Fn fido_bio_dev_enroll_continue "fido_dev_t *dev" "const fido_bio_template_t *template" "fido_bio_enroll_t *enroll" "uint32_t timeout_ms"
26.Ft int
27.Fn fido_bio_dev_enroll_cancel "fido_dev_t *dev"
28.Ft int
29.Fn fido_bio_dev_enroll_remove "fido_dev_t *dev" "const fido_bio_template_t *template" "const char *pin"
30.Ft int
31.Fn fido_bio_dev_get_template_array "fido_dev_t *dev" "fido_bio_template_array_t *template_array" "const char *pin"
32.Ft int
33.Fn fido_bio_dev_set_template_name "fido_dev_t *dev" "const fido_bio_template_t *template" "const char *pin"
34.Sh DESCRIPTION
35The functions described in this page allow biometric
36templates on a FIDO2 authenticator to be listed, created,
37removed, and customised.
38For a description of the types involved, please refer to
39.Xr fido_bio_info_new 3 ,
40.Xr fido_bio_enroll_new 3 ,
41and
42.Xr fido_bio_template 3 .
43.Pp
44The
45.Fn fido_bio_dev_get_info
46function populates
47.Fa info
48with sensor information from
49.Fa dev .
50.Pp
51The
52.Fn fido_bio_dev_enroll_begin
53function initiates a biometric enrollment on
54.Fa dev ,
55instructing the authenticator to wait
56.Fa timeout_ms
57milliseconds.
58On success,
59.Fa template
60and
61.Fa enroll
62will be populated with the newly created template's
63information and enrollment status, respectively.
64.Pp
65The
66.Fn fido_bio_dev_enroll_continue
67function continues an ongoing enrollment on
68.Fa dev ,
69instructing the authenticator to wait
70.Fa timeout_ms
71milliseconds.
72On success,
73.Fa enroll
74will be updated to reflect the status of the biometric
75enrollment.
76.Pp
77The
78.Fn fido_bio_dev_enroll_cancel
79function cancels an ongoing enrollment on
80.Fa dev .
81.Pp
82The
83.Fn fido_bio_dev_enroll_remove
84function removes
85.Fa template
86from
87.Fa dev .
88.Pp
89The
90.Fn fido_bio_dev_get_template_array
91function populates
92.Fa template_array
93with the templates currently enrolled on
94.Fa dev .
95.Pp
96The
97.Fn fido_bio_dev_set_template_name
98function sets the friendly name of
99.Fa template
100on
101.Fa dev .
102.Pp
103The error codes returned by
104.Fn fido_bio_dev_get_info ,
105.Fn fido_bio_dev_enroll_begin ,
106.Fn fido_bio_dev_enroll_continue ,
107.Fn fido_bio_dev_enroll_cancel ,
108.Fn fido_bio_dev_enroll_remove ,
109.Fn fido_bio_dev_get_template_array ,
110and
111.Fn fido_bio_dev_set_template_name
112are defined in
113.In fido/err.h .
114On success,
115.Dv FIDO_OK
116is returned.
117.Sh SEE ALSO
118.Xr fido_bio_enroll_new 3 ,
119.Xr fido_bio_info_new 3 ,
120.Xr fido_bio_template 3
diff --git a/man/fido_bio_enroll_new.3 b/man/fido_bio_enroll_new.3
new file mode 100644
index 0000000..3db3e7a
--- /dev/null
+++ b/man/fido_bio_enroll_new.3
@@ -0,0 +1,95 @@
1.\" Copyright (c) 2019 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: September 13 2019 $
6.Dt FIDO_BIO_ENROLL_NEW 3
7.Os
8.Sh NAME
9.Nm fido_bio_enroll_new ,
10.Nm fido_bio_enroll_free ,
11.Nm fido_bio_enroll_last_status ,
12.Nm fido_bio_enroll_remaining_samples
13.Nd FIDO 2 biometric enrollment API
14.Sh SYNOPSIS
15.In fido.h
16.In fido/bio.h
17.Bd -literal
18#define FIDO_BIO_ENROLL_FP_GOOD 0x00
19#define FIDO_BIO_ENROLL_FP_TOO_HIGH 0x01
20#define FIDO_BIO_ENROLL_FP_TOO_LOW 0x02
21#define FIDO_BIO_ENROLL_FP_TOO_LEFT 0x03
22#define FIDO_BIO_ENROLL_FP_TOO_RIGHT 0x04
23#define FIDO_BIO_ENROLL_FP_TOO_FAST 0x05
24#define FIDO_BIO_ENROLL_FP_TOO_SLOW 0x06
25#define FIDO_BIO_ENROLL_FP_POOR_QUALITY 0x07
26#define FIDO_BIO_ENROLL_FP_TOO_SKEWED 0x08
27#define FIDO_BIO_ENROLL_FP_TOO_SHORT 0x09
28#define FIDO_BIO_ENROLL_FP_MERGE_FAILURE 0x0a
29#define FIDO_BIO_ENROLL_FP_EXISTS 0x0b
30#define FIDO_BIO_ENROLL_FP_DATABASE_FULL 0x0c
31#define FIDO_BIO_ENROLL_NO_USER_ACTIVITY 0x0d
32#define FIDO_BIO_ENROLL_NO_USER_PRESENCE_TRANSITION 0x0e
33.Ed
34.Ft fido_bio_enroll_t *
35.Fn fido_bio_enroll_new "void"
36.Ft void
37.Fn fido_bio_enroll_free "fido_bio_enroll_t **enroll_p"
38.Ft uint8_t
39.Fn fido_bio_enroll_last_status "const fido_bio_enroll_t *enroll"
40.Ft uint8_t
41.Fn fido_bio_enroll_remaining_samples "const fido_bio_enroll_t *enroll"
42.Sh DESCRIPTION
43Ongoing FIDO 2 biometric enrollments are abstracted in
44.Em libfido2
45by the
46.Vt fido_bio_enroll_t
47type.
48.Pp
49The functions described in this page allow a
50.Vt fido_bio_enroll_t
51type to be allocated, deallocated, and inspected.
52For device operations on
53.Vt fido_bio_enroll_t ,
54please refer to
55.Xr fido_bio_dev_get_info 3 .
56.Pp
57The
58.Fn fido_bio_enroll_new
59function returns a pointer to a newly allocated, empty
60.Vt fido_bio_enroll_t
61type.
62If memory cannot be allocated, NULL is returned.
63.Pp
64The
65.Fn fido_bio_enroll_free
66function releases the memory backing
67.Fa *enroll_p ,
68where
69.Fa *enroll_p
70must have been previously allocated by
71.Fn fido_bio_enroll_new .
72On return,
73.Fa *enroll_p
74is set to NULL.
75Either
76.Fa enroll_p
77or
78.Fa *enroll_p
79may be NULL, in which case
80.Fn fido_bio_enroll_free
81is a NOP.
82.Pp
83The
84.Fn fido_bio_enroll_last_status
85function returns the enrollment status of
86.Fa enroll .
87.Pp
88The
89.Fn fido_bio_enroll_remaining_samples
90function returns the number of samples left for
91.Fa enroll
92to complete.
93.Sh SEE ALSO
94.Xr fido_bio_dev_get_info 3 ,
95.Xr fido_bio_template 3
diff --git a/man/fido_bio_info_new.3 b/man/fido_bio_info_new.3
new file mode 100644
index 0000000..c827333
--- /dev/null
+++ b/man/fido_bio_info_new.3
@@ -0,0 +1,81 @@
1.\" Copyright (c) 2019 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: September 13 2019 $
6.Dt FIDO_BIO_INFO_NEW 3
7.Os
8.Sh NAME
9.Nm fido_bio_info_new ,
10.Nm fido_bio_info_free ,
11.Nm fido_bio_info_type ,
12.Nm fido_bio_info_max_samples
13.Nd FIDO 2 biometric sensor information API
14.Sh SYNOPSIS
15.In fido.h
16.In fido/bio.h
17.Ft fido_bio_info_t *
18.Fn fido_bio_info_new "void"
19.Ft void
20.Fn fido_bio_info_free "fido_bio_info_t **info_p"
21.Ft uint8_t
22.Fn fido_bio_info_type "const fido_bio_info_t *info"
23.Ft uint8_t
24.Fn fido_bio_info_max_samples "const fido_bio_info_t *info"
25.Sh DESCRIPTION
26Biometric sensor metadata is abstracted in
27.Em libfido2
28by the
29.Vt fido_bio_info_t
30type.
31.Pp
32The functions described in this page allow a
33.Vt fido_bio_info_t
34type to be allocated, deallocated, and inspected.
35For device operations on
36.Vt fido_bio_info_t ,
37please refer to
38.Xr fido_bio_dev_get_info 3 .
39.Pp
40The
41.Fn fido_bio_info_new
42function returns a pointer to a newly allocated, empty
43.Vt fido_bio_info_t
44type.
45If memory cannot be allocated, NULL is returned.
46.Pp
47The
48.Fn fido_bio_info_free
49function releases the memory backing
50.Fa *info_p ,
51where
52.Fa *info_p
53must have been previously allocated by
54.Fn fido_bio_info_new .
55On return,
56.Fa *info_p
57is set to NULL.
58Either
59.Fa info_p
60or
61.Fa *info_p
62may be NULL, in which case
63.Fn fido_bio_info_free
64is a NOP.
65.Pp
66The
67.Fn fido_bio_info_type
68function returns the fingerprint sensor type, which is
69.Dv 1
70for touch sensors, and
71.Dv 2
72for swipe sensors.
73.Pp
74The
75.Fn fido_bio_info_max_samples
76function returns the maximum number of successful samples
77required for enrollment.
78.Sh SEE ALSO
79.Xr fido_bio_dev_get_info 3 ,
80.Xr fido_bio_enroll_new 3 ,
81.Xr fido_bio_template 3
diff --git a/man/fido_bio_template.3 b/man/fido_bio_template.3
new file mode 100644
index 0000000..6140926
--- /dev/null
+++ b/man/fido_bio_template.3
@@ -0,0 +1,169 @@
1.\" Copyright (c) 2019 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: September 13 2019 $
6.Dt FIDO_BIO_TEMPLATE 3
7.Os
8.Sh NAME
9.Nm fido_bio_template ,
10.Nm fido_bio_template_array_count ,
11.Nm fido_bio_template_array_free ,
12.Nm fido_bio_template_array_new ,
13.Nm fido_bio_template_free ,
14.Nm fido_bio_template_id_len ,
15.Nm fido_bio_template_id_ptr ,
16.Nm fido_bio_template_name ,
17.Nm fido_bio_template_new ,
18.Nm fido_bio_template_set_id ,
19.Nm fido_bio_template_set_name
20.Nd FIDO 2 biometric template API
21.Sh SYNOPSIS
22.In fido.h
23.In fido/bio.h
24.Ft fido_bio_template_t *
25.Fn fido_bio_template_new "void"
26.Ft void
27.Fn fido_bio_template_free "fido_bio_template_t **template_p"
28.Ft const char *
29.Fn fido_bio_template_name "const fido_bio_template_t *template"
30.Ft const unsigned char *
31.Fn fido_bio_template_id_ptr "const fido_bio_template_t *template"
32.Ft size_t
33.Fn fido_bio_template_id_len "const fido_bio_template_t *template"
34.Ft int
35.Fn fido_bio_template_set_id "fido_bio_template_t *template" "const unsigned char *ptr" "size_t len"
36.Ft int
37.Fn fido_bio_template_set_name "fido_bio_template_t *template" "const char *name"
38.Ft fido_bio_template_array_t *
39.Fn fido_bio_template_array_new "void"
40.Ft void
41.Fn fido_bio_template_array_free "fido_bio_template_array_t **template_array_p"
42.Ft size_t
43.Fn fido_bio_template_array_count "const fido_bio_template_array_t *template_array"
44.Ft const fido_bio_template_t *
45.Fn fido_bio_template "const fido_bio_template_array_t *template_array" "size_t idx"
46.Sh DESCRIPTION
47Existing FIDO 2 biometric enrollments are abstracted in
48.Em libfido2
49by the
50.Vt fido_bio_template_t
51and
52.Vt fido_bio_template_array_t
53types.
54.Pp
55The functions described in this page allow a
56.Vt fido_bio_template_t
57type to be allocated, deallocated, changed, and inspected,
58and a
59.Vt fido_bio_template_array_t
60type to be allocated, deallocated, and inspected.
61For device operations on
62.Vt fido_bio_template_t
63and
64.Vt fido_bio_template_array_t ,
65please refer to
66.Xr fido_bio_dev_get_info 3 .
67.Pp
68The
69.Fn fido_bio_template_new
70function returns a pointer to a newly allocated, empty
71.Vt fido_bio_template_t
72type.
73If memory cannot be allocated, NULL is returned.
74.Pp
75The
76.Fn fido_bio_template_free
77function releases the memory backing
78.Fa *template_p ,
79where
80.Fa *template_p
81must have been previously allocated by
82.Fn fido_bio_template_new .
83On return,
84.Fa *template_p
85is set to NULL.
86Either
87.Fa template_p
88or
89.Fa *template_p
90may be NULL, in which case
91.Fn fido_bio_template_free
92is a NOP.
93.Pp
94The
95.Fn fido_bio_template_name
96function returns a pointer to a NUL-terminated string containing
97the friendly name of
98.Fa template ,
99or NULL if
100.Fa template
101does not have a friendly name set.
102.Pp
103The
104.Fn fido_bio_template_id_ptr
105function returns a pointer to the template id of
106.Fa template ,
107or NULL if
108.Fa template
109does not have an id.
110The corresponding length can be obtained by
111.Fn fido_bio_template_id_len .
112.Pp
113The
114.Fn fido_bio_template_set_name
115function sets the friendly name of
116.Fa template
117to
118.Fa name .
119If
120.Fa name
121is NULL, the friendly name of
122.Fa template
123is unset.
124.Pp
125The
126.Fn fido_bio_template_array_new
127function returns a pointer to a newly allocated, empty
128.Vt fido_bio_template_array_t
129type.
130If memory cannot be allocated, NULL is returned.
131.Pp
132The
133.Fn fido_bio_template_array_free
134function releases the memory backing
135.Fa *template_array_p ,
136where
137.Fa *template_array_p
138must have been previously allocated by
139.Fn fido_bio_template_array_new .
140On return,
141.Fa *template_array_p
142is set to NULL.
143Either
144.Fa template_array_p
145or
146.Fa *template_array_p
147may be NULL, in which case
148.Fn fido_bio_template_array_free
149is a NOP.
150.Pp
151The
152.Fn fido_bio_template_array_count
153function returns the number of templates in
154.Fa template_array .
155.Pp
156The
157.Fn fido_bio_template
158function returns a pointer to the template at index
159.Fa idx
160in
161.Fa template_array .
162Please note that the first template in
163.Fa template_array
164has an
165.Fa idx
166(index) value of 0.
167.Sh SEE ALSO
168.Xr fido_bio_dev_get_info 3 ,
169.Xr fido_bio_enroll_new 3
diff --git a/man/fido_cbor_info_new.3 b/man/fido_cbor_info_new.3
new file mode 100644
index 0000000..d1e4c41
--- /dev/null
+++ b/man/fido_cbor_info_new.3
@@ -0,0 +1,153 @@
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 24 2018 $
6.Dt FIDO_CBOR_INFO_NEW 3
7.Os
8.Sh NAME
9.Nm fido_cbor_info_new ,
10.Nm fido_cbor_info_free ,
11.Nm fido_dev_get_cbor_info ,
12.Nm fido_cbor_info_aaguid_ptr ,
13.Nm fido_cbor_info_extensions_ptr ,
14.Nm fido_cbor_info_protocols_ptr ,
15.Nm fido_cbor_info_versions_ptr ,
16.Nm fido_cbor_info_options_name_ptr ,
17.Nm fido_cbor_info_options_value_ptr ,
18.Nm fido_cbor_info_aaguid_len ,
19.Nm fido_cbor_info_extensions_len ,
20.Nm fido_cbor_info_protocols_len ,
21.Nm fido_cbor_info_versions_len ,
22.Nm fido_cbor_info_options_len ,
23.Nm fido_cbor_info_maxmsgsiz
24.Nd FIDO 2 CBOR Info API
25.Sh SYNOPSIS
26.In fido.h
27.Ft fido_cbor_info_t *
28.Fn fido_cbor_info_new "void"
29.Ft void
30.Fn fido_cbor_info_free "fido_cbor_info_t **ci_p"
31.Ft int
32.Fn fido_dev_get_cbor_info "fido_dev_t *dev" "fido_cbor_info_t *ci"
33.Ft const unsigned char *
34.Fn fido_cbor_info_aaguid_ptr "const fido_cbor_info_t *ci"
35.Ft char **
36.Fn fido_cbor_info_extensions_ptr "const fido_cbor_info_t *ci"
37.Ft const uint8_t *
38.Fn fido_cbor_info_protocols_ptr "const fido_cbor_info_t *ci"
39.Ft char **
40.Fn fido_cbor_info_versions_ptr "const fido_cbor_info_t *ci"
41.Ft char **
42.Fn fido_cbor_info_options_name_ptr "const fido_cbor_info_t *ci"
43.Ft const bool *
44.Fn fido_cbor_info_options_value_ptr "const fido_cbor_info_t *ci"
45.Ft size_t
46.Fn fido_cbor_info_aaguid_len "const fido_cbor_info_t *ci"
47.Ft size_t
48.Fn fido_cbor_info_extensions_len "const fido_cbor_info_t *ci"
49.Ft size_t
50.Fn fido_cbor_info_protocols_len "const fido_cbor_info_t *ci"
51.Ft size_t
52.Fn fido_cbor_info_versions_len "const fido_cbor_info_t *ci"
53.Ft size_t
54.Fn fido_cbor_info_options_len "const fido_cbor_info_t *ci"
55.Ft uint64_t
56.Fn fido_cbor_info_maxmsgsiz "const fido_cbor_info_t *ci"
57.Sh DESCRIPTION
58The
59.Fn fido_cbor_info_new
60function returns a pointer to a newly allocated, empty
61.Vt fido_cbor_info_t
62type.
63If memory cannot be allocated, NULL is returned.
64.Pp
65The
66.Fn fido_cbor_info_free
67function releases the memory backing
68.Fa *ci_p ,
69where
70.Fa *ci_p
71must have been previously allocated by
72.Fn fido_cbor_info_new .
73On return,
74.Fa *ci_p
75is set to NULL.
76Either
77.Fa ci_p
78or
79.Fa *ci_p
80may be NULL, in which case
81.Fn fido_cbor_info_free
82is a NOP.
83.Pp
84The
85.Fn fido_dev_get_cbor_info
86function transmits a
87.Dv CTAP_CBOR_GETINFO
88command to
89.Fa dev
90and fills
91.Fa ci
92with attributes retrieved from the command's response.
93The
94.Fn fido_dev_get_cbor_info
95function may block.
96.Pp
97The
98.Fn fido_cbor_info_aaguid_ptr ,
99.Fn fido_cbor_info_extensions_ptr ,
100.Fn fido_cbor_info_protocols_ptr ,
101and
102.Fn fido_cbor_info_versions_ptr
103functions return pointers to the AAGUID, supported extensions,
104PIN protocol and CTAP version strings of
105.Fa ci .
106The corresponding length of a given attribute can be
107obtained by
108.Fn fido_cbor_info_aaguid_len ,
109.Fn fido_cbor_info_extensions_len ,
110.Fn fido_cbor_info_protocols_len ,
111or
112.Fn fido_cbor_info_versions_len .
113.Pp
114The
115.Fn fido_cbor_info_options_name_ptr
116and
117.Fn fido_cbor_info_options_value_ptr
118functions return pointers to the array of option names and their
119respective values
120in
121.Fa ci .
122The length of the options array is returned by
123.Fn fido_cbor_info_options_len .
124.Pp
125The
126.Fn fido_cbor_info_maxmsgsiz
127function returns the maximum message size of
128.Fa ci .
129.Pp
130A complete example of how to use these functions can be found in the
131.Pa example/info.c
132file shipped with
133.Em libfido2 .
134.Sh RETURN VALUES
135The
136.Fn fido_cbor_info_aaguid_ptr ,
137.Fn fido_cbor_info_extensions_ptr ,
138.Fn fido_cbor_info_protocols_ptr ,
139.Fn fido_cbor_info_versions_ptr ,
140.Fn fido_cbor_info_options_name_ptr ,
141and
142.Fn fido_cbor_info_options_value_ptr
143functions return NULL if the respective field in
144.Fa ci
145is absent.
146If not NULL, returned pointers are guaranteed to exist until any
147API function that takes
148.Fa ci
149without the
150.Em const
151qualifier is invoked.
152.Sh SEE ALSO
153.Xr fido_dev_open 3
diff --git a/man/fido_cred_exclude.3 b/man/fido_cred_exclude.3
new file mode 100644
index 0000000..700d6af
--- /dev/null
+++ b/man/fido_cred_exclude.3
@@ -0,0 +1,60 @@
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_EXCLUDE 3
7.Os
8.Sh NAME
9.Nm fido_cred_exclude
10.Nd appends a credential ID to a credential's list of excluded credentials
11.Sh SYNOPSIS
12.In fido.h
13.Ft int
14.Fn fido_cred_exclude "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
15.Sh DESCRIPTION
16The
17.Fn fido_cred_exclude
18function adds
19.Fa ptr
20to the list of credentials excluded by
21.Fa cred ,
22where
23.Fa ptr
24points to a credential ID of
25.Fa len
26bytes.
27A copy of
28.Fa ptr
29is made, and no references to the passed pointer are kept.
30If
31.Fn fido_cred_exclude
32fails, the existing list of excluded credentials is preserved.
33.Pp
34If
35.Nm
36returns success and
37.Fa cred
38is later passed to
39.Xr fido_dev_make_cred 3
40on a device that contains the credential
41denoted by
42.Fa ptr ,
43then
44.Xr fido_dev_make_cred 3
45will fail.
46.Pp
47For the format of a FIDO 2 credential ID, please refer to the
48Web Authentication (webauthn) standard.
49.Sh RETURN VALUES
50The error codes returned by
51.Fn fido_cred_exclude
52are defined in
53.In fido/err.h .
54On success,
55.Dv FIDO_OK
56is returned.
57.Sh SEE ALSO
58.Xr fido_cred_new 3 ,
59.Xr fido_cred_set_authdata 3 ,
60.Xr fido_dev_make_cred 3
diff --git a/man/fido_cred_new.3 b/man/fido_cred_new.3
new file mode 100644
index 0000000..47eeba8
--- /dev/null
+++ b/man/fido_cred_new.3
@@ -0,0 +1,157 @@
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_NEW 3
7.Os
8.Sh NAME
9.Nm fido_cred_new ,
10.Nm fido_cred_free ,
11.Nm fido_cred_fmt ,
12.Nm fido_cred_authdata_ptr ,
13.Nm fido_cred_clientdata_hash_ptr ,
14.Nm fido_cred_id_ptr ,
15.Nm fido_cred_pubkey_ptr ,
16.Nm fido_cred_sig_ptr ,
17.Nm fido_cred_x5c_ptr ,
18.Nm fido_cred_authdata_len ,
19.Nm fido_cred_clientdata_hash_len ,
20.Nm fido_cred_id_len ,
21.Nm fido_cred_pubkey_len ,
22.Nm fido_cred_sig_len ,
23.Nm fido_cred_x5c_len
24.Nd FIDO 2 credential API
25.Sh SYNOPSIS
26.In fido.h
27.Ft fido_cred_t *
28.Fn fido_cred_new "void"
29.Ft void
30.Fn fido_cred_free "fido_cred_t **cred_p"
31.Ft const char *
32.Fn fido_cred_fmt "const fido_cred_t *cred"
33.Ft const unsigned char *
34.Fn fido_cred_authdata_ptr "const fido_cred_t *cred"
35.Ft const unsigned char *
36.Fn fido_cred_clientdata_hash_ptr "const fido_cred_t *cred"
37.Ft const unsigned char *
38.Fn fido_cred_id_ptr "const fido_cred_t *cred"
39.Ft const unsigned char *
40.Fn fido_cred_pubkey_ptr "const fido_cred_t *cred"
41.Ft const unsigned char *
42.Fn fido_cred_sig_ptr "const fido_cred_t *cred"
43.Ft const unsigned char *
44.Fn fido_cred_x5c_ptr "const fido_cred_t *cred"
45.Ft size_t
46.Fn fido_cred_authdata_len "const fido_cred_t *cred"
47.Ft size_t
48.Fn fido_cred_clientdata_hash_len "const fido_cred_t *cred"
49.Ft size_t
50.Fn fido_cred_id_len "const fido_cred_t *cred"
51.Ft size_t
52.Fn fido_cred_pubkey_len "const fido_cred_t *cred"
53.Ft size_t
54.Fn fido_cred_sig_len "const fido_cred_t *cred"
55.Ft size_t
56.Fn fido_cred_x5c_len "const fido_cred_t *cred"
57.Sh DESCRIPTION
58FIDO 2 credentials are abstracted in
59.Em libfido2
60by the
61.Vt fido_cred_t
62type.
63The functions described in this page allow a
64.Vt fido_cred_t
65type to be allocated, deallocated, and inspected.
66For other operations on
67.Vt fido_cred_t ,
68please refer to
69.Xr fido_cred_set_authdata 3 ,
70.Xr fido_cred_exclude 3 ,
71.Xr fido_cred_verify 3 ,
72and
73.Xr fido_dev_make_cred 3 .
74.Pp
75The
76.Fn fido_cred_new
77function returns a pointer to a newly allocated, empty
78.Vt fido_cred_t
79type.
80If memory cannot be allocated, NULL is returned.
81.Pp
82The
83.Fn fido_cred_free
84function releases the memory backing
85.Fa *cred_p ,
86where
87.Fa *cred_p
88must have been previously allocated by
89.Fn fido_cred_new .
90On return,
91.Fa *cred_p
92is set to NULL.
93Either
94.Fa cred_p
95or
96.Fa *cred_p
97may be NULL, in which case
98.Fn fido_cred_free
99is a NOP.
100.Pp
101The
102.Fn fido_cred_fmt
103function returns a pointer to a NUL-terminated string containing
104the format of
105.Fa cred ,
106or NULL if
107.Fa cred
108does not have a format set.
109.Pp
110The
111.Fn fido_cred_authdata_ptr ,
112.Fn fido_cred_clientdata_hash_ptr ,
113.Fn fido_cred_id_ptr ,
114.Fn fido_cred_pubkey_ptr ,
115.Fn fido_cred_sig_ptr ,
116and
117.Fn fido_cred_x5c_ptr
118functions return pointers to the authenticator data, client data
119hash, ID, public key, signature and x509 certificate parts of
120.Fa cred ,
121or NULL if the respective entry is not set.
122.Pp
123The corresponding length can be obtained by
124.Fn fido_cred_authdata_len ,
125.Fn fido_cred_clientdata_hash_len ,
126.Fn fido_cred_id_len ,
127.Fn fido_cred_pubkey_len ,
128and
129.Fn fido_cred_sig_len .
130.Pp
131The authenticator data, x509 certificate, and signature parts of a
132credential are typically passed to a FIDO 2 server for verification.
133.Sh RETURN VALUES
134The authenticator data returned by
135.Fn fido_cred_authdata_ptr
136is a CBOR-encoded byte string, as obtained from the authenticator.
137.Pp
138If not NULL, pointers returned by
139.Fn fido_cred_fmt ,
140.Fn fido_cred_authdata_ptr ,
141.Fn fido_cred_clientdata_hash_ptr ,
142.Fn fido_cred_id_ptr ,
143.Fn fido_cred_pubkey_ptr ,
144.Fn fido_cred_sig_ptr ,
145and
146.Fn fido_cred_x5c_ptr
147are guaranteed to exist until any API function that takes
148.Fa cred
149without the
150.Em const
151qualifier is invoked.
152.Sh SEE ALSO
153.Xr fido_cred_exclude 3 ,
154.Xr fido_cred_set_authdata 3 ,
155.Xr fido_cred_verify 3 ,
156.Xr fido_credman_metadata_new 3 ,
157.Xr fido_dev_make_cred 3
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
25typedef 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
56The
57.Nm
58set of functions define the various parameters of a FIDO 2
59credential, allowing a
60.Fa fido_cred_t
61type to be prepared for a subsequent call to
62.Xr fido_dev_make_cred 3
63or
64.Xr fido_cred_verify 3 .
65For the complete specification of a FIDO 2 credential and the format
66of its constituent parts, please refer to the Web Authentication
67(webauthn) standard.
68.Pp
69The
70.Fn fido_cred_set_authdata ,
71.Fn fido_cred_set_x509 ,
72.Fn fido_cred_set_sig ,
73and
74.Fn fido_cred_set_clientdata_hash
75functions set the authenticator data, attestation certificate,
76signature and client data hash parts of
77.Fa cred
78to
79.Fa ptr ,
80where
81.Fa ptr
82points to
83.Fa len
84bytes.
85A copy of
86.Fa ptr
87is made, and no references to the passed pointer are kept.
88The authenticator data passed to
89.Fn fido_cred_set_authdata
90must be a CBOR-encoded byte string, as obtained from
91.Fn fido_cred_authdata_ptr .
92Alternatively, a raw binary blob may be passed to
93.Fn fido_cred_set_authdata_raw .
94.Pp
95The
96.Fn fido_cred_set_rp
97function sets the relying party
98.Fa id
99and
100.Fa name
101parameters of
102.Fa cred ,
103where
104.Fa id
105and
106.Fa name
107are NUL-terminated UTF-8 strings.
108The contents of
109.Fa id
110and
111.Fa name
112are copied, and no references to the passed pointers are kept.
113.Pp
114The
115.Fn fido_cred_set_user
116function sets the user attributes of
117.Fa cred ,
118where
119.Fa user_id
120points to
121.Fa user_id_len
122bytes and
123.Fa name ,
124.Fa display_name ,
125and
126.Fa icon
127are NUL-terminated UTF-8 strings.
128The contents of
129.Fa user_id ,
130.Fa name ,
131.Fa display_name ,
132and
133.Fa icon
134are copied, and no references to the passed pointers are kept.
135Previously set user attributes are flushed.
136The
137.Fa user_id ,
138.Fa name ,
139.Fa display_name ,
140and
141.Fa icon
142parameters may be NULL.
143.Pp
144The
145.Fn fido_cred_set_extensions
146function sets the extensions of
147.Fa cred
148to the bitmask
149.Fa flags .
150At the moment, only the
151.Dv FIDO_EXT_HMAC_SECRET
152extension is supported.
153If
154.Fa flags
155is zero, the extensions of
156.Fa cred
157are cleared.
158.Pp
159The
160.Fn fido_cred_set_rk
161and
162.Fn fido_cred_set_uv
163functions set the
164.Em rk
165(resident key)
166and
167.Em uv
168(user verification)
169attributes of
170.Fa cred .
171Both are
172.Dv FIDO_OPT_OMIT
173by default, allowing the authenticator to use its default settings.
174.Pp
175The
176.Fn fido_cred_set_fmt
177function sets the format of
178.Fa cred
179to
180.Fa fmt ,
181where
182.Fa fmt
183must be either
184.Vt "packed"
185(the format used in FIDO 2)
186or
187.Vt "fido-u2f"
188(the format used by U2F).
189A copy of
190.Fa fmt
191is made, and no references to the passed pointer are kept.
192Note that not all authenticators support FIDO2 and therefore may not
193be able to generate
194.Vt "packed" .
195.Pp
196The
197.Fn fido_cred_set_type
198function sets the type of
199.Fa cred to
200.Fa cose_alg ,
201where
202.Fa cose_alg
203is
204.Dv COSE_ES256 ,
205.Dv COSE_RS256 ,
206or
207.Dv COSE_EDDSA .
208The type of a credential may only be set once.
209Note that not all authenticators support COSE_RS256 or COSE_EDDSA.
210.Pp
211Use of the
212.Nm
213set of functions may happen in two distinct situations:
214when 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
217a generated credential using
218.Xr fido_cred_verify 3
219(i.e, in the context of a FIDO server).
220.Pp
221For a complete description of the generation of a FIDO 2 credential
222and its verification, please refer to the FIDO 2 specification.
223A concrete utilisation example of the
224.Nm
225set of functions can be found in the
226.Pa cred.c
227example shipped with
228.Em libfido2 .
229.Sh RETURN VALUES
230The error codes returned by the
231.Nm
232set of functions are defined in
233.In fido/err.h .
234On success,
235.Dv FIDO_OK
236is returned.
237.Sh SEE ALSO
238.Xr fido_cred_exclude 3 ,
239.Xr fido_cred_verify 3 ,
240.Xr fido_dev_make_cred 3
diff --git a/man/fido_cred_verify.3 b/man/fido_cred_verify.3
new file mode 100644
index 0000000..c75b9a1
--- /dev/null
+++ b/man/fido_cred_verify.3
@@ -0,0 +1,64 @@
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_VERIFY 3
7.Os
8.Sh NAME
9.Nm fido_cred_verify
10.Nd verifies the signature of a FIDO 2 credential
11.Sh SYNOPSIS
12.In fido.h
13.Ft int
14.Fn fido_cred_verify "const fido_cred_t *cred"
15.Sh DESCRIPTION
16The
17.Fn fido_cred_verify
18function verifies whether the signature contained in
19.Fa cred
20matches the attributes of the credential.
21Before using
22.Fn fido_cred_verify
23in a sensitive context, the reader is strongly encouraged to make
24herself familiar with the FIDO 2 credential attestation process
25as defined in the Web Authentication (webauthn) standard.
26.Pp
27A brief description follows:
28.Pp
29The
30.Fn fido_cred_verify
31function verifies whether the client data hash, relying party ID,
32credential ID, type, and resident key and user verification
33attributes of
34.Fa cred
35have been attested by the holder of the private counterpart of
36the public key contained in the credential's x509 certificate.
37.Pp
38Please note that the x509 certificate itself is not verified.
39.Pp
40The attestation statement formats supported by
41.Fn fido_cred_verify
42are
43.Em packed
44and
45.Em fido-u2f .
46The attestation type implemented by
47.Fn fido_cred_verify
48is
49.Em Basic Attestation .
50The attestation key pair is assumed to be of the type ES256.
51Other attestation formats and types are not supported.
52.Sh RETURN VALUES
53The error codes returned by
54.Fn fido_cred_verify
55are defined in
56.In fido/err.h .
57If
58.Fa cred
59passes verification, then
60.Dv FIDO_OK
61is returned.
62.Sh SEE ALSO
63.Xr fido_cred_new 3 ,
64.Xr fido_cred_set_authdata 3
diff --git a/man/fido_credman_metadata_new.3 b/man/fido_credman_metadata_new.3
new file mode 100644
index 0000000..16f0192
--- /dev/null
+++ b/man/fido_credman_metadata_new.3
@@ -0,0 +1,299 @@
1.\" Copyright (c) 2019 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: June 28 2019 $
6.Dt FIDO_CREDMAN_METADATA_NEW 3
7.Os
8.Sh NAME
9.Nm fido_credman_metadata_new ,
10.Nm fido_credman_rk_new ,
11.Nm fido_credman_rp_new ,
12.Nm fido_credman_metadata_free ,
13.Nm fido_credman_rk_free ,
14.Nm fido_credman_rp_free ,
15.Nm fido_credman_rk_existing ,
16.Nm fido_credman_rk_remaining ,
17.Nm fido_credman_rk ,
18.Nm fido_credman_rk_count ,
19.Nm fido_credman_rp_id ,
20.Nm fido_credman_rp_name ,
21.Nm fido_credman_rp_count ,
22.Nm fido_credman_rp_id_hash_ptr ,
23.Nm fido_credman_rp_id_hash_len ,
24.Nm fido_credman_get_dev_metadata ,
25.Nm fido_credman_get_dev_rk ,
26.Nm fido_credman_del_dev_rk ,
27.Nm fido_credman_get_dev_rp
28.Nd FIDO 2 credential management API
29.Sh SYNOPSIS
30.In fido.h
31.In fido/credman.h
32.Ft fido_credman_metadata_t *
33.Fn fido_credman_metadata_new "void"
34.Ft fido_credman_rk_t *
35.Fn fido_credman_rk_new "void"
36.Ft fido_credman_rp_t *
37.Fn fido_credman_rp_new "void"
38.Ft void
39.Fn fido_credman_metadata_free "fido_credman_metadata_t **metadata_p"
40.Ft void
41.Fn fido_credman_rk_free "fido_credman_rk_t **rk_p"
42.Ft void
43.Fn fido_credman_rp_free "fido_credman_rp_t **rp_p"
44.Ft uint64_t
45.Fn fido_credman_rk_existing "const fido_credman_metadata_t *metadata"
46.Ft uint64_t
47.Fn fido_credman_rk_remaining "const fido_credman_metadata_t *metadata"
48.Ft const fido_cred_t *
49.Fn fido_credman_rk "const fido_credman_rk_t *rk" "size_t idx"
50.Ft size_t
51.Fn fido_credman_rk_count "const fido_credman_rk_t *rk"
52.Ft const char *
53.Fn fido_credman_rp_id "const fido_credman_rp_t *rp" "size_t idx"
54.Ft const char *
55.Fn fido_credman_rp_name "const fido_credman_rp_t *rp" "size_t idx"
56.Ft size_t
57.Fn fido_credman_rp_count "const fido_credman_rp_t *rp"
58.Ft const unsigned char *
59.Fn fido_credman_rp_id_hash_ptr "const fido_credman_rp_t *rp" "size_t idx"
60.Ft size_t
61.Fn fido_credman_rp_id_hash_len "const fido_credman_rp_t *" "size_t idx"
62.Ft int
63.Fn fido_credman_get_dev_metadata "fido_dev_t *dev" "fido_credman_metadata_t *metadata" "const char *pin"
64.Ft int
65.Fn fido_credman_get_dev_rk "fido_dev_t *dev" "const char *rp_id" "fido_credman_rk_t *rk" "const char *pin"
66.Ft int
67.Fn fido_credman_del_dev_rk "fido_dev_t *dev" const unsigned char *cred_id" "size_t cred_id_len" "const char *pin"
68.Ft int
69.Fn fido_credman_get_dev_rp "fido_dev_t *dev" "fido_credman_rp_t *rp" "const char *pin"
70.Sh DESCRIPTION
71The credential management API of
72.Em libfido2
73allows resident credentials on a FIDO2 authenticator to be listed,
74inspected, and removed.
75Please note that not all authenticators support credential management.
76To obtain information on what an authenticator supports, please
77refer to
78.Xr fido_cbor_info_new 3 .
79.Pp
80The
81.Vt fido_credman_metadata_t
82type abstracts credential management metadata.
83.Pp
84The
85.Fn fido_credman_metadata_new
86function returns a pointer to a newly allocated, empty
87.Vt fido_credman_metadata_t
88type.
89If memory cannot be allocated, NULL is returned.
90.Pp
91The
92.Fn fido_credman_metadata_free
93function releases the memory backing
94.Fa *metadata_p ,
95where
96.Fa *metadata_p
97must have been previously allocated by
98.Fn fido_credman_metadata_new .
99On return,
100.Fa *metadata_p
101is set to NULL.
102Either
103.Fa metadata_p
104or
105.Fa *metadata_p
106may be NULL, in which case
107.Fn fido_credman_metadata_free
108is a NOP.
109.Pp
110The
111.Fn fido_credman_get_dev_metadata
112function populates
113.Fa metadata
114with information retrieved from
115.Fa dev .
116A valid
117.Fa pin
118must be provided.
119.Pp
120The
121.Fn fido_credman_rk_existing
122function inspects
123.Fa metadata
124and returns the number of resident credentials on the
125authenticator.
126The
127.Fn fido_credman_rk_remaining
128function inspects
129.Fa metadata
130and returns the estimated number of resident credentials that can
131be created on the authenticator.
132.Pp
133The
134.Vt fido_credman_rk_t
135type abstracts the set of resident credentials belonging to a
136given relying party.
137.Pp
138The
139.Fn fido_credman_rk_new
140function returns a pointer to a newly allocated, empty
141.Vt fido_credman_rk_t
142type.
143If memory cannot be allocated, NULL is returned.
144.Pp
145The
146.Fn fido_credman_rk_free
147function releases the memory backing
148.Fa *rk_p ,
149where
150.Fa *rk_p
151must have been previously allocated by
152.Fn fido_credman_rk_new .
153On return,
154.Fa *rk_p
155is set to NULL.
156Either
157.Fa rk_p
158or
159.Fa *rk_p
160may be NULL, in which case
161.Fn fido_credman_rk_free
162is a NOP.
163.Pp
164The
165.Fn fido_credman_get_dev_rk
166function populates
167.Fa rk
168with the set of resident credentials belonging to
169.Fa rp_id
170in
171.Fa dev .
172A valid
173.Fa pin
174must be provided.
175.Pp
176The
177.Fn fido_credman_rk_count
178function returns the number of resident credentials in
179.Fa rk .
180The
181.Fn fido_credman_rk
182function returns a pointer to the credential at index
183.Fa idx
184in
185.Fa rk .
186Please note that the first credential in
187.Fa rk
188has an
189.Fa idx
190(index) value of 0.
191.Pp
192The
193.Fn fido_credman_del_dev_rk
194function deletes the resident credential identified by
195.Fa cred_id
196from
197.Fa dev ,
198where
199.Fa cred_id
200points to
201.Fa cred_id_len
202bytes.
203A valid
204.Fa pin
205must be provided.
206.Pp
207The
208.Vt fido_credman_rp_t
209type abstracts information about a relying party.
210.Pp
211The
212.Fn fido_credman_rp_new
213function returns a pointer to a newly allocated, empty
214.Vt fido_credman_rp_t
215type.
216If memory cannot be allocated, NULL is returned.
217.Pp
218The
219.Fn fido_credman_rp_free
220function releases the memory backing
221.Fa *rp_p ,
222where
223.Fa *rp_p
224must have been previously allocated by
225.Fn fido_credman_rp_new .
226On return,
227.Fa *rp_p
228is set to NULL.
229Either
230.Fa rp_p
231or
232.Fa *rp_p
233may be NULL, in which case
234.Fn fido_credman_rp_free
235is a NOP.
236.Pp
237The
238.Fn fido_credman_get_dev_rp
239function populates
240.Fa rp
241with information about relying parties with resident credentials
242in
243.Fa dev .
244A valid
245.Fa pin
246must be provided.
247.Pp
248The
249.Fn fido_credman_rp_count
250function returns the number of relying parties in
251.Fa rp .
252.Pp
253The
254.Fn fido_credman_rp_id
255and
256.Fn fido_credman_rp_name
257functions return pointers to the id and name of relying party
258.Fa idx
259in
260.Fa rp .
261If not NULL, the values returned by these functions point to
262NUL-terminated UTF-8 strings.
263Please note that the first relying party in
264.Fa rp
265has an
266.Fa idx
267(index) value of 0.
268.Pp
269The
270.Fn fido_credman_rp_id_hash_ptr
271function returns a pointer to the hashed id of relying party
272.Fa idx
273in
274.Fa rp .
275The corresponding length can be obtained by
276.Fn fido_credman_rp_id_hash_len .
277Please note that the first relying party in
278.Fa rp
279has an
280.Fa idx
281(index) value of 0.
282.Sh RETURN VALUES
283The
284.Fn fido_credman_get_dev_metadata ,
285.Fn fido_credman_get_dev_rk ,
286.Fn fido_credman_del_dev_rk ,
287and
288.Fn fido_credman_get_dev_rp
289functions return
290.Dv FIDO_OK
291on success.
292On error, a different error code defined in
293.In fido/err.h
294is returned.
295Functions returning pointers are not guaranteed to succeed, and
296should have their return values checked for NULL.
297.Sh SEE ALSO
298.Xr fido_cbor_info_new 3 ,
299.Xr fido_cred_new 3
diff --git a/man/fido_dev_get_assert.3 b/man/fido_dev_get_assert.3
new file mode 100644
index 0000000..2e33fc5
--- /dev/null
+++ b/man/fido_dev_get_assert.3
@@ -0,0 +1,76 @@
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 24 2018 $
6.Dt FIDO_DEV_GET_ASSERT 3
7.Os
8.Sh NAME
9.Nm fido_dev_get_assert
10.Nd obtains an assertion from a FIDO device
11.Sh SYNOPSIS
12.In fido.h
13.Ft int
14.Fn fido_dev_get_assert "fido_dev_t *dev" " fido_assert_t *assert" "const char *pin"
15.Sh DESCRIPTION
16The
17.Fn fido_dev_get_assert
18function asks the FIDO device represented by
19.Fa dev
20for an assertion according to the following parameters defined in
21.Fa assert :
22.Pp
23.Bl -dash -compact
24.It
25.Nm relying party ID ;
26.It
27.Nm client data hash ;
28.It
29.Nm list of allowed credential IDs ;
30.It
31.Nm user presence and user verification attributes .
32.El
33.Pp
34See
35.Xr fido_assert_set_authdata 3
36for information on how these values are set.
37.Pp
38If a PIN is not needed to authenticate the request against
39.Fa dev ,
40then
41.Fa pin
42may be NULL.
43Otherwise
44.Fa pin
45must point to a NUL-terminated UTF-8 string.
46.Pp
47After a successful call to
48.Fn fido_dev_get_assert ,
49the
50.Xr fido_assert_count 3 ,
51.Xr fido_assert_user_display_name 3 ,
52.Xr fido_assert_user_icon 3 ,
53.Xr fido_assert_user_name 3 ,
54.Xr fido_assert_authdata_ptr 3 ,
55.Xr fido_assert_user_id_ptr 3 ,
56.Xr fido_assert_sig_ptr 3 ,
57and
58.Xr fido_assert_sigcount 3
59functions may be invoked on
60.Fa assert
61to retrieve the various attributes of the generated assertion.
62.Pp
63Please note that
64.Fn fido_dev_get_assert
65is synchronous and will block if necessary.
66.Sh RETURN VALUES
67The error codes returned by
68.Fn fido_dev_get_assert
69are defined in
70.In fido/err.h .
71On success,
72.Dv FIDO_OK
73is returned.
74.Sh SEE ALSO
75.Xr fido_assert_new 3 ,
76.Xr fido_assert_set_authdata 3
diff --git a/man/fido_dev_info_manifest.3 b/man/fido_dev_info_manifest.3
new file mode 100644
index 0000000..22519e2
--- /dev/null
+++ b/man/fido_dev_info_manifest.3
@@ -0,0 +1,143 @@
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 25 2018 $
6.Dt FIDO_DEV_INFO_MANIFEST 3
7.Os
8.Sh NAME
9.Nm fido_dev_info_manifest ,
10.Nm fido_dev_info_new ,
11.Nm fido_dev_info_free ,
12.Nm fido_dev_info_ptr ,
13.Nm fido_dev_info_path ,
14.Nm fido_dev_info_product ,
15.Nm fido_dev_info_vendor ,
16.Nm fido_dev_info_manufacturer_string ,
17.Nm fido_dev_info_product_string
18.Nd FIDO 2 device discovery functions
19.Sh SYNOPSIS
20.In fido.h
21.Ft int
22.Fn fido_dev_info_manifest "fido_dev_info_t *devlist" "size_t ilen" "size_t *olen"
23.Ft fido_dev_info_t *
24.Fn fido_dev_info_new "size_t n"
25.Ft void
26.Fn fido_dev_info_free "fido_dev_info_t **devlist_p" "size_t n"
27.Ft const fido_dev_info_t *
28.Fn fido_dev_info_ptr "const fido_dev_info_t *devlist" "size_t i"
29.Ft const char *
30.Fn fido_dev_info_path "const fido_dev_info_t *di"
31.Ft int16_t
32.Fn fido_dev_info_product "const fido_dev_info_t *di"
33.Ft int16_t
34.Fn fido_dev_info_vendor "const fido_dev_info_t *di"
35.Ft const char *
36.Fn fido_dev_info_manufacturer_string "const fido_dev_info_t *di"
37.Ft const char *
38.Fn fido_dev_info_product_string "const fido_dev_info_t *di"
39.Sh DESCRIPTION
40The
41.Fn fido_dev_info_manifest
42function fills
43.Fa devlist
44with up to
45.Fa ilen
46FIDO devices found by the underlying operating system.
47Currently only USB HID devices are supported.
48The number of discovered devices is returned in
49.Fa olen ,
50where
51.Fa olen
52is an addressable pointer.
53.Pp
54The
55.Fn fido_dev_info_new
56function returns a pointer to a newly allocated, empty device list
57with
58.Fa n
59available slots.
60If memory is not available, NULL is returned.
61.Pp
62The
63.Fn fido_dev_info_free
64function releases the memory backing
65.Fa *devlist_p ,
66where
67.Fa *devlist_p
68must have been previously allocated by
69.Fn fido_dev_info_new .
70The number
71.Fa n
72of allocated slots must also be provided.
73On return,
74.Fa *devlist_p
75is set to NULL.
76Either
77.Fa devlist_p
78or
79.Fa *devlist_p
80may be NULL, in which case
81.Fn fido_dev_info_free
82is a NOP.
83.Pp
84The
85.Fn fido_dev_info_ptr
86function returns a pointer to slot number
87.Fa i
88of
89.Fa devlist .
90It is the caller's responsibility to ensure that
91.Fa i
92is bounded.
93Please note that the first slot has index 0.
94.Pp
95The
96.Fn fido_dev_info_path
97returns the filesystem path or subsystem-specific identification
98string of
99.Fa di .
100.Pp
101The
102.Fn fido_dev_info_product
103function returns the product ID of
104.Fa di .
105.Pp
106The
107.Fn fido_dev_info_vendor
108function returns the vendor ID of
109.Fa di .
110.Pp
111The
112.Fn fido_dev_info_manufacturer_string
113function returns the manufacturer string of
114.Fa di .
115.Pp
116The
117.Fn fido_dev_info_product_string
118function returns the product string of
119.Fa di .
120.Pp
121An example of how to use the functions described in this document
122can be found in the
123.Pa examples/manifest.c
124file shipped with
125.Em libfido2 .
126.Sh RETURN VALUES
127The
128.Fn fido_dev_info_manifest
129function always returns
130.Dv FIDO_OK .
131If a discovery error occurs, the
132.Fa olen
133pointer is set to 0.
134.Pp
135The pointers returned by
136.Fn fido_dev_info_ptr ,
137.Fn fido_dev_info_path ,
138.Fn fido_dev_info_manufacturer_string ,
139and
140.Fn fido_dev_info_product_string
141are guaranteed to exist until
142.Fn fido_dev_info_free
143is called on the corresponding device list.
diff --git a/man/fido_dev_make_cred.3 b/man/fido_dev_make_cred.3
new file mode 100644
index 0000000..ccaf788
--- /dev/null
+++ b/man/fido_dev_make_cred.3
@@ -0,0 +1,77 @@
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_DEV_MAKE_CRED 3
7.Os
8.Sh NAME
9.Nm fido_dev_make_cred
10.Nd generates a new credential on a FIDO device
11.Sh SYNOPSIS
12.In fido.h
13.Ft int
14.Fn fido_dev_make_cred "fido_dev_t *dev" " fido_cred_t *cred" "const char *pin"
15.Sh DESCRIPTION
16The
17.Fn fido_dev_make_cred
18function asks the FIDO device represented by
19.Fa dev
20to generate a new credential according to the following parameters
21defined in
22.Fa cred :
23.Pp
24.Bl -dash -compact
25.It
26.Nm type ;
27.It
28.Nm client data hash ;
29.It
30.Nm relying party ;
31.It
32.Nm user attributes ;
33.It
34.Nm list of excluded credential IDs ;
35.It
36.Nm resident key and user verification attributes .
37.El
38.Pp
39See
40.Xr fido_cred_set_authdata 3
41for information on how these values are set.
42.Pp
43If a PIN is not needed to authenticate the request against
44.Fa dev ,
45then
46.Fa pin
47may be NULL.
48Otherwise
49.Fa pin
50must point to a NUL-terminated UTF-8 string.
51.Pp
52After a successful call to
53.Fn fido_dev_make_cred ,
54the
55.Xr fido_cred_authdata_ptr 3 ,
56.Xr fido_cred_pubkey_ptr 3 ,
57.Xr fido_cred_x5c_ptr 3 ,
58and
59.Xr fido_cred_sig_ptr 3
60functions may be invoked on
61.Fa cred
62to retrieve the various parts of the generated credential.
63.Pp
64Please note that
65.Fn fido_dev_make_cred
66is synchronous and will block if necessary.
67.Sh RETURN VALUES
68The error codes returned by
69.Fn fido_dev_make_cred
70are defined in
71.In fido/err.h .
72On success,
73.Dv FIDO_OK
74is returned.
75.Sh SEE ALSO
76.Xr fido_cred_new 3 ,
77.Xr fido_cred_set_authdata 3
diff --git a/man/fido_dev_open.3 b/man/fido_dev_open.3
new file mode 100644
index 0000000..53e3a12
--- /dev/null
+++ b/man/fido_dev_open.3
@@ -0,0 +1,159 @@
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 25 2018 $
6.Dt FIDO_DEV_OPEN 3
7.Os
8.Sh NAME
9.Nm fido_dev_open ,
10.Nm fido_dev_close ,
11.Nm fido_dev_cancel ,
12.Nm fido_dev_new ,
13.Nm fido_dev_free ,
14.Nm fido_dev_force_fido2 ,
15.Nm fido_dev_force_u2f ,
16.Nm fido_dev_is_fido2 ,
17.Nm fido_dev_protocol ,
18.Nm fido_dev_build ,
19.Nm fido_dev_flags ,
20.Nm fido_dev_major ,
21.Nm fido_dev_minor
22.Nd FIDO 2 device open/close and related functions
23.Sh SYNOPSIS
24.In fido.h
25.Ft int
26.Fn fido_dev_open "fido_dev_t *dev" "const char *path"
27.Ft int
28.Fn fido_dev_close "fido_dev_t *dev"
29.Ft int
30.Fn fido_dev_cancel "fido_dev_t *dev"
31.Ft fido_dev_t *
32.Fn fido_dev_new "void"
33.Ft void
34.Fn fido_dev_free "fido_dev_t **dev_p"
35.Ft void
36.Fn fido_dev_force_fido2 "fido_dev_t *dev"
37.Ft void
38.Fn fido_dev_force_u2f "fido_dev_t *dev"
39.Ft bool
40.Fn fido_dev_is_fido2 "const fido_dev_t *dev"
41.Ft uint8_t
42.Fn fido_dev_protocol "const fido_dev_t *dev"
43.Ft uint8_t
44.Fn fido_dev_build "const fido_dev_t *dev"
45.Ft uint8_t
46.Fn fido_dev_flags "const fido_dev_t *dev"
47.Ft uint8_t
48.Fn fido_dev_major "const fido_dev_t *dev"
49.Ft uint8_t
50.Fn fido_dev_minor "const fido_dev_t *dev"
51.Sh DESCRIPTION
52The
53.Fn fido_dev_open
54function opens the device pointed to by
55.Fa path ,
56where
57.Fa dev
58is a freshly allocated or otherwise closed
59.Vt fido_dev_t .
60.Pp
61The
62.Fn fido_dev_close
63function closes the device represented by
64.Fa dev .
65If
66.Fa dev
67is already closed,
68.Fn fido_dev_close
69is a NOP.
70.Pp
71The
72.Fn fido_dev_cancel
73function cancels any pending requests on
74.Fa dev .
75.Pp
76The
77.Fn fido_dev_new
78function returns a pointer to a newly allocated, empty
79.Vt fido_dev_t .
80If memory cannot be allocated, NULL is returned.
81.Pp
82The
83.Fn fido_dev_free
84function releases the memory backing
85.Fa *dev_p ,
86where
87.Fa *dev_p
88must have been previously allocated by
89.Fn fido_dev_new .
90On return,
91.Fa *dev_p
92is set to NULL.
93Either
94.Fa dev_p
95or
96.Fa *dev_p
97may be NULL, in which case
98.Fn fido_dev_free
99is a NOP.
100.Pp
101The
102.Fn fido_dev_force_fido2
103function can be used to force CTAP2 communication with
104.Fa dev .
105.Pp
106The
107.Fn fido_dev_force_u2f
108function can be used to force CTAP1 (U2F) communication with
109.Fa dev .
110.Pp
111The
112.Fn fido_dev_is_fido2
113function returns
114.Dv true
115if
116.Fa dev
117is a FIDO 2 device.
118.Pp
119The
120.Fn fido_dev_protocol
121function returns the CTAPHID protocol version identifier of
122.Fa dev .
123.Pp
124The
125.Fn fido_dev_build
126function returns the CTAPHID build version number of
127.Fa dev .
128.Pp
129The
130.Fn fido_dev_flags
131function returns the CTAPHID capabilities flags of
132.Fa dev .
133.Pp
134The
135.Fn fido_dev_major
136function returns the CTAPHID major version number of
137.Fa dev .
138.Pp
139The
140.Fn fido_dev_minor
141function returns the CTAPHID minor version number of
142.Fa dev .
143.Pp
144For the format and meaning of the CTAPHID parameters returned by
145functions above, please refer to the FIDO Client to Authenticator
146Protocol (CTAP) specification.
147.Sh RETURN VALUES
148On success,
149.Fn fido_dev_open
150and
151.Fn fido_dev_close
152return
153.Dv FIDO_OK .
154On error, a different error code defined in
155.In fido/err.h
156is returned.
157.Sh SEE ALSO
158.Xr fido_dev_info_manifest 3 ,
159.Xr fido_dev_set_io_functions 3
diff --git a/man/fido_dev_set_io_functions.3 b/man/fido_dev_set_io_functions.3
new file mode 100644
index 0000000..adc4a9e
--- /dev/null
+++ b/man/fido_dev_set_io_functions.3
@@ -0,0 +1,95 @@
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 25 2018 $
6.Dt FIDO_DEV_SET_IO_FUNCTIONS 3
7.Os
8.Sh NAME
9.Nm fido_dev_set_io_functions
10.Nd FIDO 2 device I/O interface
11.Sh SYNOPSIS
12.In fido.h
13.Bd -literal
14typedef void *fido_dev_io_open_t(const char *);
15typedef void fido_dev_io_close_t(void *);
16typedef int fido_dev_io_read_t(void *, unsigned char *, size_t, int);
17typedef int fido_dev_io_write_t(void *, const unsigned char *, size_t);
18
19typedef struct fido_dev_io {
20 fido_dev_io_open_t *open;
21 fido_dev_io_close_t *close;
22 fido_dev_io_read_t *read;
23 fido_dev_io_write_t *write;
24} fido_dev_io_t;
25.Ed
26.Ft int
27.Fn fido_dev_set_io_functions "fido_dev_t *dev" "const fido_dev_io_t *io"
28.Sh DESCRIPTION
29The
30.Nm
31interface defines the I/O handlers used to talk to
32.Fa dev .
33Its usage is optional.
34By default,
35.Em libfido2
36will use the operating system's native HID interface to talk to
37a FIDO device.
38.Pp
39A
40.Vt fido_dev_io_open_t
41function is expected to return a non-NULL opaque pointer on success,
42and NULL on error.
43The returned opaque pointer is never dereferenced by
44.Em libfido2 .
45.Pp
46A
47.Vt fido_dev_io_close_t
48function receives the opaque handle obtained from
49.Vt fido_dev_io_open_t .
50It is not expected to be idempotent.
51.Pp
52A
53.Vt fido_dev_io_read_t
54function reads from
55.Fa dev .
56The first parameter taken is the opaque handle obtained from
57.Vt fido_dev_io_open_t .
58The read buffer is pointed to by the second parameter, and the
59third parameter holds its size.
60Finally, the last argument passed to
61.Vt fido_dev_io_read_t
62is the number of milliseconds the caller is willing to sleep,
63should the call need to block.
64If this value holds -1,
65.Vt fido_dev_io_read_t
66may block indefinitely.
67The number of bytes read is returned.
68On error, -1 is returned.
69.Pp
70Conversely, a
71.Vt fido_dev_io_write_t
72function writes to
73.Fa dev .
74The first parameter taken is the opaque handle returned by
75.Vt fido_dev_io_open_t .
76The write buffer is pointed to by the second parameter, and the
77third parameter holds its size.
78A
79.Vt fido_dev_io_write_t
80function may block.
81The number of bytes written is returned.
82On error, -1 is returned.
83.Pp
84No references to
85.Fa io
86are held by
87.Fn fido_dev_set_io_functions .
88.Sh RETURN VALUES
89On success,
90.Fn fido_dev_set_io_functions
91returns
92.Dv FIDO_OK .
93On error, a different error code defined in
94.In fido/err.h
95is returned.
diff --git a/man/fido_dev_set_pin.3 b/man/fido_dev_set_pin.3
new file mode 100644
index 0000000..94f841b
--- /dev/null
+++ b/man/fido_dev_set_pin.3
@@ -0,0 +1,88 @@
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 25 2018 $
6.Dt FIDO_DEV_SET_PIN 3
7.Os
8.Sh NAME
9.Nm fido_dev_set_pin ,
10.Nm fido_dev_get_retry_count ,
11.Nm fido_dev_reset
12.Nd FIDO 2 device management functions
13.Sh SYNOPSIS
14.In fido.h
15.Ft int
16.Fn fido_dev_set_pin "fido_dev_t *dev" "const char *pin" "const char *oldpin"
17.Ft int
18.Fn fido_dev_get_retry_count "fido_dev_t *dev" "int *retries"
19.Ft int
20.Fn fido_dev_reset "fido_dev_t *dev"
21.Sh DESCRIPTION
22The
23.Fn fido_dev_set_pin
24function sets the PIN of device
25.Fa dev
26to
27.Fa pin ,
28where
29.Fa pin
30is a NUL-terminated UTF-8 string.
31If
32.Fa oldpin
33is not NULL, the device's PIN is changed from
34.Fa oldpin
35to
36.Fa pin ,
37where
38.Fa pin
39and
40.Fa oldpin
41are NUL-terminated UTF-8 strings.
42.Pp
43The
44.Fn fido_dev_get_retry_count
45function fills
46.Fa retries
47with the number of PIN retries left in
48.Fa dev
49before lock-out, where
50.Fa retries
51is an addressable pointer.
52.Pp
53The
54.Fn fido_dev_reset
55function performs a reset on
56.Fa dev ,
57resetting the device's PIN and erasing credentials stored on the
58device.
59.Pp
60Please note that
61.Fn fido_dev_set_pin ,
62.Fn fido_dev_get_retry_count ,
63and
64.Fn fido_dev_reset
65are synchronous and will block if necessary.
66.Sh RETURN VALUES
67The error codes returned by
68.Fn fido_dev_set_pin ,
69.Fn fido_dev_get_retry_count ,
70and
71.Fn fido_dev_reset
72are defined in
73.In fido/err.h .
74On success,
75.Dv FIDO_OK
76is returned.
77.Sh CAVEATS
78Regarding
79.Fn fido_dev_reset ,
80the actual user-flow to perform a reset is outside the scope of the
81FIDO2 specification, and may therefore vary depending on the
82authenticator.
83Yubico authenticators will return
84.Dv FIDO_ERR_NOT_ALLOWED
85if a reset is issued later than 5 seconds after power-up, and
86.Dv FIDO_ERR_ACTION_TIMEOUT
87if the user fails to confirm the reset by touching the key
88within 30 seconds.
diff --git a/man/fido_init.3 b/man/fido_init.3
new file mode 100644
index 0000000..7f38948
--- /dev/null
+++ b/man/fido_init.3
@@ -0,0 +1,40 @@
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 25 2018 $
6.Dt FIDO_INIT 3
7.Os
8.Sh NAME
9.Nm fido_init
10.Nd initialise the FIDO 2 library
11.Sh SYNOPSIS
12.In fido.h
13.Ft void
14.Fn fido_init "int flags"
15.Sh DESCRIPTION
16The
17.Fn fido_init
18function initialises the
19.Em libfido2
20library.
21Its invocation must precede that of any other
22.Em libfido2
23function.
24If
25.Dv FIDO_DEBUG
26is set in
27.Fa flags ,
28then
29debug output will be emitted by
30.Em libfido2
31on
32.Em stderr .
33Alternatively, the
34.Ev FIDO_DEBUG
35environment variable may be set.
36.Sh SEE ALSO
37.Xr fido_assert_new 3 ,
38.Xr fido_cred_new 3 ,
39.Xr fido_dev_info_manifest 3 ,
40.Xr fido_dev_open 3
diff --git a/man/fido_strerr.3 b/man/fido_strerr.3
new file mode 100644
index 0000000..05c86b9
--- /dev/null
+++ b/man/fido_strerr.3
@@ -0,0 +1,27 @@
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 25 2018 $
6.Dt FIDO_STRERR 3
7.Os
8.Sh NAME
9.Nm fido_strerr
10.Nd FIDO 2 error codes
11.Sh SYNOPSIS
12.In fido.h
13.Ft const char *
14.Fn fido_strerr "int n"
15.Sh DESCRIPTION
16The
17.Fn fido_strerr
18function translates the error code
19.Fa n
20into a readable string,
21where
22.Fa n
23is an error code defined in
24.In fido/err.h .
25.Fn fido_strerr
26never returns NULL.
27Returned pointers point to static strings.
diff --git a/man/rs256_pk_new.3 b/man/rs256_pk_new.3
new file mode 100644
index 0000000..4ad0ebe
--- /dev/null
+++ b/man/rs256_pk_new.3
@@ -0,0 +1,122 @@
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 24 2018 $
6.Dt RS256_PK_NEW 3
7.Os
8.Sh NAME
9.Nm rs256_pk_new ,
10.Nm rs256_pk_free ,
11.Nm rs256_pk_from_RSA ,
12.Nm rs256_pk_from_ptr ,
13.Nm rs256_pk_to_EVP_PKEY
14.Nd FIDO 2 COSE RS256 API
15.Sh SYNOPSIS
16.In openssl/rsa.h
17.In fido/rs256.h
18.Ft rs256_pk_t *
19.Fn rs256_pk_new "void"
20.Ft void
21.Fn rs256_pk_free "rs256_pk_t **pkp"
22.Ft int
23.Fn rs256_pk_from_RSA "rs256_pk_t *pk" "const RSA *rsa"
24.Ft int
25.Fn rs256_pk_from_ptr "rs256_pk_t *pk" "const void *ptr" "size_t len"
26.Ft EVP_PKEY *
27.Fn rs256_pk_to_EVP_PKEY "const rs256_pk_t *pk"
28.Sh DESCRIPTION
29RS256 is the name given in the CBOR Object Signing and Encryption
30(COSE) RFC to PKCS#1.5 2048-bit RSA with SHA-256.
31The COSE RS256 API of
32.Em libfido2
33is an auxiliary API with routines to convert between the different
34RSA public key types used in
35.Em libfido2
36and
37.Em OpenSSL .
38.Pp
39In
40.Em libfido2 ,
41RS256 public keys are abstracted by the
42.Vt rs256_pk_t
43type.
44.Pp
45The
46.Fn rs256_pk_new
47function returns a pointer to a newly allocated, empty
48.Vt rs256_pk_t
49type.
50If memory cannot be allocated, NULL is returned.
51.Pp
52The
53.Fn rs256_pk_free
54function releases the memory backing
55.Fa *pkp ,
56where
57.Fa *pkp
58must have been previously allocated by
59.Fn rs256_pk_new .
60On return,
61.Fa *pkp
62is set to NULL.
63Either
64.Fa pkp
65or
66.Fa *pkp
67may be NULL, in which case
68.Fn rs256_pk_free
69is a NOP.
70.Pp
71The
72.Fn rs256_pk_from_RSA
73function fills
74.Fa pk
75with the contents of
76.Fa rsa .
77No references to
78.Fa rsa
79are kept.
80.Pp
81The
82.Fn rs256_pk_from_ptr
83function fills
84.Fa pk
85with the contents of
86.Fa ptr ,
87where
88.Fa ptr
89points to
90.Fa len
91bytes.
92No references to
93.Fa ptr
94are kept.
95.Pp
96The
97.Fn rs256_pk_to_EVP_PKEY
98function converts
99.Fa pk
100to a newly allocated
101.Fa EVP_PKEY
102type with a reference count of 1.
103No internal references to the returned pointer are kept.
104If an error occurs,
105.Fn rs256_pk_to_EVP_PKEY
106returns NULL.
107.Sh RETURN VALUES
108The
109.Fn rs256_pk_from_RSA
110and
111.Fn rs256_pk_from_ptr
112functions return
113.Dv FIDO_OK
114on success.
115On error, a different error code defined in
116.In fido/err.h
117is returned.
118.Sh SEE ALSO
119.Xr eddsa_pk_new 3 ,
120.Xr es256_pk_new 3 ,
121.Xr fido_assert_verify 3 ,
122.Xr fido_cred_pubkey_ptr 3
diff --git a/man/style.css b/man/style.css
new file mode 100644
index 0000000..8c223fa
--- /dev/null
+++ b/man/style.css
@@ -0,0 +1,24 @@
1* { margin: 0; padding: 0; }
2
3body {
4 font-family: monospace;
5 font-size: 1em;
6 margin: 2% auto;
7 max-width: 54em;
8}
9
10ul { margin-left: 1em; }
11a { color: #009900; }
12.Sh { font-size: 1em; padding-top: 1em; padding-bottom: 1em; }
13.foot { padding-top: 1em; }
14
15table.head, table.foot { width: 100%; }
16td.head-rtitle, td.foot-os { text-align: right; }
17td.head-vol { text-align: center; }
18div.Pp { margin: 1ex 0ex; }
19div.Nd, div.Bf, div.Op { display: inline; }
20span.Pa, span.Ad { font-style: italic; }
21span.Ms { font-weight: bold; }
22dl.Bl-diag > dt { font-weight: bold; }
23code.Nm, code.Fl, code.Cm, code.Ic, code.In, code.Fd, code.Fn,
24code.Cd { font-weight: bold; font-family: inherit; }
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-10 18:22:42 +0000