39/66: programming-2022: Add illustrations.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository maintenance.

commit f56ca7baf16a6501a975de1adf1db7f06bfe8fef
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Sat Jan 29 23:24:32 2022 +0100

    programming-2022: Add illustrations.
    
    * doc/programming-2022/images/github-verification-statuses.png,
    doc/programming-2022/images/guix-build-daemon.tex,
    doc/programming-2022/images/guix-package-workflow.tex: New files.
    * doc/programming-2022/security.sbib: Tweak "courant2022:ocamlboot".
    * doc/programming-2022/supply-chain.skb: Augment 'usepackage' custom.
    'image' width defaults to 1.0.
    (A Deployment Toolbox): Mention 'guix shell'.
    (Reproducible Builds): Add figure.
    (Rationale): Add figure.
    (Related Work): Add figure.
---
 .../images/github-verification-statuses.png        | Bin 0 -> 196137 bytes
 doc/programming-2022/images/guix-build-daemon.tex  |  45 ++++++++++++++++
 .../images/guix-package-workflow.tex               |  44 +++++++++++++++
 doc/programming-2022/security.sbib                 |   5 +-
 doc/programming-2022/supply-chain.skb              |  60 ++++++++++++++++++---
 5 files changed, 144 insertions(+), 10 deletions(-)

