path: root/man/fido2-cred.1

.\" Copyright (c) 2018 Yubico AB. All rights reserved.
.\" Use of this source code is governed by a BSD-style
.\" license that can be found in the LICENSE file.
.\"
.Dd $Mdocdate: November 5 2019 $
.Dt FIDO2-CRED 1
.Os
.Sh NAME
.Nm fido2-cred
.Nd make/verify a FIDO 2 credential
.Sh SYNOPSIS
.Nm
.Fl M
.Op Fl dhqruv
.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 FIDO 2 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 c Ar cred_protect
If making a credential, set the credential's protection level to
.Ar cred_protect .
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.
.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.
.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).
.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.