mirror of
https://git.hardenedbsd.org/hardenedbsd/HardenedBSD.git
synced 2024-11-25 10:01:02 +01:00
2ccfa855b2
Some highlights from NEWS entries: ** Improved OpenSSL 3.0 compatibility. ** Support for hidraw(4) on FreeBSD; gh#597. ** Improved support for FIDO 2.1 authenticators. PR: 273596 Relnotes: Yes Sponsored by: The FreeBSD Foundation
217 lines
6.1 KiB
Groff
217 lines
6.1 KiB
Groff
.\" Copyright (c) 2020 Yubico AB. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions are
|
|
.\" met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in
|
|
.\" the documentation and/or other materials provided with the
|
|
.\" distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" SPDX-License-Identifier: BSD-2-Clause
|
|
.\"
|
|
.Dd $Mdocdate: October 26 2020 $
|
|
.Dt FIDO_LARGEBLOB_GET 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm fido_dev_largeblob_get ,
|
|
.Nm fido_dev_largeblob_set ,
|
|
.Nm fido_dev_largeblob_remove ,
|
|
.Nm fido_dev_largeblob_get_array ,
|
|
.Nm fido_dev_largeblob_set_array
|
|
.Nd FIDO2 large blob API
|
|
.Sh SYNOPSIS
|
|
.In fido.h
|
|
.Ft int
|
|
.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"
|
|
.Ft int
|
|
.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"
|
|
.Ft int
|
|
.Fn fido_dev_largeblob_remove "fido_dev_t *dev" "const unsigned char *key_ptr" "size_t key_len" "const char *pin"
|
|
.Ft int
|
|
.Fn fido_dev_largeblob_get_array "fido_dev_t *dev" "unsigned char **cbor_ptr" "size_t *cbor_len"
|
|
.Ft int
|
|
.Fn fido_dev_largeblob_set_array "fido_dev_t *dev" "const unsigned char *cbor_ptr" "size_t cbor_len" "const char *pin"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Dq largeBlobs
|
|
API of
|
|
.Em libfido2
|
|
allows binary blobs residing on a CTAP 2.1 authenticator to be
|
|
read, written, and inspected.
|
|
.Dq largeBlobs
|
|
is a CTAP 2.1 extension.
|
|
.Pp
|
|
.Dq largeBlobs
|
|
are stored as elements of a CBOR array.
|
|
Confidentiality is ensured by encrypting each element with a
|
|
distinct, credential-bound 256-bit AES-GCM key.
|
|
The array is otherwise shared between different credentials and
|
|
FIDO2 relying parties.
|
|
.Pp
|
|
Retrieval of a credential's encryption key is possible during
|
|
enrollment with
|
|
.Xr fido_cred_set_extensions 3
|
|
and
|
|
.Xr fido_cred_largeblob_key_ptr 3 ,
|
|
during assertion with
|
|
.Xr fido_assert_set_extensions 3
|
|
and
|
|
.Xr fido_assert_largeblob_key_ptr 3 ,
|
|
or, in the case of a resident credential, via
|
|
.Em libfido2's
|
|
credential management API.
|
|
.Pp
|
|
The
|
|
.Dq largeBlobs
|
|
CBOR array is opaque to the authenticator.
|
|
Management of the array is left at the discretion of FIDO2 clients.
|
|
For further details on CTAP 2.1's
|
|
.Dq largeBlobs
|
|
extension, please refer to the CTAP 2.1 spec.
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_largeblob_get
|
|
function retrieves the authenticator's
|
|
.Dq largeBlobs
|
|
CBOR array and, on success, returns the first blob
|
|
.Pq iterating from array index zero
|
|
that can be decrypted by
|
|
.Fa key_ptr ,
|
|
where
|
|
.Fa key_ptr
|
|
points to
|
|
.Fa key_len
|
|
bytes.
|
|
On success,
|
|
.Fn fido_dev_largeblob_get
|
|
sets
|
|
.Fa blob_ptr
|
|
to the body of the decrypted blob, and
|
|
.Fa blob_len
|
|
to the length of the decrypted blob in bytes.
|
|
It is the caller's responsibility to free
|
|
.Fa blob_ptr .
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_largeblob_set
|
|
function uses
|
|
.Fa key_ptr
|
|
to encrypt
|
|
.Fa blob_ptr
|
|
and inserts the result in the authenticator's
|
|
.Dq largeBlobs
|
|
CBOR array.
|
|
Insertion happens at the end of the array if no existing element
|
|
can be decrypted by
|
|
.Fa key_ptr ,
|
|
or at the position of the first element
|
|
.Pq iterating from array index zero
|
|
that can be decrypted by
|
|
.Fa key_ptr .
|
|
.Fa key_len
|
|
holds the length of
|
|
.Fa key_ptr
|
|
in bytes, and
|
|
.Fa blob_len
|
|
the length of
|
|
.Fa blob_ptr
|
|
in bytes.
|
|
A
|
|
.Fa pin
|
|
or equivalent user-verification gesture is required.
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_largeblob_remove
|
|
function retrieves the authenticator's
|
|
.Dq largeBlobs
|
|
CBOR array and, on success, drops the first blob
|
|
.Pq iterating from array index zero
|
|
that can be decrypted by
|
|
.Fa key_ptr ,
|
|
where
|
|
.Fa key_ptr
|
|
points to
|
|
.Fa key_len
|
|
bytes.
|
|
A
|
|
.Fa pin
|
|
or equivalent user-verification gesture is required.
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_largeblob_get_array
|
|
function retrieves the authenticator's
|
|
.Dq largeBlobs
|
|
CBOR array and, on success,
|
|
sets
|
|
.Fa cbor_ptr
|
|
to the body of the CBOR array, and
|
|
.Fa cbor_len
|
|
to its corresponding length in bytes.
|
|
It is the caller's responsibility to free
|
|
.Fa cbor_ptr .
|
|
.Pp
|
|
Finally, the
|
|
.Fn fido_dev_largeblob_set_array
|
|
function sets the authenticator's
|
|
.Dq largeBlobs
|
|
CBOR array to the data pointed to by
|
|
.Fa cbor_ptr ,
|
|
where
|
|
.Fa cbor_ptr
|
|
points to
|
|
.Fa cbor_len
|
|
bytes.
|
|
A
|
|
.Fa pin
|
|
or equivalent user-verification gesture is required.
|
|
.Sh RETURN VALUES
|
|
The functions
|
|
.Fn fido_dev_largeblob_set ,
|
|
.Fn fido_dev_largeblob_get ,
|
|
.Fn fido_dev_largeblob_remove ,
|
|
.Fn fido_dev_largeblob_get_array ,
|
|
and
|
|
.Fn fido_dev_largeblob_set_array
|
|
return
|
|
.Dv FIDO_OK
|
|
on success.
|
|
On error, an error code defined in
|
|
.In fido/err.h
|
|
is returned.
|
|
.Sh SEE ALSO
|
|
.Xr fido_assert_largeblob_key_len 3 ,
|
|
.Xr fido_assert_largeblob_key_ptr 3 ,
|
|
.Xr fido_assert_set_extensions 3 ,
|
|
.Xr fido_cred_largeblob_key_len 3 ,
|
|
.Xr fido_cred_largeblob_key_ptr 3 ,
|
|
.Xr fido_cred_set_extensions 3 ,
|
|
.Xr fido_credman_get_dev_rk 3 ,
|
|
.Xr fido_credman_get_dev_rp 3 ,
|
|
.Xr fido_dev_get_assert 3 ,
|
|
.Xr fido_dev_make_cred 3
|
|
.Sh CAVEATS
|
|
The
|
|
.Dq largeBlobs
|
|
extension is not meant to be used to store sensitive data.
|
|
When retrieved, a credential's
|
|
.Dq largeBlobs
|
|
encryption key is transmitted in the clear, and an authenticator's
|
|
.Dq largeBlobs
|
|
CBOR array can be read without user interaction or verification.
|