Updated: 2025/Nov/16

Please read Privacy Policy. It's for your privacy.

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

NAME
     fido2-assert - get/verify a FIDO2 assertion

SYNOPSIS
     fido2-assert -G [-bdhpruvw] [-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), 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.

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.   CBOR encoded 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.   CBOR encoded 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)

NetBSD 11.99               $Mdocdate: July 3 2023 $               NetBSD 11.99