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 FIDO2 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 FIDO2 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
96