1.\" Copyright (c) 2019 Yubico AB. All rights reserved.
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions are
5.\" met:
6.\"
7.\"    1. Redistributions of source code must retain the above copyright
8.\"       notice, this list of conditions and the following disclaimer.
9.\"    2. Redistributions in binary form must reproduce the above copyright
10.\"       notice, this list of conditions and the following disclaimer in
11.\"       the documentation and/or other materials provided with the
12.\"       distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
15.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
16.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
17.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
18.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
19.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
20.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25.\"
26.\" SPDX-License-Identifier: BSD-2-Clause
27.\"
28.Dd $Mdocdate: September 13 2019 $
29.Dt FIDO_BIO_DEV_GET_INFO 3
30.Os
31.Sh NAME
32.Nm fido_bio_dev_get_info ,
33.Nm fido_bio_dev_enroll_begin ,
34.Nm fido_bio_dev_enroll_continue ,
35.Nm fido_bio_dev_enroll_cancel ,
36.Nm fido_bio_dev_enroll_remove ,
37.Nm fido_bio_dev_get_template_array ,
38.Nm fido_bio_dev_set_template_name
39.Nd FIDO2 biometric authenticator API
40.Sh SYNOPSIS
41.In fido.h
42.In fido/bio.h
43.Ft int
44.Fn fido_bio_dev_get_info "fido_dev_t *dev" "fido_bio_info_t *info"
45.Ft int
46.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"
47.Ft int
48.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"
49.Ft int
50.Fn fido_bio_dev_enroll_cancel "fido_dev_t *dev"
51.Ft int
52.Fn fido_bio_dev_enroll_remove "fido_dev_t *dev" "const fido_bio_template_t *template" "const char *pin"
53.Ft int
54.Fn fido_bio_dev_get_template_array "fido_dev_t *dev" "fido_bio_template_array_t *template_array" "const char *pin"
55.Ft int
56.Fn fido_bio_dev_set_template_name "fido_dev_t *dev" "const fido_bio_template_t *template" "const char *pin"
57.Sh DESCRIPTION
58The functions described in this page allow biometric
59templates on a FIDO2 authenticator to be listed, created,
60removed, and customised.
61Please note that not all FIDO2 authenticators support biometric
62enrollment.
63For a description of the types involved, please refer to
64.Xr fido_bio_info_new 3 ,
65.Xr fido_bio_enroll_new 3 ,
66and
67.Xr fido_bio_template 3 .
68.Pp
69The
70.Fn fido_bio_dev_get_info
71function populates
72.Fa info
73with sensor information from
74.Fa dev .
75.Pp
76The
77.Fn fido_bio_dev_enroll_begin
78function initiates a biometric enrollment on
79.Fa dev ,
80instructing the authenticator to wait
81.Fa timeout_ms
82milliseconds.
83On success,
84.Fa template
85and
86.Fa enroll
87will be populated with the newly created template's
88information and enrollment status, respectively.
89.Pp
90The
91.Fn fido_bio_dev_enroll_continue
92function continues an ongoing enrollment on
93.Fa dev ,
94instructing the authenticator to wait
95.Fa timeout_ms
96milliseconds.
97On success,
98.Fa enroll
99will be updated to reflect the status of the biometric
100enrollment.
101.Pp
102The
103.Fn fido_bio_dev_enroll_cancel
104function cancels an ongoing enrollment on
105.Fa dev .
106.Pp
107The
108.Fn fido_bio_dev_enroll_remove
109function removes
110.Fa template
111from
112.Fa dev .
113.Pp
114The
115.Fn fido_bio_dev_get_template_array
116function populates
117.Fa template_array
118with the templates currently enrolled on
119.Fa dev .
120.Pp
121The
122.Fn fido_bio_dev_set_template_name
123function sets the friendly name of
124.Fa template
125on
126.Fa dev .
127.Sh RETURN VALUES
128The error codes returned by
129.Fn fido_bio_dev_get_info ,
130.Fn fido_bio_dev_enroll_begin ,
131.Fn fido_bio_dev_enroll_continue ,
132.Fn fido_bio_dev_enroll_cancel ,
133.Fn fido_bio_dev_enroll_remove ,
134.Fn fido_bio_dev_get_template_array ,
135and
136.Fn fido_bio_dev_set_template_name
137are defined in
138.In fido/err.h .
139On success,
140.Dv FIDO_OK
141is returned.
142.Sh SEE ALSO
143.Xr fido_bio_enroll_new 3 ,
144.Xr fido_bio_info_new 3 ,
145.Xr fido_bio_template 3
146