Re: ssh-keygen(1): resident fido2 keys
On Sun, May 01, 2022 at 03:26:55PM +0200, Florian Obser wrote: > On 2022-05-01 14:43 +02, Christian Weisgerber 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
Re: ssh-keygen(1): resident fido2 keys
On 2022-05-01 14:43 +02, Christian Weisgerber 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. 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
Re: ssh-keygen(1): resident fido2 keys
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. > Maybe you have text for DESCRIPTION? > Not sure what to do about -K, maybe > see > .Sx FIDO > for details. "... for more information."? -- Christian "naddy" Weisgerber na...@mips.inka.de
Re: ssh-keygen(1): resident fido2 keys
On Sat, Apr 30, 2022 at 03:39:14PM +0200, Florian Obser wrote: > On 2022-04-29 19:24 +01, Jason McIntyre 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. > yep, that looks fine i think. > Maybe you have text for DESCRIPTION? after looking at your changes, i actually don;t think there is a need for that so much, so i'd forget my idea. > Not sure what to do about -K, maybe > see > .Sx FIDO > for details. > yes, something like that. so overall i think this diff is better. but it does expose at least one downside - it leaves the -O section with an isolated looking list of -Y options. i don;t see an easy way to avoid that and i suppose it's no biggie. also i'm unsure if "FIDO" is the ideal section name, and whether it's the correct term for all these keys. other parts of the text use "FIDO authenticators". maybe someone else can double check the terminology? anyway i'm ok with your changes. maybe let it sit a day in case one of the openssh people want to chip in. jmc > 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
Re: ssh-keygen(1): resident fido2 keys
On 2022-04-29 19:24 +01, Jason McIntyre 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
Re: ssh-keygen(1): resident fido2 keys
On Fri, Apr 29, 2022 at 04:46:23PM +0200, Florian Obser wrote: > So I got a yubikey and I wanted to try fido2 with ssh. I was a bit > unsure on how to generate a key (hint: it's just ssh-keygen -t > ed25519-sk). So I went and ask the Internet. I ran into some page that > suggested that you need to give a ton of options to ssh-keygen, > including -o resident without explaining why. Our man page confused me > even more: > > resident > Indicate that the key should be stored on the FIDO > authenticator itself. > > Well, that sounds reasonable, I mean, I got this thing to store my ssh > key. But hang on, why would I want a non-resident key? > > The 8.2 release notes provided the answer under the heading "FIDO2 > resident keys" (https://www.openssh.com/txt/release-8.2) > > I have used parts of the explanation and adjusted it a bit to make it > better fit the man page. > > It's a bit weird to explain how fido keys work in the middle of options > discussion, but I couldn't find a better spot. > > Thoughts? > hi. i do sympathize here. some of the concepts are a bit baffling. but i'm not convinced that this is the right way to do it. we already talk about resident keys, much earlier in the page (the -K option). and, as you say, it feels weird to shoehorn the explanation into the middle of that option section. the description of "resident" is clear enough if you understand how these things work (i don't, fully). so your text really adds some duplication. 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? jmc > diff --git ssh-keygen.1 ssh-keygen.1 > index 59b7f23a1fa..b333f740936 100644 > --- ssh-keygen.1 > +++ ssh-keygen.1 > @@ -516,6 +516,11 @@ 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. > +FIDO keys consist of two parts, a key handle part stored in the private key > +file on disk, and a per-token private key that cannot be exported from the > +token hardware. > +This stores the key handle on the token itself but increases the likelihood > of > +an attacker being able to use a stolen token device. > 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 > > > -- > I'm not entirely sure you are real. >
ssh-keygen(1): resident fido2 keys
So I got a yubikey and I wanted to try fido2 with ssh. I was a bit unsure on how to generate a key (hint: it's just ssh-keygen -t ed25519-sk). So I went and ask the Internet. I ran into some page that suggested that you need to give a ton of options to ssh-keygen, including -o resident without explaining why. Our man page confused me even more: resident Indicate that the key should be stored on the FIDO authenticator itself. Well, that sounds reasonable, I mean, I got this thing to store my ssh key. But hang on, why would I want a non-resident key? The 8.2 release notes provided the answer under the heading "FIDO2 resident keys" (https://www.openssh.com/txt/release-8.2) I have used parts of the explanation and adjusted it a bit to make it better fit the man page. It's a bit weird to explain how fido keys work in the middle of options discussion, but I couldn't find a better spot. Thoughts? diff --git ssh-keygen.1 ssh-keygen.1 index 59b7f23a1fa..b333f740936 100644 --- ssh-keygen.1 +++ ssh-keygen.1 @@ -516,6 +516,11 @@ 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. +FIDO keys consist of two parts, a key handle part stored in the private key +file on disk, and a per-token private key that cannot be exported from the +token hardware. +This stores the key handle on the token itself but increases the likelihood of +an attacker being able to use a stolen token device. 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 -- I'm not entirely sure you are real.