diff --git a/doc/programming-2022/images/github-verification-statuses.png 
b/doc/programming-2022/images/github-verification-statuses.png
new file mode 100644
index 0000000..4da9a73
Binary files /dev/null and 
b/doc/programming-2022/images/github-verification-statuses.png differ
diff --git a/doc/programming-2022/images/guix-build-daemon.tex 
b/doc/programming-2022/images/guix-build-daemon.tex
new file mode 100644
index 0000000..cc3ece6
--- /dev/null
+++ b/doc/programming-2022/images/guix-build-daemon.tex
@@ -0,0 +1,45 @@
+\begin{tikzpicture}[tools/.style = {
+                      text width=50mm, minimum height=10mm,
+                      text centered, draw=guixblue2, thick,
+                      rounded corners=2mm,
+                      fill=white, text=black
+                    },
+                    tool/.style = {
+                      fill=white, text=black, text width=3cm,
+                      text centered
+                    },
+                    daemon/.style = {
+                      rectangle, text width=50mm, text centered,
+                      rounded corners=2mm, minimum height=10mm,
+                      fill=guixorange1, text=black
+                    },
+                    builders/.style = {
+                      draw=guixorange1, very thick,
+                      fill=white, text=black, text width=5cm,
+                      rounded corners=2mm,
+                    },
+                    builder/.style = {
+                      draw=guixred2, thick, rectangle,
+                      fill=white, text=black,
+                      rotate=90
+                    }]
+  \matrix[row sep=3mm, column sep=3.4cm] {
+    \node(builders)[builders, text height=3.5cm]{}
+        node[fill=white, text=black] at (0, 1.3) {\textbf{build processes}}
+        node[fill=white, text=black] at (0, 0.9) {chroot, separate UIDs}
+        node[builder] at (-1,-0.5) {\texttt{make}, \texttt{gcc}, etc.}
+        node[builder] at ( 0,-0.5) {\texttt{make}, \texttt{gcc}, etc.}
+        node[builder] at ( 1,-0.5) {\texttt{make}, \texttt{gcc}, etc.}; &
+    \node(cli)[tools]{\texttt{guix} command};
+    \\
+
+    \node(daemon)[daemon]{\textbf{build daemon}}; &
+    &
+    \\
+  };
+
+  \path[very thick, draw=guixorange1]
+    (cli.south) edge [out=-90, in=0, ->] node[below, sloped]{RPCs} 
(daemon.east);
+  \path[->, very thick, draw=guixorange1]
+    (daemon) edge (builders);
+\end{tikzpicture}
diff --git a/doc/programming-2022/images/guix-package-workflow.tex 
b/doc/programming-2022/images/guix-package-workflow.tex
new file mode 100644
index 0000000..e214e50
--- /dev/null
+++ b/doc/programming-2022/images/guix-package-workflow.tex
@@ -0,0 +1,44 @@
+  \begin{tikzpicture}[box/.style = {
+                         rounded corners=2mm,
+                         fill=white, text=black, text width=4.8cm,
+                         inner sep=2mm
+                      },
+                      server/.style = {
+                         text centered, rounded corners=2mm,
+                         fill=guixorange1, text=black, text width=3.4cm,
+                         inner sep=3mm
+                      },
+                      note/.style = {
+                        rounded corners=4, text centered,
+                        fill=guixorange1, text width=5.5cm,
+                        inner sep=3mm, rotate=5, opacity=.75, text opacity=1,
+                        drop shadow={opacity=0.5}
+                      }]
+    \matrix[row sep=1.4cm, column sep=0.4cm] {
+      \node(def)[box]{\texttt{(define python (package \textrm{...}))}};
+      & & \node(user)[server]{user};
+      \\
+      \node(build)[box]{\texttt{guix build python}
+         \texttt{/gnu/store/\textrm{...}-python-3.9.6}};
+      & & \node(hydra)[server]{build~farm};
+      \\
+      & \node(savannah)[server, draw=guixblue2, thick]{\textbf{Git 
repository}}; &
+      \\
+    };
+
+    \path[->, very thick, draw=guixblue2]
+      (def) edge node[left]{test} (build);
+    \path[->, very thick, draw=guixblue2]
+      (build) edge[->, in=110, out=-70] node[above, sloped]{\texttt{git push}}
+      (savannah);
+    \path[<-, very thick, draw=guixblue2]
+      (hydra) edge[out=-90, in=0] node[right]{pull} (savannah.east);
+    \path[<-, very thick, draw=guixblue2]
+      (user.south west) edge[in=80, out=200] node[above, sloped]{\texttt{guix 
pull}}
+      (savannah);
+    \path[<-, very thick, dashed, draw=guixblue2]
+      (user) edge node[right]{get binaries} (hydra);
+
+    %% \node[note, rotate=3] at (2,1) {\Large{no ``maintainer uploads''}};
+    %% \node[note, rotate=-10] at (-2,-1) {\Large{no single point of trust}};
+  \end{tikzpicture}
diff --git a/doc/programming-2022/security.sbib 
b/doc/programming-2022/security.sbib
index 500966e..c5a18b6 100644
--- a/doc/programming-2022/security.sbib
+++ b/doc/programming-2022/security.sbib
@@ -339,8 +339,9 @@ Thayer")
 (article courant2022:ocamlboot
   (author "Nathanaëlle Courant, Julien Lepiller, Gabriel Scherer")
   (year "2022")
-  (title "Debootstrapping Without Archeology: Stacked Implementations in 
Camlboot")
-  (booktitle "Programming Journal")
+  (title "Debootstrapping Without Archeology: Stacked Implementations in
+  Camlboot (to appear)")
+  (journal "Programming Journal")
   (issue "3")
   (volume "6")
   (notes "to appear"))
diff --git a/doc/programming-2022/supply-chain.skb 
b/doc/programming-2022/supply-chain.skb
index 196b25a..fd36d75 100644
--- a/doc/programming-2022/supply-chain.skb
+++ b/doc/programming-2022/supply-chain.skb
@@ -10,7 +10,8 @@
             (skribilo biblio author)
             (skribilo source)
             (skribilo source lisp)
-            (skribilo source parameters))
+            (skribilo source parameters)
+            (rnrs io ports))
 
 (define (---) ; emdash
   (resolve (lambda (n e env)
@@ -66,6 +67,13 @@
                      ;; See 
<https://en.wikibooks.org/wiki/LaTeX/Labels_and_Cross-referencing>
                      ;; and 
<http://tug.org/pipermail/texhax/2010-September/015596.html>.
                      (string-append u "\n" 
+                                    "\\usepackage{tikz}\n"
+                                   "\\usetikzlibrary{arrows,shapes,shadows}\n"
+                                   
"\\definecolor{guixorange1}{RGB}{243,154,38}  % guixorange P\n"
+                                   "\\definecolor{guixblue2}{RGB}{10,50,80} % 
guixblue S\n"
+                                   "\\definecolor{guixred2}{RGB}{230,68,57}  % 
red S\n"
+                                   "\\definecolor{guixdarkgrey}{RGB}{46,47,55} 
% guixdarkgrey S\n"
+
                                    ;; Trick so that ‘…’ is properly
                                    ;; typeset inside teletype text.
                                    
"\\DeclareUnicodeCharacter{2026}{\\textrm{\\ldots}}\n"
@@ -104,7 +112,7 @@
      :options '(:file :url :width :height :zoom)
      :action (lambda (n e)
               (format #t "\n\\includegraphics[width=~a\\textwidth]{~a}\n"
-                      (or (markup-option n :width) 0.5)
+                      (or (markup-option n :width) 1.0)
                       (markup-option n :file))))
 
 
@@ -331,7 +339,9 @@ user-land software they need, down to the C library; this 
guarantees
 they behave the same on any system.])
 
         (p [There are other tools beyond the “package manager”
-interface.  The ,(tt [guix pack]) command, for example, creates
+interface.  The ,(tt [guix shell]) command, for example, creates a
+one-off development environment containing the given packages.
+The ,(tt [guix pack]) command creates
 standalone ,(emph [application bundles]) or ,(emph [container images])
 providing one or more software packages and all the packages they depend
 on at run time.  The container images can be loaded by Docker, podman,
@@ -388,10 +398,24 @@ specifically for substitutes for ,(tt
 desired build output.  Substitutes are cryptographically signed by the
 server and Guix rejects substitutes not signed by one of the keys the
 user authorized.])
+
+        (figure :legend [The ,(tt [guix]) command makes remote
+procedure calls (RPCs) to a build daemon, which spawns hermetic builds
+on its behalf.]
+           :ident "fig-build-daemon"
+          (!latex (call-with-input-file "images/guix-build-daemon.tex"
+                    get-string-all)))
+
         (p [To maximize chances that build processes actually look like
 pure functions, they are spawned in isolated build environments—Linux
 ,(emph [containers])—ensuring that only explicitly declared inputs are
-visible to the build process.  This, in turn, helps achieve bit-for-bit
+visible to the build process.  This method, inherited from Nix ,(ref
+:bib 'dolstra2004:nix), is illustrated in ,(numref :text [Figure] :ident
+"fig-build-daemon"): ,(tt [guix]) commands make remote procedure calls
+(RPCs) to a build daemon, which spawns build processes in isolated
+environments on their behalf and stores the build result in ,(tt
+[/gnu/store]).])
+        (p [Build isolation, in turn, helps achieve bit-for-bit
 ,(emph [reproducible builds]), which are critical from a security
 standpoint ,(ref :bib 'lamb2021:reproducible).  Reproducible builds
 enable users and developers to verify that a binary matches a given
@@ -485,6 +509,16 @@ asset to be protected are binaries themselves ,(ref :bib
 'cappos2008:attacks).  Guix being a source-based distribution, the
 question has to be approached from a different angle.])
 
+      (figure :legend [Supplying software with Guix: developers (left)
+write package definitions, test them, and publish them in the Git
+repository; users (right) update their copy from Git using ,(tt [guix
+pull]) and either fetch binaries for the packages they need or build
+them locally.]
+        :ident "fig-package-workflow"
+        
+        (!latex (call-with-input-file "images/guix-package-workflow.tex"
+                   get-string-all)))
+
       (p [Guix consists of source code for the tools as well as package
 definitions that make up the GNU/Linux distribution.  All this code is
 maintained under version control in a Git repository.
@@ -492,7 +526,8 @@ To update Guix
 and its package collection, users run ,(tt [guix pull])—the equivalent
 of ,(tt [apt update]) in Debian.  When users run ,(tt [guix pull]), what
 happens behind the scene is equivalent to ,(tt [git clone]) or ,(tt [git
-pull]).])
+pull]).  This workflow is illustrated in ,(numref :text [Figure] :ident
+"fig-package-workflow").])
       
       (p [There are several ways this update process can lead users to
 run malicious code.  An attacker could trick the user into connecting to
@@ -605,7 +640,8 @@ authorizations.])
       (figure
         :legend [Graph of commits and the associated authorizations.]
         :ident "fig-commits"
-        (image :file "images/commit-graph.pdf"))
+        (image :file "images/commit-graph.pdf"
+           :width 0.7))
 
       (p [Let us take an example to illustrate the authorization
 invariant.  In ,(numref :text [Figure] :ident "fig-commits"), each box
@@ -677,7 +713,8 @@ authorization invariant?])
       (figure
         :legend [The introductory commit in a commit graph.]
         :ident "fig-commit-graph-intro"
-        (image :file "images/commit-graph-intro.pdf"))
+        (image :file "images/commit-graph-intro.pdf"
+           :width 0.7))
 
       (p [We solve this bootstrapping issue by defining ,(emph [channel 
introductions]).
 Previously, one would identify a channel solely by its URL.  Now, when
@@ -1218,12 +1255,19 @@ non-verifiability through attestation.  SLSA ,(ref :bib
 similar approach, insisting on certification rather than allowing
 independent verification of each step.])
 
+      (figure :legend [GitHub’s Web interface showing commit
+verification statuses.]
+        :ident "fig-github-verification"
+        (image :file "images/github-verification-statuses.png"))
+
       (p [While signed Git commits (and tags) are becoming more common
 and generally seen as good practice, we are not aware of other tools or
 protocols to support off-line Git checkout authentication.  Recently,
+as illustrated in ,(numref :ident "fig-github-verification" :text [Figure]),
 hosting platforms such as GitHub and GitLab started displaying a
 “verified” tag next to commits signed with the OpenPGP key of the person
-who pushed them or that of their author—a very limited verification
+who pushed them or that of their author—a very limited verification that
+may give a false sense of security
 ,(ref :bib '(github2021:verify-commits gitlab2021:verify-commits)).
 This mechanism depends on out-of-band data (keys associated with user
 accounts) and does not permit off-line checks; it also lacks a notion of