Merge branch 'master' into staging

2 files changed, 92 insertions, 15 deletions

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index f371364746..af08d4ed54 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,65 @@ 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 U2F, Universal 2nd Factor
+@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, 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.
+
+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.  It is hoped the configuration can be useful for
+other security keys as well, with minor adjustments.
+
+@subsection Configuration for use as a two-factor authenticator (2FA)
+
+To be usable, the udev rules of the system should be extended with
+key-specific rules.  The following shows 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-logging in your graphical
+session so that the new group is in effect for your user, 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-factor authentication
+(2FA).
+
 @node Connecting to Wireguard VPN
 @section Connecting to Wireguard VPN
 
diff --git a/doc/guix.texi b/doc/guix.texi
index eaecfd0daa..e547d469f4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -60,7 +60,7 @@ Copyright @copyright{} 2018, 2021 Oleg Pykhalov@*
 Copyright @copyright{} 2018 Mike Gerwitz@*
 Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
 Copyright @copyright{} 2018, 2019 Gábor Boskovits@*
-Copyright @copyright{} 2018, 2019, 2020 Florian Pelz@*
+Copyright @copyright{} 2018, 2019, 2020, 2022 Florian Pelz@*
 Copyright @copyright{} 2018 Laura Lazzati@*
 Copyright @copyright{} 2018 Alex Vong@*
 Copyright @copyright{} 2019 Josh Holland@*
@@ -1409,7 +1409,7 @@ when transferring files to and from build machines.
 File name of the Unix-domain socket @command{guix-daemon} is listening
 to on that machine.
 
-@item @code{overload-threshold} (default: @code{0.6})
+@item @code{overload-threshold} (default: @code{0.8})
 The load threshold above which a potential offload machine is
 disregarded by the offload scheduler.  The value roughly translates to
 the total processor usage of the build machine, ranging from 0.0 (0%) to
@@ -3423,19 +3423,25 @@ The @var{options} can be among the following:
 @itemx -i @var{package} @dots{}
 Install the specified @var{package}s.
 
-Each @var{package} may specify either a simple package name, such as
-@code{guile}, or a package name followed by an at-sign and version number,
-such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter
-case, the newest version prefixed by @code{1.8} is selected).
+Each @var{package} may specify a simple package name, such as
+@code{guile}, optionally followed by an at-sign and version number,
+such as @code{guile@@3.0.7} or simply @code{guile@@3.0}.  In the latter
+case, the newest version prefixed by @code{3.0} is selected.
 
-If no version number is specified, the
-newest available version will be selected.  In addition, @var{package}
+If no version number is specified, the newest available version will be
+selected.  In addition, such a @var{package} specification
 may contain a colon, followed by the name of one of the outputs of the
 package, as in @code{gcc:doc} or @code{binutils@@2.22:lib}
-(@pxref{Packages with Multiple Outputs}).  Packages with a corresponding
+(@pxref{Packages with Multiple Outputs}).
+
+Packages with a corresponding
 name (and optionally version) are searched for among the GNU
 distribution modules (@pxref{Package Modules}).
 
+Alternatively, a @var{package} can directly specify a store file name
+such as @file{/gnu/store/...-guile-3.0.7}, as produced by, e.g.,
+@code{guix build}.
+
 @cindex propagated inputs
 Sometimes packages have @dfn{propagated inputs}: these are dependencies
 that automatically get installed along with the required package
@@ -4834,6 +4840,15 @@ invocation can be expensive: it may have to download or even build a
 large number of packages; the result is cached though and subsequent
 commands targeting the same commit are almost instantaneous.
 
+@quotation Note
+The history of Guix is immutable and @command{guix time-machine}
+provides the exact same software as they are in a specific Guix
+revision.  Naturally, no security fixes are provided for old versions
+of Guix or its channels.  A careless use of @command{guix time-machine}
+opens the door to security vulnerabilities.  @xref{Invoking guix pull,
+@option{--allow-downgrades}}.
+@end quotation
+
 The general syntax is:
 
 @example
@@ -8080,20 +8095,20 @@ following forms:
 @item (delete @var{name}@dots{})
 Delete from the inputs packages with the given @var{name}s (strings).
 
-@item (append @var{package}@dots{})
-Add @var{package}s to the end of the input list.
-
 @item (prepend @var{package}@dots{})
 Add @var{package}s to the front of the input list.
+
+@item (append @var{package}@dots{})
+Add @var{package}s to the end of the input list.
 @end table
 
 The example below removes the GMP and ACL inputs of Coreutils and adds
-libcap to the back of the input list:
+libcap to the front of the input list:
 
 @lisp
 (modify-inputs (package-inputs coreutils)
   (delete "gmp" "acl")
-  (append libcap))
+  (prepend libcap))
 @end lisp
 
 The example below replaces the @code{guile} package from the inputs of
@@ -8104,7 +8119,7 @@ The example below replaces the @code{guile} package from the inputs of
   (replace "guile" guile-2.2))
 @end lisp
 
-The last type of clause is @code{prepend}, to add inputs to the front of
+The last type of clause is @code{append}, to add inputs at the back of
 the list.
 @end deffn