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

  • Done
  • quality assurance status badge
Details
4 participants
  • John Kehayias
  • Christopher Baines
  • Maxim Cournoyer
  • zimoun
Owner
unassigned
Submitted by
Maxim Cournoyer
Severity
normal
M
M
Maxim Cournoyer wrote on 21 Nov 2022 21:02
(address . guix-patches@gnu.org)(name . Maxim Cournoyer)(address . maxim.cournoyer@gmail.com)
20221121200256.2680-1-maxim.cournoyer@gmail.com
* 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(+)

Toggle diff (95 lines)
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

base-commit: fe3be8d5e04804dadd84c7a909e1f85fe52080f3
--
2.38.1
J
J
John Kehayias wrote on 23 Nov 2022 05:11
877czmfgy5.fsf@protonmail.com
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:

Toggle quote (6 lines)
> +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.

Toggle quote (6 lines)
> +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?

Toggle quote (10 lines)
> +@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.

Toggle quote (24 lines)
> +@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?)

Toggle quote (5 lines)
> +@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).

Toggle quote (5 lines)
> +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
C
C
Christopher Baines wrote on 23 Nov 2022 10:25
tag 59454 moreinfo
(address . control@debbugs.gnu.org)
87h6yq10qh.fsf@cbaines.net
tags 59454 + moreinfo
quit
Z
Z
zimoun wrote on 22 Nov 2022 16:44
Re: [bug#59454] [PATCH] doc: Add a security keys section to the cookbook.
(name . Maxim Cournoyer)(address . maxim.cournoyer@gmail.com)
86h6yrc7tn.fsf@gmail.com
Hi,

On Mon, 21 Nov 2022 at 15:02, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
Toggle quote (7 lines)
> * 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
M
M
Maxim Cournoyer wrote on 25 Nov 2022 16:37
Re: [PATCH] doc: Add a security keys section to the cookbook.
(name . John Kehayias)(address . john.kehayias@protonmail.com)(address . 59454-done@debbugs.gnu.org)
87lenzjba7.fsf@gmail.com
Hi John,

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

Toggle quote (6 lines)
> 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!

Toggle quote (9 lines)
> 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:

Toggle snippet (3 lines)
/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"

Toggle quote (12 lines)
> 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:

Toggle snippet (7 lines)
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.

I hope that's a bit better.

Toggle quote (4 lines)
> 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

Toggle quote (8 lines)
>> +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 [...]'.

Toggle quote (12 lines)
>> +@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".

Toggle quote (26 lines)
>> +@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 :-).

Toggle quote (4 lines)
> 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.

Toggle quote (9 lines)
>> +@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!

Toggle quote (9 lines)
>> +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.

Toggle quote (4 lines)
> 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!

--
Thanks,
Maxim
Closed
?
Your comment

This issue is archived.

To comment on this conversation send an email to 59454@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 59454
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch