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. >
