Adding upstream version 1.12.0.upstream/1.12.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 290 insertions, 0 deletions

diff --git a/man/fido2-cred.1 b/man/fido2-cred.1
new file mode 100644
index 0000000..bd82499
--- /dev/null
+++ b/man/fido2-cred.1
@@ -0,0 +1,290 @@
+.\" Copyright (c) 2018 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: 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.