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