mirror of
https://github.com/token2/fido2-manage.git
synced 2026-04-09 10:45:39 +00:00
Add files via upload
This commit is contained in:
Token2
GitHub
314
man/fido_assert_set_authdata.3
Normal file
314
man/fido_assert_set_authdata.3
Normal file
@@ -0,0 +1,314 @@
|
||||
.\" Copyright (c) 2018-2022 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: April 8 2023 $
|
||||
.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 ,
|
||||
.Nm fido_assert_set_winhello_appid
|
||||
.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"
|
||||
.Ft int
|
||||
.Fn fido_assert_set_winhello_appid "fido_assert_t *assert" "const char *id"
|
||||
.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.
|
||||
Note that the resulting hmac-secret varies according to whether
|
||||
user verification was performed by the authenticator.
|
||||
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
|
||||
The
|
||||
.Fn fido_assert_set_winhello_appid
|
||||
function sets the U2F application
|
||||
.Fa id
|
||||
.Pq Dq U2F AppID
|
||||
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.
|
||||
The
|
||||
.Fn fido_assert_set_winhello_appid
|
||||
function is a no-op unless
|
||||
.Fa assert
|
||||
is passed to
|
||||
.Xr fido_dev_get_assert 3
|
||||
with a device
|
||||
.Fa dev
|
||||
on which
|
||||
.Xr fido_dev_is_winhello 3
|
||||
holds true.
|
||||
In this case,
|
||||
.Em libfido2
|
||||
will instruct Windows Hello to try the assertion twice,
|
||||
first with the
|
||||
.Fa id
|
||||
passed to
|
||||
.Fn fido_assert_set_rp ,
|
||||
and a second time with the
|
||||
.Fa id
|
||||
passed to
|
||||
.Fn fido_assert_set_winhello_appid .
|
||||
If the second assertion succeeds,
|
||||
.Xr fido_assert_rp_id 3
|
||||
will point to the U2F AppID once
|
||||
.Xr fido_dev_get_assert 3
|
||||
completes.
|
||||
This mechanism exists in Windows Hello to ensure U2F backwards
|
||||
compatibility without the application inadvertently prompting the
|
||||
user twice.
|
||||
Note that
|
||||
.Fn fido_assert_set_winhello_appid
|
||||
is not needed on platforms offering CTAP primitives, since the
|
||||
authenticator can be silently probed for the existence of U2F
|
||||
credentials.
|
||||
.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 ,
|
||||
.Xr fido_dev_is_winhello 3
|
||||
Reference in New Issue
Block a user