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