contrib/libfido2/man/fido_dev_largeblob_get.3

   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
  28 The
  29 .Dq largeBlobs
  30 API of
  31 .Em libfido2
  32 allows binary blobs residing on a CTAP 2.1 authenticator to be
  33 read, written, and inspected.
  34 .Dq largeBlobs
  35 is a CTAP 2.1 extension.
  36 .Pp
  37 .Dq largeBlobs
  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.
  43 .Pp
  44 Retrieval of a credential's encryption key is possible during
  45 enrollment with
  46 .Xr fido_cred_set_extensions 3
  47 and
  48 .Xr fido_cred_largeblob_key_ptr 3 ,
  49 during assertion with
  50 .Xr fido_assert_set_extensions 3
  51 and
  52 .Xr fido_assert_largeblob_key_ptr 3 ,
  53 or, in the case of a resident credential, via
  54 .Em libfido2's
  55 credential management API.
  56 .Pp
  57 The
  58 .Dq largeBlobs
  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
  62 .Dq largeBlobs
  63 extension, please refer to the CTAP 2.1 spec.
  64 .Pp
  65 The
  66 .Fn fido_dev_largeblob_get
  67 function retrieves the authenticator's
  68 .Dq largeBlobs
  69 CBOR array and, on success, returns the first blob
  70 .Pq iterating from array index zero
  71 that can be
  72 decrypted by
  73 .Fa key_ptr ,
  74 where
  75 .Fa key_ptr
  76 points to
  77 .Fa key_len
  78 bytes.
  79 On success,
  80 .Fn fido_dev_largeblob_get
  81 sets
  82 .Fa blob_ptr
  83 to the body of the decrypted blob, and
  84 .Fa blob_len
  85 to the length of the decrypted blob in bytes.
  86 It is the caller's responsibility to free
  87 .Fa blob_ptr .
  88 .Pp
  89 The
  90 .Fn fido_dev_largeblob_set
  91 function uses
  92 .Fa key_ptr
  93 to encrypt
  94 .Fa blob_ptr
  95 and inserts the result in the authenticator's
  96 .Dq largeBlobs
  97 CBOR array.
  98 Insertion happens at the end of the array if no existing element
  99 can be decrypted by
 100 .Fa key_ptr ,
 101 or at the position of the first element
 102 .Pq iterating from array index zero
 103 that can be decrypted by
 104 .Fa key_ptr .
 105 .Fa key_len
 106 holds the length of
 107 .Fa key_ptr
 108 in bytes, and
 109 .Fa blob_len
 110 the length of
 111 .Fa blob_ptr
 112 in bytes.
 113 A
 114 .Fa pin
 115 or equivalent user-verification gesture is required.
 116 .Pp
 117 The
 118 .Fn fido_dev_largeblob_remove
 119 function retrieves the authenticator's
 120 .Dq largeBlobs
 121 CBOR array and, on success, drops the first blob
 122 .Pq iterating from array index zero
 123 that can be decrypted by
 124 .Fa key_ptr ,
 125 where
 126 .Fa key_ptr
 127 points to
 128 .Fa key_len
 129 bytes.
 130 A
 131 .Fa pin
 132 or equivalent user-verification gesture is required.
 133 .Pp
 134 The
 135 .Fn fido_dev_largeblob_get_array
 136 function retrieves the authenticator's
 137 .Dq largeBlobs
 138 CBOR array and, on success,
 139 sets
 140 .Fa cbor_ptr
 141 to the body of the CBOR array, and
 142 .Fa cbor_len
 143 to its corresponding length in bytes.
 144 It is the caller's responsibility to free
 145 .Fa cbor_ptr .
 146 .Pp
 147 Finally, the
 148 .Fn fido_dev_largeblob_set_array
 149 function sets the authenticator's
 150 .Dq largeBlobs
 151 CBOR array to the data pointed to by
 152 .Fa cbor_ptr ,
 153 where
 154 .Fa cbor_ptr
 155 points to
 156 .Fa cbor_len
 157 bytes.
 158 A
 159 .Fa pin
 160 or equivalent user-verification gesture is required.
 161 .Sh RETURN VALUES
 162 The 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 ,
 167 and
 168 .Fn fido_dev_largeblob_set_array
 169 return
 170 .Dv FIDO_OK
 171 on success.
 172 On error, an error code defined in
 173 .In fido/err.h
 174 is 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
 187 The
 188 .Dq largeBlobs
 189 extension is not meant to be used to store sensitive data.
 190 When retrieved, a credential's
 191 .Dq largeBlobs
 192 encryption key is transmitted in the clear, and an authenticator's
 193 .Dq largeBlobs
 194 CBOR array can be read without user interaction or verification.