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
286
man/fido2-assert.1
Normal file
286
man/fido2-assert.1
Normal file
@@ -0,0 +1,286 @@
|
||||
.\" 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
|
||||
Reference in New Issue
Block a user