From efb5e833ba0450c5136e7a282c83789bd623afd1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= <ludo@gnu.org>
Date: Mon, 11 May 2015 22:59:29 +0200
Subject: [PATCH] doc: Document X.509 certificates.

* doc/guix.texi (Using the Configuration System): Add xref to "X.509
  Certificates".
  (X.509 Certificates): New section.
* gnu/system/examples/desktop.tmpl: Use NSS-CERTS.
---
 doc/guix.texi                    | 46 +++++++++++++++++++++++++++++++-
 gnu/system/examples/desktop.tmpl |  3 ++-
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 698b63fac5..137b39bed2 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -3998,6 +3998,7 @@ instance to support new system services.
 * Locales::                     Language and cultural convention settings.
 * Services::                    Specifying system services.
 * Setuid Programs::             Programs running with root privileges.
+* X.509 Certificates::          Authenticating HTTPS servers.
 * Name Service Switch::         Configuring libc's name service switch.
 * Initial RAM Disk::            Linux-Libre bootstrapping.
 * GRUB Configuration::          Configuring the boot loader.
@@ -4058,7 +4059,8 @@ more, would look like this:
 @end lisp
 
 @xref{Desktop Services}, for the exact list of services provided by
-@var{%desktop-services}.
+@var{%desktop-services}.  @xref{X.509 Certificates}, for background
+information about the @code{nss-certs} package that is used here.
 
 Assuming the above snippet is stored in the @file{my-system-config.scm}
 file, the @command{guix system reconfigure my-system-config.scm} command
@@ -5172,6 +5174,48 @@ Under the hood, the actual setuid programs are created in the
 files in this directory refer to the ``real'' binaries, which are in the
 store.
 
+@node X.509 Certificates
+@subsection X.509 Certificates
+
+@cindex HTTPS, certificates
+@cindex X.509 certificates
+@cindex TLS
+Web servers available over HTTPS (that is, HTTP over the transport-layer
+security mechanism, TLS) send client programs an @dfn{X.509 certificate}
+that the client can then use to @emph{authenticate} the server.  To do
+that, clients verify that the server's certificate is signed by a
+so-called @dfn{certificate authority} (CA).  But to verify the CA's
+signature, clients must have first acquired the CA's certificate.
+
+Web browsers such as GNU@tie{}IceCat include their own set of CA
+certificates, such that they are able to verify CA signatures
+out-of-the-box.
+
+However, most other programs that can talk HTTPS---@command{wget},
+@command{git}, @command{w3m}, etc.---need to be told where CA
+certificates can be found.
+
+@cindex @code{nss-certs}
+In GuixSD, this is done by adding a package that provides certificates
+to the @code{packages} field of the @code{operating-system} declaration
+(@pxref{operating-system Reference}).  GuixSD includes one such package,
+@code{nss-certs}, which is a set of CA certificates provided as part of
+Mozilla's Network Security Services.
+
+Note that it is @emph{not} part of @var{%base-packages}, so you need to
+explicitly add it.  The @file{/etc/ssl/certs} directory, which is where
+most applications and libraries look for certificates by default, points
+to the certificates installed globally.
+
+Unprivileged users can also install their own certificate package in
+their profile.  A number of environment variables need to be defined so
+that applications and libraries know where to find them.  Namely, the
+OpenSSL library honors the @code{SSL_CERT_DIR} and @code{SSL_CERT_FILE}
+variables.  Some applications add their own environment variables; for
+instance, the Git version control system honors the certificate bundle
+pointed to by the @code{GIT_SSL_CAINFO} environment variable.
+
+
 @node Name Service Switch
 @subsection Name Service Switch
 
diff --git a/gnu/system/examples/desktop.tmpl b/gnu/system/examples/desktop.tmpl
index 07e3f0b1d6..b2919f7221 100644
--- a/gnu/system/examples/desktop.tmpl
+++ b/gnu/system/examples/desktop.tmpl
@@ -3,7 +3,7 @@
 
 (use-modules (gnu) (gnu system nss))
 (use-service-modules desktop)
-(use-package-modules xfce ratpoison wicd avahi xorg)
+(use-package-modules xfce ratpoison wicd avahi xorg certs)
 
 (operating-system
   (host-name "antelope")
@@ -32,6 +32,7 @@
   ;; sessions using either of these at the log-in screen.
   (packages (cons* xfce ratpoison    ;desktop environments
                    xterm wicd avahi  ;useful tools
+                   nss-certs         ;for HTTPS access
                    %base-packages))
 
   ;; Use the "desktop" services, which include the X11