=================================================================== RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/ssh/ssh-keygen.1,v retrieving revision 1.220 retrieving revision 1.221 diff -u -r1.220 -r1.221 --- src/usr.bin/ssh/ssh-keygen.1 2022/02/06 00:29:03 1.220 +++ src/usr.bin/ssh/ssh-keygen.1 2022/05/03 07:42:27 1.221 @@ -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 .\" Copyright (c) 1995 Tatu Ylonen , 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 @@ 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 @@ .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 @@ 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).