xref: /freebsd/contrib/libfido2/man/fido_dev_open.3 (revision f81cdf24ba5436367377f7c8e8f51f6df2a75ca7) 
1.\" Copyright (c) 2018 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: May 25 2018 $
29.Dt FIDO_DEV_OPEN 3
30.Os
31.Sh NAME
32.Nm fido_dev_open ,
33.Nm fido_dev_open_with_info ,
34.Nm fido_dev_close ,
35.Nm fido_dev_cancel ,
36.Nm fido_dev_new ,
37.Nm fido_dev_new_with_info ,
38.Nm fido_dev_free ,
39.Nm fido_dev_force_fido2 ,
40.Nm fido_dev_force_u2f ,
41.Nm fido_dev_is_fido2 ,
42.Nm fido_dev_is_winhello ,
43.Nm fido_dev_supports_credman ,
44.Nm fido_dev_supports_cred_prot ,
45.Nm fido_dev_supports_permissions ,
46.Nm fido_dev_supports_pin ,
47.Nm fido_dev_supports_uv ,
48.Nm fido_dev_has_pin ,
49.Nm fido_dev_has_uv ,
50.Nm fido_dev_protocol ,
51.Nm fido_dev_build ,
52.Nm fido_dev_flags ,
53.Nm fido_dev_major ,
54.Nm fido_dev_minor
55.Nd FIDO2 device open/close and related functions
56.Sh SYNOPSIS
57.In fido.h
58.Ft int
59.Fn fido_dev_open "fido_dev_t *dev" "const char *path"
60.Ft int
61.Fn fido_dev_open_with_info "fido_dev_t *dev"
62.Ft int
63.Fn fido_dev_close "fido_dev_t *dev"
64.Ft int
65.Fn fido_dev_cancel "fido_dev_t *dev"
66.Ft fido_dev_t *
67.Fn fido_dev_new "void"
68.Ft fido_dev_t *
69.Fn fido_dev_new_with_info "const fido_dev_info_t *"
70.Ft void
71.Fn fido_dev_free "fido_dev_t **dev_p"
72.Ft void
73.Fn fido_dev_force_fido2 "fido_dev_t *dev"
74.Ft void
75.Fn fido_dev_force_u2f "fido_dev_t *dev"
76.Ft bool
77.Fn fido_dev_is_fido2 "const fido_dev_t *dev"
78.Ft bool
79.Fn fido_dev_is_winhello "const fido_dev_t *dev"
80.Ft bool
81.Fn fido_dev_supports_credman "const fido_dev_t *dev"
82.Ft bool
83.Fn fido_dev_supports_cred_prot "const fido_dev_t *dev"
84.Ft bool
85.Fn fido_dev_supports_permissions "const fido_dev_t *dev"
86.Ft bool
87.Fn fido_dev_supports_pin "const fido_dev_t *dev"
88.Ft bool
89.Fn fido_dev_supports_uv "const fido_dev_t *dev"
90.Ft bool
91.Fn fido_dev_has_pin "const fido_dev_t *dev"
92.Ft bool
93.Fn fido_dev_has_uv "const fido_dev_t *dev"
94.Ft uint8_t
95.Fn fido_dev_protocol "const fido_dev_t *dev"
96.Ft uint8_t
97.Fn fido_dev_build "const fido_dev_t *dev"
98.Ft uint8_t
99.Fn fido_dev_flags "const fido_dev_t *dev"
100.Ft uint8_t
101.Fn fido_dev_major "const fido_dev_t *dev"
102.Ft uint8_t
103.Fn fido_dev_minor "const fido_dev_t *dev"
104.Sh DESCRIPTION
105The
106.Fn fido_dev_open
107function opens the device pointed to by
108.Fa path ,
109where
110.Fa dev
111is a freshly allocated or otherwise closed
112.Vt fido_dev_t .
113If
114.Fa dev
115claims to be FIDO2,
116.Em libfido2
117will attempt to speak FIDO2 to
118.Fa dev .
119If that fails,
120.Em libfido2
121will fallback to U2F unless the
122.Dv FIDO_DISABLE_U2F_FALLBACK
123flag was set in
124.Xr fido_init 3 .
125.Pp
126The
127.Fn fido_dev_open_with_info
128function opens
129.Fa dev
130as previously allocated using
131.Fn fido_dev_new_with_info .
132.Pp
133The
134.Fn fido_dev_close
135function closes the device represented by
136.Fa dev .
137If
138.Fa dev
139is already closed,
140.Fn fido_dev_close
141is a NOP.
142.Pp
143The
144.Fn fido_dev_cancel
145function cancels any pending requests on
146.Fa dev .
147.Pp
148The
149.Fn fido_dev_new
150function returns a pointer to a newly allocated, empty
151.Vt fido_dev_t .
152If memory cannot be allocated, NULL is returned.
153.Pp
154The
155.Fn fido_dev_new_with_info
156function returns a pointer to a newly allocated
157.Vt fido_dev_t
158with
159.Vt fido_dev_info_t
160parameters, for use with
161.Xr fido_dev_info_manifest 3
162and
163.Fn fido_dev_open_with_info .
164If memory cannot be allocated, NULL is returned.
165.Pp
166The
167.Fn fido_dev_free
168function releases the memory backing
169.Fa *dev_p ,
170where
171.Fa *dev_p
172must have been previously allocated by
173.Fn fido_dev_new .
174On return,
175.Fa *dev_p
176is set to NULL.
177Either
178.Fa dev_p
179or
180.Fa *dev_p
181may be NULL, in which case
182.Fn fido_dev_free
183is a NOP.
184.Pp
185The
186.Fn fido_dev_force_fido2
187function can be used to force CTAP2 communication with
188.Fa dev ,
189where
190.Fa dev
191is an open device.
192.Pp
193The
194.Fn fido_dev_force_u2f
195function can be used to force CTAP1 (U2F) communication with
196.Fa dev ,
197where
198.Fa dev
199is an open device.
200.Pp
201The
202.Fn fido_dev_is_fido2
203function returns
204.Dv true
205if
206.Fa dev
207is a FIDO2 device.
208.Pp
209The
210.Fn fido_dev_is_winhello
211function returns
212.Dv true
213if
214.Fa dev
215is a Windows Hello device.
216.Pp
217The
218.Fn fido_dev_supports_credman
219function returns
220.Dv true
221if
222.Fa dev
223supports CTAP 2.1 Credential Management.
224.Pp
225The
226.Fn fido_dev_supports_cred_prot
227function returns
228.Dv true
229if
230.Fa dev
231supports CTAP 2.1 Credential Protection.
232.Pp
233The
234.Fn fido_dev_supports_permissions
235function returns
236.Dv true
237if
238.Fa dev
239supports CTAP 2.1 UV token permissions.
240.Pp
241The
242.Fn fido_dev_supports_pin
243function returns
244.Dv true
245if
246.Fa dev
247supports CTAP 2.0 Client PINs.
248.Pp
249The
250.Fn fido_dev_supports_uv
251function returns
252.Dv true
253if
254.Fa dev
255supports a built-in user verification method.
256.Pp
257The
258.Fn fido_dev_has_pin
259function returns
260.Dv true
261if
262.Fa dev
263has a CTAP 2.0 Client PIN set.
264.Pp
265The
266.Fn fido_dev_has_uv
267function returns
268.Dv true
269if
270.Fa dev
271supports built-in user verification and its user verification
272feature is configured.
273.Pp
274The
275.Fn fido_dev_protocol
276function returns the CTAPHID protocol version identifier of
277.Fa dev .
278.Pp
279The
280.Fn fido_dev_build
281function returns the CTAPHID build version number of
282.Fa dev .
283.Pp
284The
285.Fn fido_dev_flags
286function returns the CTAPHID capabilities flags of
287.Fa dev .
288.Pp
289The
290.Fn fido_dev_major
291function returns the CTAPHID major version number of
292.Fa dev .
293.Pp
294The
295.Fn fido_dev_minor
296function returns the CTAPHID minor version number of
297.Fa dev .
298.Pp
299For the format and meaning of the CTAPHID parameters returned by
300functions above, please refer to the FIDO Client to Authenticator
301Protocol (CTAP) specification.
302.Sh RETURN VALUES
303On success,
304.Fn fido_dev_open ,
305.Fn fido_dev_open_with_info ,
306and
307.Fn fido_dev_close
308return
309.Dv FIDO_OK .
310On error, a different error code defined in
311.In fido/err.h
312is returned.
313.Sh SEE ALSO
314.Xr fido_dev_info_manifest 3 ,
315.Xr fido_dev_set_io_functions 3 ,
316.Xr fido_init 3
317