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