03/66: ccs-2021: Tweak main sections.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository maintenance.

commit 188700aee5208e4136c7fdb0f91df95cac4850b8
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Fri Apr 30 10:46:14 2021 +0200

    ccs-2021: Tweak main sections.
---
 doc/ccs-2021/supply-chain.skb | 166 +++++++++++++++++++++++++++++-------------
 1 file changed, 115 insertions(+), 51 deletions(-)

diff --git a/doc/ccs-2021/supply-chain.skb b/doc/ccs-2021/supply-chain.skb
index 5827d42..a4f2fa7 100644
--- a/doc/ccs-2021/supply-chain.skb
+++ b/doc/ccs-2021/supply-chain.skb
@@ -338,16 +338,30 @@ fetched were pushed by authorized developers of the 
project.  We are
 really looking at individual commits, not tags, because users can choose
 to pull arbitrary points in the commit history of Guix and third-party
 channels.])
-
-      (p [Checkout authentication requires cryptographically signed
-commits,(footnote
-[https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work]).  By
-signing a commit, a Guix developer asserts that they are the one who
-made the commit; they may be its author, or they may be the person who
-applied somebody else’s changes after review.  It also requires a notion
-of authorization: we don’t simply want commits to have a valid
-signature, we want them to be signed by an authorized key.  The set of
-authorized keys changes over time as people join and leave the project.])
+      
+      (p [Git is an append-only, content-addressed version control
+system.  Revision history in Git is represented by a graph of commit
+objects: each commit can have zero or more parent commits.  In the
+common case, there is a single parent commit pointing to the previous
+revision; “merge commits”, which are created by merging the history of
+two development branches, have two parent commits.  “Append-only” means
+that we only ever ,(emph [add]) new commits to the graph.
+“Content-addressed” corresponds to the fact that commits are referred to
+by their cryptographic content hash (SHA-1); the contents of a revision,
+,(it [trees]) in Git parlance, as well as all other kind of data stored
+in a Git repository, are all content-addressed.])
+
+      (p [Git supports ,(emph [signed commits]),(footnote
+[https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work]).  A signed
+commit includes an additional header containing as ASCII-armored OpenPGP
+signature computer over the other headers of the commit.  Checkout
+authentication requires cryptographically signed commits.  By signing a
+commit, a Guix developer asserts that they are the one who made the
+commit; they may be its author, or they may be the person who applied
+somebody else’s changes after review.  It also requires a notion of
+authorization: we don’t simply want commits to have a valid signature,
+we want them to be signed by an authorized key.  The set of authorized
+keys changes over time as people join and leave the project.])
 
       (p [To implement that, we came up with the following mechanism and rule:
 
@@ -358,21 +372,39 @@ authorized keys changes over time as people join and 
leave the project.])
     (item [A commit is considered authentic if and only if it is signed by one
      of the keys listed in the ,(tt [.guix-authorizations]) file of each of
      its parents.  This is the ,(emph [authorization invariant]).]))
-
-(Remember that Git commits form a directed acyclic graph (DAG) where
-each commit can have zero or more parents; merge commits have two parent
-commits, for instance.  Do not miss _Git for Computer
-Scientists_,(footnote 
[https://eagain.net/articles/git-for-computer-scientists/])
-for a pedagogical overview!)])
+     
+The ,(tt [.guix-authorizations]) format is a Lisp-style s-expression (or
+“sexp”), as shown in ,(numref :text [Figure] :ident
+"fig-guix-authorizations").  Besides being a natural choice for Guix,
+which is implemented in Scheme, a language of the Lisp family, such a
+structured format leaves room for extensions, such as per-file
+authorizations.])
+
+     (figure
+       :legend [Example ,(tt [.guix-authorizations]) file listing
+       authorized committers.]
+       :ident "fig-guix-authorizations"
+       
+       (prog :line #f
+          (source :language scheme [
+(authorizations
+  (version 0)               ;current file format version
+
+  (("AD17 A21E F8AE D8F1 CC02  DBD9 F8AE D8F1 765C 61E3"
+    (name "alice"))
+   ("2A39 3FFF 68F4 EF7A 3D29  12AF 68F4 EF7A 22FB B2D5"
+    (name "bob"))
+   ("CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"
+    (name "charlie"))))])))
 
       (figure
         :legend [Graph of commits and the associated authorizations.]
         :ident "fig-commits"
         (image :file "images/commit-graph.pdf"))
 
