3e696dfb70
Some highlights from NEWS:
** bio: fix CTAP2 canonical CBOR encoding in fido_bio_dev_enroll_*();
gh#480.
** New API calls:
- fido_dev_info_set;
- fido_dev_io_handle;
- fido_dev_new_with_info;
- fido_dev_open_with_info.
** Documentation and reliability fixes.
** Support for TPM 2.0 attestation of COSE_ES256 credentials.
Relnotes: Yes
Sponsored by: The FreeBSD Foundation
268 lines
5.3 KiB
Groff
268 lines
5.3 KiB
Groff
.\" 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 FIDO2 credential
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Fl M
|
|
.Op Fl bdhqruv
|
|
.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.
|
|
.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.
|