contrib/libfido2/man/fido_dev_largeblob_get.3

   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.