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