On Sun, May 01, 2022 at 03:26:55PM +0200, Florian Obser wrote: > On 2022-05-01 14:43 +02, Christian Weisgerber <[email protected]> wrote: > > Florian Obser: > > > >> 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. > > > > I think that makes sense. > > > > s/token/authenticator/g > > > > We standardized on "FIDO authenticator" some time ago, because > > "token" is already used for % expansion, and "security key" was > > confusing. "Authenticator" is also the official term used in the > > FIDO standard. > > > > ... I see some instances of "FIDO token" already slipped in over > > the last months, but that needs to be fixed. > > fixed > > I'm also using > > .Sh FIDO AUTHENTICATOR > > > > >> Maybe you have text for DESCRIPTION? > >> Not sure what to do about -K, maybe > >> see > >> .Sx FIDO > >> for details. > > > > "... for more information."? > > I went with > > See the > .Sx FIDO AUTHENTICATOR > section for more information. > > because I noticed that's used already in the document for other > sections. >
hi. reads pretty good now. jmc > diff --git ssh-keygen.1 ssh-keygen.1 > index 59b7f23a1fa..4d83e8f085e 100644 > --- ssh-keygen.1 > +++ ssh-keygen.1 > @@ -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). > > > > -- > I'm not entirely sure you are real. >
