fido2-assert —
get/verify a FIDO2 assertion
fido2-assert |
-G
[-bdhpruvw]
[-t
option]
[-i
input_file]
[-o
output_file]
device |
fido2-assert |
-V
[-dhpv]
[-i
input_file]
key_file
[type] |
fido2-assert gets or verifies a FIDO2 assertion.
The input of
fido2-assert is defined by the
parameters of the assertion to be obtained/verified. See the
INPUT FORMAT section for
details.
The output of
fido2-assert is defined by the result
of the selected operation. See the
OUTPUT FORMAT section for
details.
If an assertion is successfully obtained or verified,
fido2-assert exits 0. Otherwise,
fido2-assert exits 1.
The options are as follows:
-
-
- -G
- Tells fido2-assert to obtain a
new assertion from device.
-
-
- -V
- Tells fido2-assert to verify
an assertion using the PEM-encoded public key in
key_file of type
type, where
type may be
es256 (denoting ECDSA over NIST P-256 with
SHA-256), es384 (denoting ECDSA over NIST
P-384 with SHA-384), rs256 (denoting 2048-bit
RSA with PKCS#1.5 padding and SHA-256), or
eddsa (denoting EDDSA over Curve25519 with
SHA-512). If type is not specified,
es256 is assumed.
-
-
- -b
- Request the credential's “largeBlobKey”, a
32-byte symmetric key associated with the asserted credential.
-
-
- -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.
-
-
- -d
- Causes fido2-assert to emit
debugging output on stderr.
-
-
- -i
input_file
- Tells fido2-assert to read the
parameters of the assertion from
input_file instead of
stdin.
-
-
- -o
output_file
- Tells fido2-assert to write
output on output_file instead of
stdout.
-
-
- -p
- If obtaining an assertion, request user presence. If
verifying an assertion, check whether the user presence bit was signed by
the authenticator.
-
-
- -r
- Obtain an assertion using a resident credential. If
-r is specified,
fido2-assert will not expect a credential id
in its input, and may output multiple assertions. Resident credentials are
called “discoverable credentials” in CTAP 2.1.
-
-
- -t
option
- Toggles a key/value
option, where
option is a string of the form
“key=value”. The options supported at present are:
-
-
- up=true|false
- Asks the authenticator for user presence to be enabled
or disabled.
-
-
- uv=true|false
- Asks the authenticator for user verification to be
enabled or disabled.
-
-
- pin=true|false
- Tells fido2-assert whether
to prompt for a PIN and request user verification.
The -t option may be specified multiple
times.
-
-
- -u
- Obtain an assertion using U2F. By default,
fido2-assert will use FIDO2 if supported by
the authenticator, and fallback to U2F otherwise.
-
-
- -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.
-
-
- -w
- Tells fido2-assert 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.
If a
tty is available,
fido2-assert will use it to obtain the PIN.
Otherwise,
stdin is used.
The input of
fido2-assert consists of base64 blobs
and UTF-8 strings separated by newline characters ('\n').
When obtaining an assertion,
fido2-assert expects
its input to consist of:
- client data hash (base64 blob);
- relying party id (UTF-8 string);
- credential id, if credential not resident (base64
blob);
- hmac salt, if the FIDO2 hmac-secret extension is enabled
(base64 blob);
When verifying an assertion,
fido2-assert expects
its input to consist of:
- client data hash (base64 blob);
- relying party id (UTF-8 string);
- CBOR encoded authenticator data (base64 blob);
- assertion signature (base64 blob);
UTF-8 strings passed to
fido2-assert must not
contain embedded newline or NUL characters.
The output of
fido2-assert consists of base64 blobs
and UTF-8 strings separated by newline characters ('\n').
For each generated assertion,
fido2-assert outputs:
- client data hash (base64 blob);
- relying party id (UTF-8 string);
- CBOR encoded authenticator data (base64 blob);
- assertion signature (base64 blob);
- user id, if credential resident (base64 blob);
- hmac secret, if the FIDO2 hmac-secret extension is enabled
(base64 blob);
- the credential's associated 32-byte symmetric key
(“largeBlobKey”), if requested (base64 blob).
When verifying an assertion,
fido2-assert produces
no output.
Assuming
cred contains a
es256 credential created according to the steps
outlined in
fido2-cred(1),
obtain an assertion from an authenticator at
/dev/hidraw5 and verify it:
$ echo assertion challenge | openssl sha256
-binary | base64 > assert_param
$ echo relying party >>
assert_param
$ head -1 cred >>
assert_param
$ tail -n +2 cred > pubkey
$ fido2-assert -G -i assert_param /dev/hidraw5
| fido2-assert -V pubkey es256
fido2-cred(1),
fido2-token(1)