diff mbox series

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

Message ID 20221121200256.2680-1-maxim.cournoyer@gmail.com
State New
Headers show
Series [bug#59454] doc: Add a security keys section to the cookbook. | expand

Commit Message

Maxim Cournoyer Nov. 21, 2022, 8:02 p.m. UTC
* doc/guix-cookbook.texi (Top): Register new menu.
(System Configuration): Likewise.
(Using security keys): New section.
---
 doc/guix-cookbook.texi | 59 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)


base-commit: fe3be8d5e04804dadd84c7a909e1f85fe52080f3

Comments

zimoun Nov. 22, 2022, 3:44 p.m. UTC | #1
Hi,

On Mon, 21 Nov 2022 at 15:02, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
> * doc/guix-cookbook.texi (Top): Register new menu.
> (System Configuration): Likewise.
> (Using security keys): New section.
> ---
>  doc/guix-cookbook.texi | 59 ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 59 insertions(+)

Neat!  LGTM.

Cheers,
simon
John Kehayias Nov. 23, 2022, 4:11 a.m. UTC | #2
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
Maxim Cournoyer Nov. 25, 2022, 3:37 p.m. UTC | #3
Hi John,

John Kehayias <john.kehayias@protonmail.com> writes:

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

Thanks!

> 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 think it may well be required for some use cases; if you grep the
libfido2 package for "plugdev", you'll find plenty references in
the 70-u2f.rules file like:

--8<---------------cut here---------------start------------->8---
/gnu/store/vy2pry1q2b1hhibsq4qchnr0v2xyah0r-libfido2-1.12.0/lib/udev/rules.d/70-u2f.rules:226:KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="311f", ATTRS{idProduct}=="a6e9", TAG+="uaccess", GROUP="plugdev", MODE="0660"
--8<---------------cut here---------------end--------------->8---

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

I removed the door keys/locks example and rephrased it like:

--8<---------------cut here---------------start------------->8---
The use of security keys can improve your security by providing a second
authentication source that cannot be easily stolen or copied, at least
for a remote adversary (something that you have), to the main secret (a
passphrase -- something that you know), reducing the risk of
impersonation.
--8<---------------cut here---------------end--------------->8---

I hope that's a bit better.

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

I plugged that in the context indices: @cindex U2F, Universal 2nd Factor

>> +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?

I think we try to refrain from doing so indeed, although the cookbook
feels a lot less formal to me than the reference manual.  I've adjusted
to use 'It is hoped [...]'.

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

Oof, thanks for catching these.  I think it's fine to address the reader
as "you".

>> +@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 think so :-).

> 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?)

Yes.  I clarified this a bit.

>> +@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).

Problems with websites is that they typically use nonfree JavaScript.  I
don't know of a smaller local tool to demo security keys unfortunately;
it'd be nice to have one!

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

I'm not sure.  I feel the resetting of the key should only affect the
operation of Chromium rather than like erase your secrets off your key,
but don't take my word for it, it's just a guest.

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

Thanks a lot for going through it!  It sure came out better.

Now pushed!
diff mbox series

Patch

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index f371364746..7a7877bd00 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -21,6 +21,7 @@  Copyright @copyright{} 2020 Brice Waegeneire@*
 Copyright @copyright{} 2020 André Batista@*
 Copyright @copyright{} 2020 Christine Lemmer-Webber@*
 Copyright @copyright{} 2021 Joshua Branson@*
+Copyright @copyright{} 2022 Maxim Cournoyer*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -95,6 +96,7 @@  System Configuration
 * Auto-Login to a Specific TTY::    Automatically Login a User to a Specific TTY
 * Customizing the Kernel::          Creating and using a custom Linux kernel on Guix System.
 * Guix System Image API::           Customizing images to target specific platforms.
+* Using security keys::             How to use security keys with Guix System.
 * Connecting to Wireguard VPN::     Connecting to a Wireguard VPN.
 * Customizing a Window Manager::    Handle customization of a Window manager on Guix System.
 * Running Guix on a Linode Server:: Running Guix on a Linode Server.  Running Guix on a Linode Server
@@ -1380,6 +1382,7 @@  reference.
 * Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY
 * Customizing the Kernel::       Creating and using a custom Linux kernel on Guix System.
 * Guix System Image API::        Customizing images to target specific platforms.
+* Using security keys::          How to use security keys with Guix System.
 * Connecting to Wireguard VPN::  Connecting to a Wireguard VPN.
 * Customizing a Window Manager:: Handle customization of a Window manager on Guix System.
 * Running Guix on a Linode Server:: Running Guix on a Linode Server
@@ -1883,6 +1886,62 @@  guix system image --image-type=hurd-qcow2 my-hurd-os.scm
 
 will instead produce a Hurd QEMU image.
 
+@node Using security keys
+@section Using security keys
+@cindex 2FA, two-factor authentication
+@cindex security key, configuration
+
+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.
+
+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.
+
+@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:
+
+@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:
+
+@example
+guix shell ungoogled-chromium -- chromium chrome://settings/securityKeys
+@end example
+
+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).
+
 @node Connecting to Wireguard VPN
 @section Connecting to Wireguard VPN