-      (p [Let’s take an example to illustrate.  In ,(numref :text
-[Figure] :ident "fig-commits"), each box is a commit, and each arrow is
-a parent relationship.])
+      (p [Let’s take an example to illustrate the authorization
+invariant.  In ,(numref :text [Figure] :ident "fig-commits"), each box
+is a commit, and each arrow is a parent relationship.])
 
       (p [This figure shows two lines of development: the orange line may be 
the
 main development branch, while the purple line may correspond to a
@@ -414,21 +446,23 @@ Revocation is similar: any authorized committer can 
remove entries from
 committer can remove their former key and add their new key in a single
 commit, signed by the former key.])
 
-      (p [The authorization invariant satisfies our needs for Guix.  It
-has one downside: it prevents pull-request-style workflows.  Indeed,
-merging the branch of a contributor not listed in ,(tt [.guix-authorizations])
-would break the authorization invariant.  It’s a good tradeoff for Guix
-because our workflow relies on patches carved into stone tablets
-,(footnote [https://lwn.net/Articles/702177/]) (patch tracker,(footnote
-[https://issues.guix.gnu.org/])), but it’s not suitable for every
-project out there.]))
+      (p [The authorization invariant satisfies the needs of the Guix
+project.  It has one downside: it prevents pull-request-style workflows.
+Indeed, merging the branch of a contributor not listed in ,(tt
+[.guix-authorizations]) would break the authorization invariant, unless
+the committer who accepts the changes signs them, which involves
+rewriting the commit history of the branch that was submitted.  It is a
+good tradeoff for Guix where the contribution workflow relies on patches
+sent by email to patch tracker, and where commits are signed by the
+committer rather than the original author, but it may be less suitable
+for other workflows.]))
    
    (chapter :title [Bootstrapping] :ident "bootstrapping"
       
-      (p [The attentive reader may have noticed that something’s missing
-from the explanation above: what do we do about commit ,(it [A]) in the
-example above?  In other words, which commit do we pick as the first one
-where we can start verifying the authorization invariant?])
+      (p [You may have noticed that something is missing from the
+explanation above: what do we do about commit ,(it [A]) in the example
+above?  In other words, which commit do we pick as the first one where
+we can start verifying the authorization invariant?])
 
       (figure
         :legend [The introductory commit in a graph.]
@@ -515,9 +549,9 @@ strictly related to the authentication issue we’ve been 
discussing,
 except that it’s another important issue in this area that we took the
 opportunity to address.])
 
-      (p [Guix saves provenance info for itself: ,(tt [guix describe]) prints 
that
-information, essentially the Git commits of the channels used during
-,(tt [git pull]):]
+      (p [Guix saves provenance info for itself: the ,(tt [guix
+describe]) command prints that information, essentially the Git commits
+of the channels used during ,(tt [git pull]):]
 
      (prog :class "small" :line #f [
 $ guix describe
@@ -536,15 +570,44 @@ is a descendant of the current commit.  Going back to the 
figure above,
 going from commit ,(it [A]) to commit ,(it [F]) is a fast-forward update, but 
going
 from ,(it [F]) to ,(it [A]) or from ,(it [D]) to ,(it [E]) is not.])
 
-      (p [Not doing a fast-forward update would mean that the user is 
deploying an
-older version of the Guix currently used, or deploying an unrelated
-version from another branch.  In both cases, the user is at risk of
-ending up installing older, vulnerable software.])
-
-      (p [By default ,(tt [guix pull]) now errors out on non-fast-forward 
updates,
-thereby protecting from roll-backs.  Users who understand the
-risks can override that by passing
-,(tt [--allow-downgrades]).]))
+      (p [Not doing a fast-forward update would mean that the user is
+deploying an older version of the Guix currently used, or deploying an
+unrelated version from another branch.  In both cases, the user is at
+risk of ending up installing older, vulnerable software.  By default
+,(tt [guix pull]) errors out on non-fast-forward updates, thereby
+protecting from roll-backs.  Users who understand the risks can override
+that by passing ,(tt [--allow-downgrades]).])
+
+      (p [Downgrade prevention has been extended to system deployment.
+When deploying a system with ,(tt [guix system reconfigure]) or a fleet
+or systems with ,(tt [guix deploy]), the currently used channels are
+recorded in the deployed system, as can be seen by running ,(tt [guix
+system describe]):]
+       
+       (prog :class "small" :line #f [
+$ guix system describe
+Generation 161 Apr 27 2021 22:04:13    (current)
+  file name: /var/guix/profiles/system-161-link
+  canonical file name: /gnu/store/dyx1j…-system
+  label: GNU with Linux-Libre 5.11.16
+  bootloader: grub-efi
+  root device: label: "root"
+  kernel: /gnu/store/k029d…-linux-libre-5.11.16/bzImage
+  channels:
+    guix:
+      repository URL: https://git.savannah.gnu.org/git/guix.git
+      branch: master
+      commit: d904abe0768293b2322dbf355b6e41d94e769d78
+  configuration file: /gnu/store/m8rql…-configuration.scm
+])
+       
+       [This is useful information for users who wish to map a deployed
+system back to its source code.  We take advantage of that information
+to implement ,(emph [system downgrade prevention]): like ,(tt [guix
+pull]), deploying a system with ,(tt [guix system reconfigure]) or ,(tt
+[guix deploy]) now fails with an error when attempting a
+non-fast-forward update.  To our knowledge, this is the first time
+downgrade prevention is implemented at this level.]))
    
    (chapter :title [Mirrors and the risk of staleness]
       :ident "mirrors"
@@ -563,7 +626,7 @@ or if it’s not a genuine mirror, ,(tt [guix pull]) will 
abort.  In other
 cases, it will proceed.])
 
       (p [Unfortunately, there is no way to answer the general question
-“,(it [is]) X ,(it [the latest commit of branch]) B ,(it [?])”.
+“,(it [is]) X ,(it [the latest commit of branch]) B,(it [?])”.
 Rollback detection prevents just that, rollbacks, but there is no
 mechanism in place to tell whether a given mirror is stale.  To mitigate
 that, channel authors can specify, in the repository, the channel’s
@@ -612,8 +675,8 @@ with OpenPGP keys and signatures, although complex, are also
 well-documented.])
         
         (p [Key distribution is an important issue.  We did not want
-the whole mechanism to lazily fetch keys (,(it [certificates]) in
-OpenPGP parlance) from key servers: this was bound to be unreliable and
+the whole mechanism to lazily fetch public keys from key servers:
+this was bound to be unreliable and
 slow.  We instead chose to store keys inside the repository, as plain
 binary or ASCII-armored OpenPGP packets.  Our recommendation is to keep
 them in a dedicated branch to avoid cluttering regular branches (channel
@@ -745,11 +808,12 @@ on by server administrators.  The service periodically 
pulls and
 reconfigures the system.  With the guarantees Guix provides, the worst
 that can happen is that an upgrade does not take place.])
         
-        (p [Generalized authentication support offered by ,(tt [guix
-git authenticate]) has allowed Guix developers to use authentication
-support on a few repositories beside Guix and Guix channels.  We have
-yet to see broader adoption but we reckon that simplifying the interface
-may be a precondition, as explained above.])))
+        (p [Since it became available, authors of Guix channels have
+been adopting authentication support without hassle.  Generalized
+authentication support offered by ,(tt [guix git authenticate]) has seen
+use in a few repositories beside Guix channels.  We have yet to see
+broader adoption but we reckon that simplifying the interface may be a
+precondition, as explained above.])))
    
    (chapter :title [Notes on SHA-1] :ident "sha1"