xref: /freebsd-src/contrib/libfido2/man/fido2-assert.1 (revision 60a517b66a69b8c011b04063ef63a938738719bd)

.\" Copyright (c) 2018-2023 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: July 3 2023 $
.Dt FIDO2-ASSERT 1
.Os
.Sh NAME
.Nm fido2-assert
.Nd get/verify a FIDO2 assertion
.Sh SYNOPSIS
.Nm
.Fl G
.Op Fl bdhpruvw
.Op Fl t Ar option
.Op Fl i Ar input_file
.Op Fl o Ar output_file
.Ar device
.Nm
.Fl V
.Op Fl dhpv
.Op Fl i Ar input_file
.Ar key_file
.Op Ar type
.Sh DESCRIPTION
.Nm
gets or verifies a FIDO2 assertion.
.Pp
The input of
.Nm
is defined by the parameters of the assertion to be obtained/verified.
See the
.Sx INPUT FORMAT
section for details.
.Pp
The output of
.Nm
is defined by the result of the selected operation.
See the
.Sx OUTPUT FORMAT
section for details.
.Pp
If an assertion is successfully obtained or verified,
.Nm
exits 0.
Otherwise,
.Nm
exits 1.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl G
Tells
.Nm
to obtain a new assertion from
.Ar device .
.It Fl V
Tells
.Nm
to verify an assertion using the PEM-encoded public key in
.Ar key_file
of type
.Ar type ,
where
.Ar type
may be
.Em es256
(denoting ECDSA over NIST P-256 with SHA-256),
.Em rs256
(denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or
.Em eddsa
(denoting EDDSA over Curve25519 with SHA-512).
If
.Ar type
is not specified,
.Em es256
is assumed.
.It Fl b
Request the credential's
.Dq largeBlobKey ,
a 32-byte symmetric key associated with the asserted credential.
.It Fl h
If obtaining an assertion, enable the FIDO2 hmac-secret
extension.
If verifying an assertion, check whether the extension data bit was
signed by the authenticator.
.It Fl d
Causes
.Nm
to emit debugging output on
.Em stderr .
.It Fl i Ar input_file
Tells
.Nm
to read the parameters of the assertion from
.Ar input_file
instead of
.Em stdin .
.It Fl o Ar output_file
Tells
.Nm
to write output on
.Ar output_file
instead of
.Em stdout .
.It Fl p
If obtaining an assertion, request user presence.
If verifying an assertion, check whether the user presence bit was
signed by the authenticator.
.It Fl r
Obtain an assertion using a resident credential.
If
.Fl r
is specified,
.Nm
will not expect a credential id in its input, and may output
multiple assertions.
Resident credentials are called
.Dq discoverable credentials
in CTAP 2.1.
.It Fl t Ar option
Toggles a key/value
.Ar option ,
where
.Ar option
is a string of the form
.Dq key=value .
The options supported at present are:
.Bl -tag -width Ds
.It Cm up Ns = Ns Ar true|false
Asks the authenticator for user presence to be enabled or disabled.
.It Cm uv Ns = Ns Ar true|false
Asks the authenticator for user verification to be enabled or
disabled.
.It Cm pin Ns = Ns Ar true|false
Tells
.Nm
whether to prompt for a PIN and request user verification.
.El
.Pp
The
.Fl t
option may be specified multiple times.
.It Fl u
Obtain an assertion using U2F.
By default,
.Nm
will use FIDO2 if supported by the authenticator, and fallback to
U2F otherwise.
.It Fl v
If obtaining an assertion, prompt the user for a PIN and request
user verification from the authenticator.
If verifying an assertion, check whether the user verification bit
was signed by the authenticator.
.It Fl w
Tells
.Nm
that the first line of input when obtaining an assertion shall be
interpreted as unhashed client data.
This is required by Windows Hello, which calculates the client data hash
internally.
.El
.Pp
If a
.Em tty
is available,
.Nm
will use it to obtain the PIN.
Otherwise,
.Em stdin
is used.
.Sh INPUT FORMAT
The input of
.Nm
consists of base64 blobs and UTF-8 strings separated
by newline characters ('\\n').
.Pp
When obtaining an assertion,
.Nm
expects its input to consist of:
.Pp
.Bl -enum -offset indent -compact
.It
client data hash (base64 blob);
.It
relying party id (UTF-8 string);
.It
credential id, if credential not resident (base64 blob);
.It
hmac salt, if the FIDO2 hmac-secret extension is enabled
(base64 blob);
.El
.Pp
When verifying an assertion,
.Nm
expects its input to consist of:
.Pp
.Bl -enum -offset indent -compact
.It
client data hash (base64 blob);
.It
relying party id (UTF-8 string);
.It
authenticator data (base64 blob);
.It
assertion signature (base64 blob);
.El
.Pp
UTF-8 strings passed to
.Nm
must not contain embedded newline or NUL characters.
.Sh OUTPUT FORMAT
The output of
.Nm
consists of base64 blobs and UTF-8 strings separated
by newline characters ('\\n').
.Pp
For each generated assertion,
.Nm
outputs:
.Pp
.Bl -enum -offset indent -compact
.It
client data hash (base64 blob);
.It
relying party id (UTF-8 string);
.It
authenticator data (base64 blob);
.It
assertion signature (base64 blob);
.It
user id, if credential resident (base64 blob);
.It
hmac secret, if the FIDO2 hmac-secret extension is enabled
(base64 blob);
.It
the credential's associated 32-byte symmetric key
.Pq Dq largeBlobKey ,
if requested (base64 blob).
.El
.Pp
When verifying an assertion,
.Nm
produces no output.
.Sh EXAMPLES
Assuming
.Pa cred
contains a
.Em es256
credential created according to the steps outlined in
.Xr fido2-cred 1 ,
obtain an assertion from an authenticator at
.Pa /dev/hidraw5
and verify it:
.Pp
.Dl $ echo assertion challenge | openssl sha256 -binary | base64 > assert_param
.Dl $ echo relying party >> assert_param
.Dl $ head -1 cred >> assert_param
.Dl $ tail -n +2 cred > pubkey
.Dl $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V pubkey es256
.Sh SEE ALSO
.Xr fido2-cred 1 ,
.Xr fido2-token 1