Debian Codegraph @

extra/libfido2/libfido2-1.15.0/man/fido_bio_template.3

raw
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_TEMPLATE 3
30 .Os
31 .Sh NAME
32 .Nm fido_bio_template ,
33 .Nm fido_bio_template_array_count ,
34 .Nm fido_bio_template_array_free ,
35 .Nm fido_bio_template_array_new ,
36 .Nm fido_bio_template_free ,
37 .Nm fido_bio_template_id_len ,
38 .Nm fido_bio_template_id_ptr ,
39 .Nm fido_bio_template_name ,
40 .Nm fido_bio_template_new ,
41 .Nm fido_bio_template_set_id ,
42 .Nm fido_bio_template_set_name
43 .Nd FIDO2 biometric template API
44 .Sh SYNOPSIS
45 .In fido.h
46 .In fido/bio.h
47 .Ft fido_bio_template_t *
48 .Fn fido_bio_template_new "void"
49 .Ft void
50 .Fn fido_bio_template_free "fido_bio_template_t **template_p"
51 .Ft const char *
52 .Fn fido_bio_template_name "const fido_bio_template_t *template"
53 .Ft const unsigned char *
54 .Fn fido_bio_template_id_ptr "const fido_bio_template_t *template"
55 .Ft size_t
56 .Fn fido_bio_template_id_len "const fido_bio_template_t *template"
57 .Ft int
58 .Fn fido_bio_template_set_id "fido_bio_template_t *template" "const unsigned char *ptr" "size_t len"
59 .Ft int
60 .Fn fido_bio_template_set_name "fido_bio_template_t *template" "const char *name"
61 .Ft fido_bio_template_array_t *
62 .Fn fido_bio_template_array_new "void"
63 .Ft void
64 .Fn fido_bio_template_array_free "fido_bio_template_array_t **array_p"
65 .Ft size_t
66 .Fn fido_bio_template_array_count "const fido_bio_template_array_t *array"
67 .Ft const fido_bio_template_t *
68 .Fn fido_bio_template "const fido_bio_template_array_t *array" "size_t idx"
69 .Sh DESCRIPTION
70 Existing FIDO2 biometric enrollments are abstracted in
71 .Em libfido2
72 by the
73 .Vt fido_bio_template_t
74 and
75 .Vt fido_bio_template_array_t
76 types.
77 .Pp
78 The functions described in this page allow a
79 .Vt fido_bio_template_t
80 type to be allocated, deallocated, changed, and inspected,
81 and a
82 .Vt fido_bio_template_array_t
83 type to be allocated, deallocated, and inspected.
84 For device operations on
85 .Vt fido_bio_template_t
86 and
87 .Vt fido_bio_template_array_t ,
88 please refer to
89 .Xr fido_bio_dev_get_info 3 .
90 .Pp
91 The
92 .Fn fido_bio_template_new
93 function returns a pointer to a newly allocated, empty
94 .Vt fido_bio_template_t
95 type.
96 If memory cannot be allocated, NULL is returned.
97 .Pp
98 The
99 .Fn fido_bio_template_free
100 function releases the memory backing
101 .Fa *template_p ,
102 where
103 .Fa *template_p
104 must have been previously allocated by
105 .Fn fido_bio_template_new .
106 On return,
107 .Fa *template_p
108 is set to NULL.
109 Either
110 .Fa template_p
111 or
112 .Fa *template_p
113 may be NULL, in which case
114 .Fn fido_bio_template_free
115 is a NOP.
116 .Pp
117 The
118 .Fn fido_bio_template_name
119 function returns a pointer to a NUL-terminated string containing
120 the friendly name of
121 .Fa template ,
122 or NULL if
123 .Fa template
124 does not have a friendly name set.
125 .Pp
126 The
127 .Fn fido_bio_template_id_ptr
128 function returns a pointer to the template id of
129 .Fa template ,
130 or NULL if
131 .Fa template
132 does not have an id.
133 The corresponding length can be obtained by
134 .Fn fido_bio_template_id_len .
135 .Pp
136 The
137 .Fn fido_bio_template_set_name
138 function sets the friendly name of
139 .Fa template
140 to
141 .Fa name .
142 If
143 .Fa name
144 is NULL, the friendly name of
145 .Fa template
146 is unset.
147 .Pp
148 The
149 .Fn fido_bio_template_array_new
150 function returns a pointer to a newly allocated, empty
151 .Vt fido_bio_template_array_t
152 type.
153 If memory cannot be allocated, NULL is returned.
154 .Pp
155 The
156 .Fn fido_bio_template_array_free
157 function releases the memory backing
158 .Fa *array_p ,
159 where
160 .Fa *array_p
161 must have been previously allocated by
162 .Fn fido_bio_template_array_new .
163 On return,
164 .Fa *array_p
165 is set to NULL.
166 Either
167 .Fa array_p
168 or
169 .Fa *array_p
170 may be NULL, in which case
171 .Fn fido_bio_template_array_free
172 is a NOP.
173 .Pp
174 The
175 .Fn fido_bio_template_array_count
176 function returns the number of templates in
177 .Fa array .
178 .Pp
179 The
180 .Fn fido_bio_template
181 function returns a pointer to the template at index
182 .Fa idx
183 in
184 .Fa array .
185 Please note that the first template in
186 .Fa array
187 has an
188 .Fa idx
189 (index) value of 0.
190 .Sh RETURN VALUES
191 The error codes returned by
192 .Fn fido_bio_template_set_id
193 and
194 .Fn fido_bio_template_set_name
195 are defined in
196 .In fido/err.h .
197 On success,
198 .Dv FIDO_OK
199 is returned.
200 .Sh SEE ALSO
201 .Xr fido_bio_dev_get_info 3 ,
202 .Xr fido_bio_enroll_new 3