[openssh-commits] [openssh] 02/06: upstream: Add FIDO AUTHENTICATOR section and explain a bit how FIDO

[git+noreply at mindrot.org]

This is an automated email from the git hooks/post-receive script.

djm pushed a commit to branch master
in repository openssh.

commit e5c036d2092c00bef395e9161dc5ce42d4be9565
Author: florian at openbsd.org <florian at openbsd.org>
Date:   Tue May 3 07:42:27 2022 +0000

    upstream: Add FIDO AUTHENTICATOR section and explain a bit how FIDO
    
    works. The wording came mostly from the 8.2 OpenSSH release notes, addapted
    to fit the man page. Then move the -O bits into the new section as is already
    done for CERTIFICATES and MODULI GENERATION. Finally we can explain the
    trade-offs of resident keys. While here, consistently refer to the FIDO
    thingies as "FIDO authenticators", not "FIDO tokens".
    
    input & OK jmc, naddy
    
    OpenBSD-Commit-ID: dd98748d7644df048f78dcf793b3b63db9ab1d25
---
 ssh-keygen.1 | 130 +++++++++++++++++++++++++++++++++++------------------------
 1 file changed, 78 insertions(+), 52 deletions(-)

diff --git a/ssh-keygen.1 b/ssh-keygen.1
index 59b7f23a..561600db 100644
--- a/ssh-keygen.1
+++ b/ssh-keygen.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ssh-keygen.1,v 1.220 2022/02/06 00:29:03 jsg Exp $
+.\"	$OpenBSD: ssh-keygen.1,v 1.221 2022/05/03 07:42:27 florian Exp $
 .\"
 .\" Author: Tatu Ylonen <ylo at cs.hut.fi>
 .\" Copyright (c) 1995 Tatu Ylonen <ylo at cs.hut.fi>, Espoo, Finland
@@ -35,7 +35,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: February 6 2022 $
+.Dd $Mdocdate: May 3 2022 $
 .Dt SSH-KEYGEN 1
 .Os
 .Sh NAME
@@ -396,6 +396,9 @@ Public and private key files will be written to the current directory for
 each downloaded key.
 If multiple FIDO authenticators are attached, keys will be downloaded from
 the first touched authenticator.
+See the
+.Sx FIDO AUTHENTICATOR
+section for more information.
 .It Fl k
 Generate a KRL file.
 In this mode,
@@ -487,56 +490,9 @@ listed in the
 .Sx MODULI GENERATION
 section may be specified.
 .Pp
-When generating a key that will be hosted on a FIDO authenticator,
-this flag may be used to specify key-specific options.
-Those supported at present are:
-.Bl -tag -width Ds
-.It Cm application
-Override the default FIDO application/origin string of
-.Dq ssh: .
-This may be useful when generating host or domain-specific resident keys.
-The specified application string must begin with
-.Dq ssh: .
-.It Cm challenge Ns = Ns Ar path
-Specifies a path to a challenge string that will be passed to the
-FIDO token during key generation.
-The challenge string may be used as part of an out-of-band
-protocol for key enrollment
-(a random challenge is used by default).
-.It Cm device
-Explicitly specify a
-.Xr fido 4
-device to use, rather than letting the token middleware select one.
-.It Cm no-touch-required
-Indicate that the generated private key should not require touch
-events (user presence) when making signatures.
-Note that
-.Xr sshd 8
-will refuse such signatures by default, unless overridden via
-an authorized_keys option.
-.It Cm resident
-Indicate that the key should be stored on the FIDO authenticator itself.
-Resident keys may be supported on FIDO2 tokens and typically require that
-a PIN be set on the token prior to generation.
-Resident keys may be loaded off the token using
-.Xr ssh-add 1 .
-.It Cm user
-A username to be associated with a resident key,
-overriding the empty default username.
-Specifying a username may be useful when generating multiple resident keys
-for the same application name.
-.It Cm verify-required
-Indicate that this private key should require user verification for
-each signature.
-Not all FIDO tokens support this option.
-Currently PIN authentication is the only supported verification method,
-but other methods may be supported in the future.
-.It Cm write-attestation Ns = Ns Ar path
-May be used at key generation time to record the attestation data
-returned from FIDO tokens during key generation.
-This information is potentially sensitive.
-By default, this information is discarded.
-.El
+When generating FIDO authenticator-backed keys, the options listed in the
+.Sx FIDO AUTHENTICATOR
+section may be specified.
 .Pp
 When performing signature-related options using the
 .Fl Y
@@ -1060,6 +1016,76 @@ public key must be trusted by
 or
 .Xr ssh 1 .
 Refer to those manual pages for details.
+.Sh FIDO AUTHENTICATOR
+.Nm
+is able to to generate FIDO authenticator-backed keys, after which
+they may be used much like any other key type supported by OpenSSH, so
+long as the hardware authenticator is attached when the keys are used.
+FIDO authenticators generally require the user to explicitly authorise
+operations by touching or tapping them.
+FIDO keys consist of two parts: a key handle part stored in the
+private key file on disk, and a per-device private key that is unique
+to each FIDO authenticator and that cannot be exported from the
+authenticator hardware.
+These are combined by the hardware at authentication time to derive
+the real key that is used to sign authentication challenges.
+Supported key types are
+.Cm ecdsa-sk
+and
+.Cm ed25519-sk .
+.Pp
+The options that are valid for FIDO keys are:
+.Bl -tag -width Ds
+.It Cm application
+Override the default FIDO application/origin string of
+.Dq ssh: .
+This may be useful when generating host or domain-specific resident keys.
+The specified application string must begin with
+.Dq ssh: .
+.It Cm challenge Ns = Ns Ar path
+Specifies a path to a challenge string that will be passed to the
+FIDO authenticator during key generation.
+The challenge string may be used as part of an out-of-band
+protocol for key enrollment
+(a random challenge is used by default).
+.It Cm device
+Explicitly specify a
+.Xr fido 4
+device to use, rather than letting the authenticator middleware select one.
+.It Cm no-touch-required
+Indicate that the generated private key should not require touch
+events (user presence) when making signatures.
+Note that
+.Xr sshd 8
+will refuse such signatures by default, unless overridden via
+an authorized_keys option.
+.It Cm resident
+Indicate that the key handle should be stored on the FIDO
+authenticator itself.
+This makes it easier to use the authenticator on multiple computers.
+Resident keys may be supported on FIDO2 authenticators and typically
+require that a PIN be set on the authenticator prior to generation.
+Resident keys may be loaded off the authenticator using
+.Xr ssh-add 1 .
+Storing both parts of a key on a FIDO authenticator increases the likelihood
+of an attacker being able to use a stolen authenticator device.
+.It Cm user
+A username to be associated with a resident key,
+overriding the empty default username.
+Specifying a username may be useful when generating multiple resident keys
+for the same application name.
+.It Cm verify-required
+Indicate that this private key should require user verification for
+each signature.
+Not all FIDO authenticators support this option.
+Currently PIN authentication is the only supported verification method,
+but other methods may be supported in the future.
+.It Cm write-attestation Ns = Ns Ar path
+May be used at key generation time to record the attestation data
+returned from FIDO authenticators during key generation.
+This information is potentially sensitive.
+By default, this information is discarded.
+.El
 .Sh KEY REVOCATION LISTS
 .Nm
 is able to manage OpenSSH format Key Revocation Lists (KRLs).

-- 
To stop receiving notification emails like this one, please contact
djm at mindrot.org.