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.
5 .Dd $Mdocdate: October 26 2020 $
6 .Dt FIDO_LARGEBLOB_GET 3
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 FIDO2 large blob API
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"
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"
22 .Fn fido_dev_largeblob_remove "fido_dev_t *dev" "const unsigned char *key_ptr" "size_t key_len" "const char *pin"
24 .Fn fido_dev_largeblob_get_array "fido_dev_t *dev" "unsigned char **cbor_ptr" "size_t *cbor_len"
26 .Fn fido_dev_largeblob_set_array "fido_dev_t *dev" "const unsigned char *cbor_ptr" "size_t cbor_len" "const char *pin"
32 allows binary blobs residing on a CTAP 2.1 authenticator to be
33 read, written, and inspected.
35 is a CTAP 2.1 extension.
38 are stored as elements of a CBOR array.
39 Confidentiality is ensured by encrypting each element with a
40 distinct, credential-bound 256-bit AES-GCM key.
41 The array is otherwise shared between different credentials and
42 FIDO2 relying parties.
44 Retrieval of a credential's encryption key is possible during
46 .Xr fido_cred_set_extensions 3
48 .Xr fido_cred_largeblob_key_ptr 3 ,
50 .Xr fido_assert_set_extensions 3
52 .Xr fido_assert_largeblob_key_ptr 3 ,
53 or, in the case of a resident credential, via
55 credential management API.
59 CBOR array is opaque to the authenticator.
60 Management of the array is left at the discretion of FIDO2 clients.
61 For further details on CTAP 2.1's
63 extension, please refer to the CTAP 2.1 spec.
66 .Fn fido_dev_largeblob_get
67 function retrieves the authenticator's
69 CBOR array and, on success, returns the first blob
70 .Pq iterating from array index zero
80 .Fn fido_dev_largeblob_get
83 to the body of the decrypted blob, and
85 to the length of the decrypted blob in bytes.
86 It is the caller's responsibility to free
90 .Fn fido_dev_largeblob_set
95 and inserts the result in the authenticator's
98 Insertion happens at the end of the array if no existing element
101 or at the position of the first element
102 .Pq iterating from array index zero
103 that can be decrypted by
115 or equivalent user-verification gesture is required.
118 .Fn fido_dev_largeblob_remove
119 function retrieves the authenticator's
121 CBOR array and, on success, drops the first blob
122 .Pq iterating from array index zero
123 that can be decrypted by
132 or equivalent user-verification gesture is required.
135 .Fn fido_dev_largeblob_get_array
136 function retrieves the authenticator's
138 CBOR array and, on success,
141 to the body of the CBOR array, and
143 to its corresponding length in bytes.
144 It is the caller's responsibility to free
148 .Fn fido_dev_largeblob_set_array
149 function sets the authenticator's
151 CBOR array to the data pointed to by
160 or equivalent user-verification gesture is required.
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 ,
168 .Fn fido_dev_largeblob_set_array
172 On error, an error code defined in
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
189 extension is not meant to be used to store sensitive data.
190 When retrieved, a credential's
192 encryption key is transmitted in the clear, and an authenticator's
194 CBOR array can be read without user interaction or verification.