xref: /freebsd/contrib/libfido2/man/fido_dev_largeblob_get.3 (revision 3332f1b444d4a73238e9f59cca27bfc95fe936bd)
1.\" Copyright (c) 2020 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: October 26 2020 $
6.Dt FIDO_LARGEBLOB_GET 3
7.Os
8.Sh NAME
9.Nm fido_dev_largeblob_get ,
10.Nm fido_dev_largeblob_set ,
11.Nm fido_dev_largeblob_remove ,
12.Nm fido_dev_largeblob_get_array ,
13.Nm fido_dev_largeblob_set_array
14.Nd FIDO 2 large blob API
15.Sh SYNOPSIS
16.In fido.h
17.Ft int
18.Fn fido_dev_largeblob_get "fido_dev_t *dev" "const unsigned char *key_ptr" "size_t key_len" "unsigned char **blob_ptr" "size_t *blob_len"
19.Ft int
20.Fn fido_dev_largeblob_set "fido_dev_t *dev" "const unsigned char *key_ptr" "size_t key_len" "const unsigned char *blob_ptr" "size_t blob_len" "const char *pin"
21.Ft int
22.Fn fido_dev_largeblob_remove "fido_dev_t *dev" "const unsigned char *key_ptr" "size_t key_len" "const char *pin"
23.Ft int
24.Fn fido_dev_largeblob_get_array "fido_dev_t *dev" "unsigned char **cbor_ptr" "size_t *cbor_len"
25.Ft int
26.Fn fido_dev_largeblob_set_array "fido_dev_t *dev" "const unsigned char *cbor_ptr" "size_t cbor_len" "const char *pin"
27.Sh DESCRIPTION
28The
29.Dq largeBlobs
30API of
31.Em libfido2
32allows binary blobs residing on a FIDO 2.1 authenticator to be
33read, written, and inspected.
34.Dq largeBlobs
35is a FIDO 2.1 extension.
36.Pp
37.Dq largeBlobs
38are stored as elements of a CBOR array.
39Confidentiality is ensured by encrypting each element with a
40distinct, credential-bound 256-bit AES-GCM key.
41The array is otherwise shared between different credentials and
42FIDO2 relying parties.
43.Pp
44Retrieval of a credential's encryption key is possible during
45enrollment with
46.Xr fido_cred_set_extensions 3
47and
48.Xr fido_cred_largeblob_key_ptr 3 ,
49during assertion with
50.Xr fido_assert_set_extensions 3
51and
52.Xr fido_assert_largeblob_key_ptr 3 ,
53or, in the case of a resident credential, via
54.Em libfido2's
55credential management API.
56.Pp
57The
58.Dq largeBlobs
59CBOR array is opaque to the authenticator.
60Management of the array is left at the discretion of FIDO2 clients.
61For further details on FIDO 2.1's
62.Dq largeBlobs
63extension, please refer to the FIDO 2.1 spec.
64.Pp
65The
66.Fn fido_dev_largeblob_get
67function retrieves the authenticator's
68.Dq largeBlobs
69CBOR array and, on success, returns the first blob
70.Pq iterating from array index zero
71that can be
72decrypted by
73.Fa key_ptr ,
74where
75.Fa key_ptr
76points to
77.Fa key_len
78bytes.
79On success,
80.Fn fido_dev_largeblob_get
81sets
82.Fa blob_ptr
83to the body of the decrypted blob, and
84.Fa blob_len
85to the length of the decrypted blob in bytes.
86It is the caller's responsibility to free
87.Fa blob_ptr .
88.Pp
89The
90.Fn fido_dev_largeblob_set
91function uses
92.Fa key_ptr
93to encrypt
94.Fa blob_ptr
95and inserts the result in the authenticator's
96.Dq largeBlobs
97CBOR array.
98Insertion happens at the end of the array if no existing element
99can be decrypted by
100.Fa key_ptr ,
101or at the position of the first element
102.Pq iterating from array index zero
103that can be decrypted by
104.Fa key_ptr .
105.Fa key_len
106holds the length of
107.Fa key_ptr
108in bytes, and
109.Fa blob_len
110the length of
111.Fa blob_ptr
112in bytes.
113A
114.Fa pin
115or equivalent user-verification gesture is required.
116.Pp
117The
118.Fn fido_dev_largeblob_remove
119function retrieves the authenticator's
120.Dq largeBlobs
121CBOR array and, on success, drops the first blob
122.Pq iterating from array index zero
123that can be decrypted by
124.Fa key_ptr ,
125where
126.Fa key_ptr
127points to
128.Fa key_len
129bytes.
130A
131.Fa pin
132or equivalent user-verification gesture is required.
133.Pp
134The
135.Fn fido_dev_largeblob_get_array
136function retrieves the authenticator's
137.Dq largeBlobs
138CBOR array and, on success,
139sets
140.Fa cbor_ptr
141to the body of the CBOR array, and
142.Fa cbor_len
143to its corresponding length in bytes.
144It is the caller's responsibility to free
145.Fa cbor_ptr .
146.Pp
147Finally, the
148.Fn fido_dev_largeblob_set_array
149function sets the authenticator's
150.Dq largeBlobs
151CBOR array to the data pointed to by
152.Fa cbor_ptr ,
153where
154.Fa cbor_ptr
155points to
156.Fa cbor_len
157bytes.
158A
159.Fa pin
160or equivalent user-verification gesture is required.
161.Sh RETURN VALUES
162The functions
163.Fn fido_dev_largeblob_set ,
164.Fn fido_dev_largeblob_get ,
165.Fn fido_dev_largeblob_remove ,
166.Fn fido_dev_largeblob_get_array ,
167and
168.Fn fido_dev_largeblob_set_array
169return
170.Dv FIDO_OK
171on success.
172On error, an error code defined in
173.In fido/err.h
174is returned.
175.Sh SEE ALSO
176.Xr fido_assert_largeblob_key_len 3 ,
177.Xr fido_assert_largeblob_key_ptr 3 ,
178.Xr fido_assert_set_extensions 3 ,
179.Xr fido_cred_largeblob_key_len 3 ,
180.Xr fido_cred_largeblob_key_ptr 3 ,
181.Xr fido_cred_set_extensions 3 ,
182.Xr fido_credman_dev_get_rk 3 ,
183.Xr fido_credman_dev_get_rp 3 ,
184.Xr fido_dev_get_assert 3 ,
185.Xr fido_dev_make_cred 3
186.Sh CAVEATS
187The
188.Dq largeBlobs
189extension is not meant to be used to store sensitive data.
190When retrieved, a credential's
191.Dq largeBlobs
192encryption key is transmitted in the clear, and an authenticator's
193.Dq largeBlobs
194CBOR array can be read without user interaction or verification.
195