fido2-assert(1)

FIDO2-ASSERT(1) General Commands Manual FIDO2-ASSERT(1)

NAME

fido2-assert — get/verify a FIDO2 assertion

SYNOPSIS

fido2-assert -G [-bdhpruv] [-t option] [-i input_file] [-o output_file] device
fido2-assert -V [-dhpv] [-i input_file] key_file [type]

DESCRIPTION

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), 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.

If a tty is available, fido2-assert will use it to obtain the PIN. Otherwise, stdin is used.

INPUT FORMAT

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:

1.

client data hash (base64 blob);

2.

relying party id (UTF-8 string);

3.

credential id, if credential not resident (base64 blob);

4.

hmac salt, if the FIDO2 hmac-secret extension is enabled (base64 blob);

When verifying an assertion, fido2-assert expects its input to consist of:

1.

client data hash (base64 blob);

2.

relying party id (UTF-8 string);

3.

authenticator data (base64 blob);

4.

assertion signature (base64 blob);

UTF-8 strings passed to fido2-assert must not contain embedded newline or NUL characters.

OUTPUT FORMAT

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:

1.

client data hash (base64 blob);

2.

relying party id (UTF-8 string);

3.

authenticator data (base64 blob);

4.

assertion signature (base64 blob);

5.

user id, if credential resident (base64 blob);

6.

hmac secret, if the FIDO2 hmac-secret extension is enabled (base64 blob);

7.

the credential’s associated 32-byte symmetric key (“largeBlobKey”), if requested (base64 blob).

When verifying an assertion, fido2-assert produces no output.

EXAMPLES

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

SEE ALSO

fido2-cred(1), fido2-token(1) GNU November 5, 2019 FIDO2-ASSERT(1)