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

NAME
     fido2-cred - make/verify a FIDO2 credential

SYNOPSIS
     fido2-cred -M [-bdhqruvw] [-c cred_protect] [-i input_file]
                [-o output_file] device [type]
     fido2-cred -V [-dhv] [-c cred_protect] [-i input_file] [-o output_file]
                [type]

DESCRIPTION
     fido2-cred makes or verifies a FIDO2 credential.

     A credential 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.

     When making a credential, the authenticator may require the user to
     authenticate with a PIN.  If the -q option is not specified, fido2-cred
     will prompt the user for the PIN.  If a tty is available, fido2-cred will
     use it to obtain the PIN.  Otherwise, stdin is used.

     The input of fido2-cred is defined by the parameters of the credential to
     be made/verified.  See the INPUT FORMAT section for details.

     The output of fido2-cred is defined by the result of the selected
     operation.  See the OUTPUT FORMAT section for details.

     If a credential is successfully created or verified, fido2-cred exits 0.
     Otherwise, fido2-cred exits 1.

     The options are as follows:

     -M      Tells fido2-cred to make a new credential on device.

     -V      Tells fido2-cred to verify a credential.

     -b      Request the credential's "largeBlobKey", a 32-byte symmetric key
             associated with the generated credential.

     -c cred_protect
             If making a credential, set the credential's protection level to
             cred_protect, where cred_protect is the credential's protection
             level in decimal notation.  Please refer to <fido/param.h> for
             the set of possible values.  If verifying a credential, check
             whether the credential's protection level was signed by the
             authenticator as cred_protect.

     -d      Causes fido2-cred to emit debugging output on stderr.

     -h      If making a credential, enable the FIDO2 hmac-secret extension.
             If verifying a credential, check whether the extension data bit
             was signed by the authenticator.

     -i input_file
             Tells fido2-cred to read the parameters of the credential from
             input_file instead of stdin.

     -o output_file
             Tells fido2-cred to write output on output_file instead of
             stdout.

     -q      Tells fido2-cred to be quiet.  If a PIN is required and -q is
             specified, fido2-cred will fail.

     -r      Create a resident credential.  Resident credentials are called
             "discoverable credentials" in CTAP 2.1.

     -u      Create a U2F credential.  By default, fido2-cred will use FIDO2
             if supported by the authenticator, and fallback to U2F otherwise.

     -v      If making a credential, request user verification.  If verifying
             a credential, check whether the user verification bit was signed
             by the authenticator.

     -w      Tells fido2-cred that the first line of input when making a
             credential shall be interpreted as unhashed client data.  This is
             required by Windows Hello, which calculates the client data hash
             internally.

INPUT FORMAT
     The input of fido2-cred consists of base64 blobs and UTF-8 strings
     separated by newline characters ('\n').

     When making a credential, fido2-cred expects its input to consist of:

           1.   client data hash (base64 blob);
           2.   relying party id (UTF-8 string);
           3.   user name (UTF-8 string);
           4.   user id (base64 blob).

     When verifying a credential, fido2-cred expects its input to consist of:

           1.   client data hash (base64 blob);
           2.   relying party id (UTF-8 string);
           3.   credential format (UTF-8 string);
           4.   authenticator data (base64 blob);
           5.   credential id (base64 blob);
           6.   attestation signature (base64 blob);
           7.   attestation certificate (optional, base64 blob).

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

OUTPUT FORMAT
     The output of fido2-cred consists of base64 blobs, UTF-8 strings, and
     PEM-encoded public keys separated by newline characters ('\n').

     Upon the successful generation of a credential, fido2-cred outputs:

           1.   client data hash (base64 blob);
           2.   relying party id (UTF-8 string);
           3.   credential format (UTF-8 string);
           4.   authenticator data (base64 blob);
           5.   credential id (base64 blob);
           6.   attestation signature (base64 blob);
           7.   attestation certificate, if present (base64 blob).
           8.   the credential's associated 32-byte symmetric key
                ("largeBlobKey"), if present (base64 blob).

     Upon the successful verification of a credential, fido2-cred outputs:

           1.   credential id (base64 blob);
           2.   PEM-encoded credential key.

EXAMPLES
     Create a new es256 credential on /dev/hidraw5, verify it, and save the id
     and the public key of the credential in cred:

           $ echo credential challenge | openssl sha256 -binary | base64 >
           cred_param
           $ echo relying party >> cred_param
           $ echo user name >> cred_param
           $ dd if=/dev/urandom bs=1 count=32 | base64 >> cred_param
           $ fido2-cred -M -i cred_param /dev/hidraw5 | fido2-cred -V -o cred

SEE ALSO
     fido2-assert(1), fido2-token(1)

CAVEATS
     Please note that fido2-cred handles Basic Attestation and Self
     Attestation transparently.  In the case of Basic Attestation, the
     validity of the authenticator's attestation certificate is not verified.

Linux 6.7.4-arch1-1              July 3, 2023              Linux 6.7.4-arch1-1