0afa8e065e
git-subtree-dir: contrib/libfido2 git-subtree-mainline: d586c978b9b4216869e589daa5bbcc33225a0e35 git-subtree-split: a58dee945a5da64d0e97f35a508928e0d17c9cc7
257 lines
5.1 KiB
Groff
257 lines
5.1 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: November 5 2019 $
|
|
.Dt FIDO2-ASSERT 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm fido2-assert
|
|
.Nd get/verify a FIDO 2 assertion
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Fl G
|
|
.Op Fl bdhpruv
|
|
.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 FIDO 2 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 FIDO 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.
|
|
.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
|