FIDO2-ASSERT(1)

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

# NAME

`fido2-assert` —
get/verify a FIDO 2 assertion

# SYNOPSIS

`fido2-assert` | `-G` [`-dhpruv`] [`-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 FIDO 2 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.
`-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.
`-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);

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)

November 5, 2019 | Yubico AB