On 2022-04-29 19:24 +01, Jason McIntyre <[email protected]> wrote:
> what we probably want is a simple overview of these devices in
> DESCRIPTION. but that's not simple. the page is already a bruiser. i
> mean, it discusses what constitues a good password/phrase! where to go
> from there?
>
> i note that the other components using -O have their own sections
> (CERTIFICATES/MODULE GENERATION). so what about this:
>
> - add a very small note to DESCRIPTION saying it can handle fido keys.
> that seems warranted anyway because they seem now fairly common and are
> somewhat different to traditional (software) keys.
>
> - move the -O stuff pertaining to fido keys to its own section.
>
> - tweak the new fido section to give a simple overview of these devices.
>
> i'm not able to offer a diff at this point, but maybe we could piece
> something together if you agree?
Sounds reasonable, this adds the FIDO section and moves the -O bits in.
The wording is inspired by / copied from the 8.2 release notes and the
CERTIFICATES section.
Maybe you have text for DESCRIPTION?
Not sure what to do about -K, maybe
see
.Sx FIDO
for details.
diff --git ssh-keygen.1 ssh-keygen.1
index 59b7f23a1fa..6dc71aa32bd 100644
--- ssh-keygen.1
+++ ssh-keygen.1
@@ -487,56 +487,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 token-backed keys, the options listed in the
+.Sx FIDO
+section may be specified.
.Pp
When performing signature-related options using the
.Fl Y
@@ -1060,6 +1013,75 @@ public key must be trusted by
or
.Xr ssh 1 .
Refer to those manual pages for details.
+.Sh FIDO
+.Nm
+is able to to generate FIDO token-backed keys, after which they may
+be used much like any other key type supported by OpenSSH, so long as
+the hardware token is attached when the keys are used.
+FIDO tokens 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 token and that cannot be exported from the token
+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 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 handle should be stored on the FIDO authenticator itself.
+This makes it easier to use the token on multiple computers.
+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 .
+Storing both parts of a key on a FIDO token increases the likelihood
+of an attacker being able to use a stolen token 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 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
.Sh KEY REVOCATION LISTS
.Nm
is able to manage OpenSSH format Key Revocation Lists (KRLs).
--
I'm not entirely sure you are real.
