1FIDO_LARGEBLOB_GET(3)    BSD Library Functions Manual    FIDO_LARGEBLOB_GET(3)
2

NAME

4     fido_dev_largeblob_get, fido_dev_largeblob_set,
5     fido_dev_largeblob_remove, fido_dev_largeblob_get_array,
6     fido_dev_largeblob_set_array — FIDO2 large blob API
7

SYNOPSIS

9     #include <fido.h>
10
11     int
12     fido_dev_largeblob_get(fido_dev_t *dev, const unsigned char *key_ptr,
13         size_t key_len, unsigned char **blob_ptr, size_t *blob_len);
14
15     int
16     fido_dev_largeblob_set(fido_dev_t *dev, const unsigned char *key_ptr,
17         size_t key_len, const unsigned char *blob_ptr, size_t blob_len,
18         const char *pin);
19
20     int
21     fido_dev_largeblob_remove(fido_dev_t *dev, const unsigned char *key_ptr,
22         size_t key_len, const char *pin);
23
24     int
25     fido_dev_largeblob_get_array(fido_dev_t *dev, unsigned char **cbor_ptr,
26         size_t *cbor_len);
27
28     int
29     fido_dev_largeblob_set_array(fido_dev_t *dev,
30         const unsigned char *cbor_ptr, size_t cbor_len, const char *pin);
31

DESCRIPTION

33     The “largeBlobs” API of libfido2 allows binary blobs residing on a CTAP
34     2.1 authenticator to be read, written, and inspected.  “largeBlobs” is a
35     CTAP 2.1 extension.
36
37     “largeBlobs” are stored as elements of a CBOR array.  Confidentiality is
38     ensured by encrypting each element with a distinct, credential-bound
39     256-bit AES-GCM key.  The array is otherwise shared between different
40     credentials and FIDO2 relying parties.
41
42     Retrieval of a credential's encryption key is possible during enrollment
43     with fido_cred_set_extensions(3) and fido_cred_largeblob_key_ptr(3), dur‐
44     ing assertion with fido_assert_set_extensions(3) and
45     fido_assert_largeblob_key_ptr(3), or, in the case of a resident creden‐
46     tial, via libfido2's credential management API.
47
48     The “largeBlobs” CBOR array is opaque to the authenticator.  Management
49     of the array is left at the discretion of FIDO2 clients.  For further de‐
50     tails on CTAP 2.1's “largeBlobs” extension, please refer to the CTAP 2.1
51     spec.
52
53     The fido_dev_largeblob_get() function retrieves the authenticator's
54     “largeBlobs” CBOR array and, on success, returns the first blob
55     (iterating from array index zero) that can be decrypted by key_ptr, where
56     key_ptr points to key_len bytes.  On success, fido_dev_largeblob_get()
57     sets blob_ptr to the body of the decrypted blob, and blob_len to the
58     length of the decrypted blob in bytes.  It is the caller's responsibility
59     to free blob_ptr.
60
61     The fido_dev_largeblob_set() function uses key_ptr to encrypt blob_ptr
62     and inserts the result in the authenticator's “largeBlobs” CBOR array.
63     Insertion happens at the end of the array if no existing element can be
64     decrypted by key_ptr, or at the position of the first element (iterating
65     from array index zero) that can be decrypted by key_ptr.  key_len holds
66     the length of key_ptr in bytes, and blob_len the length of blob_ptr in
67     bytes.  A pin or equivalent user-verification gesture is required.
68
69     The fido_dev_largeblob_remove() function retrieves the authenticator's
70     “largeBlobs” CBOR array and, on success, drops the first blob (iterating
71     from array index zero) that can be decrypted by key_ptr, where key_ptr
72     points to key_len bytes.  A pin or equivalent user-verification gesture
73     is required.
74
75     The fido_dev_largeblob_get_array() function retrieves the authenticator's
76     “largeBlobs” CBOR array and, on success, sets cbor_ptr to the body of the
77     CBOR array, and cbor_len to its corresponding length in bytes.  It is the
78     caller's responsibility to free cbor_ptr.
79
80     Finally, the fido_dev_largeblob_set_array() function sets the authentica‐
81     tor's “largeBlobs” CBOR array to the data pointed to by cbor_ptr, where
82     cbor_ptr points to cbor_len bytes.  A pin or equivalent user-verification
83     gesture is required.
84

RETURN VALUES

86     The functions fido_dev_largeblob_set(), fido_dev_largeblob_get(),
87     fido_dev_largeblob_remove(), fido_dev_largeblob_get_array(), and
88     fido_dev_largeblob_set_array() return FIDO_OK on success.  On error, an
89     error code defined in <fido/err.h> is returned.
90

SEE ALSO

92     fido_assert_largeblob_key_len(3), fido_assert_largeblob_key_ptr(3),
93     fido_assert_set_extensions(3), fido_cred_largeblob_key_len(3),
94     fido_cred_largeblob_key_ptr(3), fido_cred_set_extensions(3),
95     fido_credman_dev_get_rk(3), fido_credman_dev_get_rp(3),
96     fido_dev_get_assert(3), fido_dev_make_cred(3)
97

CAVEATS

99     The “largeBlobs” extension is not meant to be used to store sensitive
100     data.  When retrieved, a credential's “largeBlobs” encryption key is
101     transmitted in the clear, and an authenticator's “largeBlobs” CBOR array
102     can be read without user interaction or verification.
103
104BSD                            October 26, 2020                            BSD