[bug#59454] [PATCH] doc: Add a security keys section to the cookbook.

[John Kehayias]

Hi Maxim,

Thanks for this addition, I think it will definitely be useful to many people. 
Overall it looks good, a few minor notes on the text after I add some of my 
confusion to the udev rules question.

For the udev rules, I tried without the plugdev group and it seemed like 
everything worked for me (though note I also use the pcscd service). In the 
past, I've had the plugdev group for the udev rules but not my user. I'm not 
sure why that is, perhaps the "uaccess" part of the rules? (I don't know much 
about this at all.) However, I did get system log messages "udevd[258]: 
specified group 'plugdev' unknown" which I'm guessing is due to me leaving that 
out of the udev rules service.

I'm not sure how we want to handle that in this documentation. I wouldn't be 
surprised if something does need the user to be in the plugdev group, I just 
haven't encountered it. Perhaps then keep it as is to be on the safe side since 
I can't think of a clear downside other than having one more group?

To add a little more confusion, on my Arch system I see no such udev rules. The 
only one I have for a Yubikey is from the equivalent of our 
yubikey-personalization package and which doesn't have any match for my 
particular Yubikey. But everything works there as well. Anyway, likely some 
other details there (some general rules for security keys?), just thought I'd 
mention that.

A few minor notes on the text now:

> +The use of security keys can improve your security by providing a second
> +authentication source that cannot be easily stolen or copied (similar to
> +the protection provided by mechanical keys for the door of your home or
> +apartment), which reduces the risk of impersonation.
> +

Not to get into the weeds here, but maybe we can use the "standard" this is the 
"something you have" part of multi-factor authentication (the "one you know" 
being a password, of course).

Also, should we use the keyword Universal 2nd Factor (U2F) standard somewhere? 
I believe this is the setup we need for that, but don't quote me on that.

> +The example configuration detailed below showcases what minimal
> +configuration needs to be made on your Guix System to allow the use of a
> +Yubico security key.  We hope the configuration can be useful for other
> +security keys as well, with minor adjustments.
> +

Super minor: do we use the "we" form much in the manual, at least in the system 
reference parts?

> +@subsection Configuration for use as a two-factor authenticator (2FA)
> +
> +Two be usable, the udev rules of the system should be extended with
> +key-specific rules.  The following show how to extend your udev rules
> +with the @file{lib/udev/rules.d/70-u2f.rules} udev rule file provided by
> +the @code{libfido2} package from the @code{(gnu packages
> +security-token)} module and add your user to the @samp{"plugdev"} group
> +it uses:
> +

Minor typos: "Two" -> "To", "show" -> "shows"; comment above for "you" here.

> +@lisp
> +(use-package-modules ... security-token ...)
> +...
> +(operating-system
> + ...
> + (users (cons* (user-account
> +               (name "your-user")
> +               (group "users")
> +               (supplementary-groups
> +             '("wheel" "netdev" "audio" "video"
> +                  "plugdev"))           ;<- added system group
> +               (home-directory "/home/your-user"))
> +              %base-user-accounts))
> + ...
> + (services
> +  (cons*
> +   ...
> +   (udev-rules-service 'fido2 libfido2 #:groups '("plugdev")))))
> +@end lisp
> +
> +After re-configuring your system and re-login to your graphical session,
> +you can verify that your key is usable by launching:
> +

Minor: "re-login" probably should be "re-logging in" maybe?

I'm guessing logging in again is needed due to the group change? (Otherwise we 
have the nice change you made so that udev rules get picked up automatically, 
right?)

> +@example
> +guix shell ungoogled-chromium -- chromium chrome://settings/securityKeys
> +@end example
> +

Perhaps a simple website for testing u2f that works in other browsers? Sorry, 
don't have any off the top of my head, just wondering (as I don't normally use 
chromium).

> +and validating that the security key can be reset via the ``Reset your
> +security key'' menu.  If it works, congratulations, your security key is
> +ready to be used with applications supporting two-factors authentication
> +(2FA).

Not familiar with the chromium settings here, is there something less 
potentially drastic to check? I didn't dare touch that as my security key is 
already set up (private keys backed up of course, but still).

Sorry for some of the more nitpick-y text things, probably reading and grading 
too many papers recently :) Overall will be a nice addition, thanks!

John