NAME

     fido2-assert — get/verify a FIDO 2 assertion

SYNOPSIS

     fido2-assert -G [-dhpruv] [-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.

     -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 a tty is available, fido2-assert will use it to obtain
             the PIN.  Otherwise, stdin is used.  If verifying an assertion, check whether the
             user verification bit was signed by the authenticator.

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)