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 FIDO2 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 CTAP 2.1 authenticator to be 33read, written, and inspected. 34.Dq largeBlobs 35is a CTAP 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 CTAP 2.1's 62.Dq largeBlobs 63extension, please refer to the CTAP 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