path: root/man/fido2-cred.1

.\" Copyright (c) 2018-2023 Yubico AB. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\"    1. Redistributions of source code must retain the above copyright
.\"       notice, this list of conditions and the following disclaimer.
.\"    2. Redistributions in binary form must reproduce the above copyright
.\"       notice, this list of conditions and the following disclaimer in
.\"       the documentation and/or other materials provided with the
.\"       distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.Dd $Mdocdate: July 3 2023 $
.Dt FIDO2-CRED 1
.Os
.Sh NAME
.Nm fido2-cred
.Nd make/verify a FIDO2 credential
.Sh SYNOPSIS
.Nm
.Fl M
.Op Fl bdhqruvw
.Op Fl c Ar cred_protect
.Op Fl i Ar input_file
.Op Fl o Ar output_file
.Ar device
.Op Ar type
.Nm
.Fl V
.Op Fl dhv
.Op Fl c Ar cred_protect
.Op Fl i Ar input_file
.Op Fl o Ar output_file
.Op Ar type
.Sh DESCRIPTION
.Nm
makes or verifies a FIDO2 credential.
.Pp
A credential
.Ar type
may be
.Em es256
(denoting ECDSA over NIST P-256 with SHA-256),
.Em rs256
(denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or
.Em eddsa
(denoting EDDSA over Curve25519 with SHA-512).
If
.Ar type
is not specified,
.Em es256
is assumed.
.Pp
When making a credential, the authenticator may require the user
to authenticate with a PIN.
If the
.Fl q
option is not specified,
.Nm
will prompt the user for the PIN.
If a
.Em tty
is available,
.Nm
will use it to obtain the PIN.
Otherwise,
.Em stdin
is used.
.Pp
The input of
.Nm
is defined by the parameters of the credential to be made/verified.
See the
.Sx INPUT FORMAT
section for details.
.Pp
The output of
.Nm
is defined by the result of the selected operation.
See the
.Sx OUTPUT FORMAT
section for details.
.Pp
If a credential is successfully created or verified,
.Nm
exits 0.
Otherwise,
.Nm
exits 1.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl M
Tells
.Nm
to make a new credential on
.Ar device .
.It Fl V
Tells
.Nm
to verify a credential.
.It Fl b
Request the credential's
.Dq largeBlobKey ,
a 32-byte symmetric key associated with the generated credential.
.It Fl c Ar cred_protect
If making a credential, set the credential's protection level to
.Ar cred_protect ,
where
.Ar cred_protect
is the credential's protection level in decimal notation.
Please refer to
.In 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
.Ar cred_protect .
.It Fl d
Causes
.Nm
to emit debugging output on
.Em stderr .
.It Fl 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.
.It Fl i Ar input_file
Tells
.Nm
to read the parameters of the credential from
.Ar input_file
instead of
.Em stdin .
.It Fl o Ar output_file
Tells
.Nm
to write output on
.Ar output_file
instead of
.Em stdout .
.It Fl q
Tells
.Nm
to be quiet.
If a PIN is required and
.Fl q
is specified,
.Nm
will fail.
.It Fl r
Create a resident credential.
Resident credentials are called
.Dq discoverable credentials
in CTAP 2.1.
.It Fl u
Create a U2F credential.
By default,
.Nm
will use FIDO2 if supported by the authenticator, and fallback to
U2F otherwise.
.It Fl v
If making a credential, request user verification.
If verifying a credential, check whether the user verification bit
was signed by the authenticator.
.It Fl w
Tells
.Nm
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.
.El
.Sh INPUT FORMAT
The input of
.Nm
consists of base64 blobs and UTF-8 strings separated
by newline characters ('\\n').
.Pp
When making a credential,
.Nm
expects its input to consist of:
.Pp
.Bl -enum -offset indent -compact
.It
client data hash (base64 blob);
.It
relying party id (UTF-8 string);
.It
user name (UTF-8 string);
.It
user id (base64 blob).
.El
.Pp
When verifying a credential,
.Nm
expects its input to consist of:
.Pp
.Bl -enum -offset indent -compact
.It
client data hash (base64 blob);
.It
relying party id (UTF-8 string);
.It
credential format (UTF-8 string);
.It
authenticator data (base64 blob);
.It
credential id (base64 blob);
.It
attestation signature (base64 blob);
.It
attestation certificate (optional, base64 blob).
.El
.Pp
UTF-8 strings passed to
.Nm
must not contain embedded newline or NUL characters.
.Sh OUTPUT FORMAT
The output of
.Nm
consists of base64 blobs, UTF-8 strings, and PEM-encoded public
keys separated by newline characters ('\\n').
.Pp
Upon the successful generation of a credential,
.Nm
outputs:
.Pp
.Bl -enum -offset indent -compact
.It
client data hash (base64 blob);
.It
relying party id (UTF-8 string);
.It
credential format (UTF-8 string);
.It
authenticator data (base64 blob);
.It
credential id (base64 blob);
.It
attestation signature (base64 blob);
.It
attestation certificate, if present (base64 blob).
.It
the credential's associated 32-byte symmetric key
.Pq Dq largeBlobKey ,
if present (base64 blob).
.El
.Pp
Upon the successful verification of a credential,
.Nm
outputs:
.Pp
.Bl -enum -offset indent -compact
.It
credential id (base64 blob);
.It
PEM-encoded credential key.
.El
.Sh EXAMPLES
Create a new
.Em es256
credential on
.Pa /dev/hidraw5 ,
verify it, and save the id and the public key of the credential in
.Em cred :
.Pp
.Dl $ echo credential challenge | openssl sha256 -binary | base64 > cred_param
.Dl $ echo relying party >> cred_param
.Dl $ echo user name >> cred_param
.Dl $ dd if=/dev/urandom bs=1 count=32 | base64 >> cred_param
.Dl $ fido2-cred -M -i cred_param /dev/hidraw5 | fido2-cred -V -o cred
.Sh SEE ALSO
.Xr fido2-assert 1 ,
.Xr fido2-token 1
.Sh CAVEATS
Please note that
.Nm
handles Basic Attestation and Self Attestation transparently.
In the case of Basic Attestation, the validity of the authenticator's
attestation certificate is
.Em not
verified.