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

[John Kehayias via Guix-patches via <guix-patches@gnu.org>]

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