3e696dfb70
Some highlights from NEWS: ** bio: fix CTAP2 canonical CBOR encoding in fido_bio_dev_enroll_*(); gh#480. ** New API calls: - fido_dev_info_set; - fido_dev_io_handle; - fido_dev_new_with_info; - fido_dev_open_with_info. ** Documentation and reliability fixes. ** Support for TPM 2.0 attestation of COSE_ES256 credentials. Relnotes: Yes Sponsored by: The FreeBSD Foundation
237 lines
5.6 KiB
Groff
237 lines
5.6 KiB
Groff
.\" Copyright (c) 2018 Yubico AB. All rights reserved.
|
|
.\" Use of this source code is governed by a BSD-style
|
|
.\" license that can be found in the LICENSE file.
|
|
.\"
|
|
.Dd $Mdocdate: May 23 2018 $
|
|
.Dt FIDO_ASSERT_SET_AUTHDATA 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm fido_assert_set_authdata ,
|
|
.Nm fido_assert_set_authdata_raw ,
|
|
.Nm fido_assert_set_clientdata ,
|
|
.Nm fido_assert_set_clientdata_hash ,
|
|
.Nm fido_assert_set_count ,
|
|
.Nm fido_assert_set_extensions ,
|
|
.Nm fido_assert_set_hmac_salt ,
|
|
.Nm fido_assert_set_hmac_secret ,
|
|
.Nm fido_assert_set_up ,
|
|
.Nm fido_assert_set_uv ,
|
|
.Nm fido_assert_set_rp ,
|
|
.Nm fido_assert_set_sig
|
|
.Nd set parameters of a FIDO2 assertion
|
|
.Sh SYNOPSIS
|
|
.In fido.h
|
|
.Bd -literal
|
|
typedef enum {
|
|
FIDO_OPT_OMIT = 0, /* use authenticator's default */
|
|
FIDO_OPT_FALSE, /* explicitly set option to false */
|
|
FIDO_OPT_TRUE, /* explicitly set option to true */
|
|
} fido_opt_t;
|
|
.Ed
|
|
.Ft int
|
|
.Fn fido_assert_set_authdata "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len"
|
|
.Ft int
|
|
.Fn fido_assert_set_authdata_raw "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len"
|
|
.Ft int
|
|
.Fn fido_assert_set_clientdata "fido_assert_t *assert" "const unsigned char *ptr" "size_t len"
|
|
.Ft int
|
|
.Fn fido_assert_set_clientdata_hash "fido_assert_t *assert" "const unsigned char *ptr" "size_t len"
|
|
.Ft int
|
|
.Fn fido_assert_set_count "fido_assert_t *assert" "size_t n"
|
|
.Ft int
|
|
.Fn fido_assert_set_extensions "fido_assert_t *assert" "int flags"
|
|
.Ft int
|
|
.Fn fido_assert_set_hmac_salt "fido_assert_t *assert" "const unsigned char *ptr" "size_t len"
|
|
.Ft int
|
|
.Fn fido_assert_set_hmac_secret "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len"
|
|
.Ft int
|
|
.Fn fido_assert_set_up "fido_assert_t *assert" "fido_opt_t up"
|
|
.Ft int
|
|
.Fn fido_assert_set_uv "fido_assert_t *assert" "fido_opt_t uv"
|
|
.Ft int
|
|
.Fn fido_assert_set_rp "fido_assert_t *assert" "const char *id"
|
|
.Ft int
|
|
.Fn fido_assert_set_sig "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
set of functions define the various parameters of a FIDO2
|
|
assertion, allowing a
|
|
.Fa fido_assert_t
|
|
type to be prepared for a subsequent call to
|
|
.Xr fido_dev_get_assert 3
|
|
or
|
|
.Xr fido_assert_verify 3 .
|
|
For the complete specification of a FIDO2 assertion and the format
|
|
of its constituent parts, please refer to the Web Authentication
|
|
(webauthn) standard.
|
|
.Pp
|
|
The
|
|
.Fn fido_assert_set_count
|
|
function sets the number of assertion statements in
|
|
.Fa assert
|
|
to
|
|
.Fa n .
|
|
.Pp
|
|
The
|
|
.Fn fido_assert_set_authdata
|
|
and
|
|
.Fn fido_assert_set_sig
|
|
functions set the authenticator data and signature parts of the
|
|
statement with index
|
|
.Fa idx
|
|
of
|
|
.Fa assert
|
|
to
|
|
.Fa ptr ,
|
|
where
|
|
.Fa ptr
|
|
points to
|
|
.Fa len
|
|
bytes.
|
|
A copy of
|
|
.Fa ptr
|
|
is made, and no references to the passed pointer are kept.
|
|
Please note that the first assertion statement of
|
|
.Fa assert
|
|
has an
|
|
.Fa idx
|
|
of
|
|
.Em 0 .
|
|
The authenticator data passed to
|
|
.Fn fido_assert_set_authdata
|
|
must be a CBOR-encoded byte string, as obtained from
|
|
.Fn fido_assert_authdata_ptr .
|
|
Alternatively, a raw binary blob may be passed to
|
|
.Fn fido_assert_set_authdata_raw .
|
|
.Pp
|
|
The
|
|
.Fn fido_assert_set_clientdata_hash
|
|
function sets the client data hash of
|
|
.Fa assert
|
|
to
|
|
.Fa ptr ,
|
|
where
|
|
.Fa ptr
|
|
points to
|
|
.Fa len
|
|
bytes.
|
|
A copy of
|
|
.Fa ptr
|
|
is made, and no references to the passed pointer are kept.
|
|
.Pp
|
|
The
|
|
.Fn fido_assert_set_clientdata
|
|
function allows an application to set the client data hash of
|
|
.Fa assert
|
|
by specifying the assertion's unhashed client data.
|
|
This is required by Windows Hello, which calculates the client data
|
|
hash internally.
|
|
For compatibility with Windows Hello, applications should use
|
|
.Fn fido_assert_set_clientdata
|
|
instead of
|
|
.Fn fido_assert_set_clientdata_hash .
|
|
.Pp
|
|
The
|
|
.Fn fido_assert_set_rp
|
|
function sets the relying party
|
|
.Fa id
|
|
of
|
|
.Fa assert ,
|
|
where
|
|
.Fa id
|
|
is a NUL-terminated UTF-8 string.
|
|
The content of
|
|
.Fa id
|
|
is copied, and no references to the passed pointer are kept.
|
|
.Pp
|
|
The
|
|
.Fn fido_assert_set_extensions
|
|
function sets the extensions of
|
|
.Fa assert
|
|
to the bitmask
|
|
.Fa flags .
|
|
At the moment, only the
|
|
.Dv FIDO_EXT_CRED_BLOB ,
|
|
.Dv FIDO_EXT_HMAC_SECRET ,
|
|
and
|
|
.Dv FIDO_EXT_LARGEBLOB_KEY
|
|
extensions are supported.
|
|
If
|
|
.Fa flags
|
|
is zero, the extensions of
|
|
.Fa assert
|
|
are cleared.
|
|
.Pp
|
|
The
|
|
.Fn fido_assert_set_hmac_salt
|
|
and
|
|
.Fn fido_assert_set_hmac_secret
|
|
functions set the hmac-salt and hmac-secret parts of
|
|
.Fa assert
|
|
to
|
|
.Fa ptr ,
|
|
where
|
|
.Fa ptr
|
|
points to
|
|
.Fa len
|
|
bytes.
|
|
A copy of
|
|
.Fa ptr
|
|
is made, and no references to the passed pointer are kept.
|
|
The HMAC Secret
|
|
.Pq hmac-secret
|
|
Extension is a CTAP 2.0 extension.
|
|
The
|
|
.Fn fido_assert_set_hmac_secret
|
|
function is normally only useful when writing tests.
|
|
.Pp
|
|
The
|
|
.Fn fido_assert_set_up
|
|
and
|
|
.Fn fido_assert_set_uv
|
|
functions set the
|
|
.Fa up
|
|
(user presence) and
|
|
.Fa uv
|
|
(user verification)
|
|
attributes of
|
|
.Fa assert .
|
|
Both are
|
|
.Dv FIDO_OPT_OMIT
|
|
by default, allowing the authenticator to use its default settings.
|
|
.Pp
|
|
Use of the
|
|
.Nm
|
|
set of functions may happen in two distinct situations:
|
|
when asking a FIDO2 device to produce a series of assertion
|
|
statements, prior to
|
|
.Xr fido_dev_get_assert 3
|
|
(i.e, in the context of a FIDO2 client), or when verifying assertion
|
|
statements using
|
|
.Xr fido_assert_verify 3
|
|
(i.e, in the context of a FIDO2 server).
|
|
.Pp
|
|
For a complete description of the generation of a FIDO2 assertion
|
|
and its verification, please refer to the FIDO2 specification.
|
|
An example of how to use the
|
|
.Nm
|
|
set of functions can be found in the
|
|
.Pa examples/assert.c
|
|
file shipped with
|
|
.Em libfido2 .
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Nm
|
|
functions return
|
|
.Dv FIDO_OK
|
|
on success.
|
|
The error codes returned by the
|
|
.Nm
|
|
set of functions are defined in
|
|
.In fido/err.h .
|
|
.Sh SEE ALSO
|
|
.Xr fido_assert_allow_cred 3 ,
|
|
.Xr fido_assert_verify 3 ,
|
|
.Xr fido_dev_get_assert 3
|