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