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