doc: how to update the repository

As it is not easy to get files to dom0 and we don't want to reimplement
a package manager, crude Git is the solution as of know.

With Git we have the following advantages: native fetch format for
source controlled files, cleaner command-line, automatic signature
verification during merge, the disadvantage is that it is not included
by default in Dom0 and filtering it's stdout chars are not possible.
Note that the remote can report messages to the client via stderr, which
is filtered already, and if it tries to send an escape sequence to
stdout, the operation will fail with 'bad line length character: CHAR'
printed to stderr on the client, unfiltered by qrexec, but filtered to
some extent by the git client. If it is an escape character, the char is
transformed to "?", but UTF-8 multibyte characters are not filtered. Up
to 4 bytes can be displayed.

Tar on the other hand is already installed, but it is much ancient and
it's file parsing caused CVEs in the past relatively more drastic than
Git, it also doesn't only include committed files, it can include any
file that is present in the directory, which by far, increases a lot of
the attack surface unless you reset the state to HEAD, clean .git
directory manually and there are possibly other avenues of attack.

README.md

@@ -13,8 +13,11 @@ and will be introduced in the meantime. You've been warned.
 * [Design](#design)
 * [Prerequisites](#prerequisites)
 * [Installation](#installation)
-  * [DomU](#domu)
+  * [DomU Installation](#domu-installation)
-  * [Dom0](#dom0)
+  * [Dom0 Installation](#dom0-installation)
+* [Update](#update)
+  * [DomU Update](#domu-update)
+  * [Dom0 Update](#dom0-update)
 * [Usage](#usage)
 * [Contribute](#contribute)
 * [Donate](#donate)
@@ -50,7 +53,7 @@ adjust the target of the qubesctl call or write Salt Top files.
 Qubes global settings (qubes-prefs) that will be managed:
 
 - **clockvm**: disp-sys-net, sys-net
-- **default_dispvm**: reader
+- **default_dispvm**: dvm-reader
 - **default_netvm**: sys-pihole, sys-firewall or disp-sys-firewall
 - **management_dispvm**: dvm-mgmt
 - **updatevm**: sys-pihole, sys-firewall or disp-sys-firewall
@@ -68,21 +71,26 @@ You current setup needs to fulfill the following requisites:
 
 ## Installation
 
-### DomU
+### DomU Installation
 
-1. Install `git` in the downloader qube, if it is an AppVM, install it in the
+1. Install `git` in the downloader qube, if it is an AppVM, install it it's
-TemplateVM.
+   the TemplateVM.
 
-2. Clone this repository in an app qube:
+2. Clone this repository:
   ```sh
   git clone --recurse-submodules https://github.com/ben-grande/qusal.git
   ```
-If you made a fork, before cloning it, fork the submodule(s). Clone your own
+  If you made a fork, fork the submodule(s) before clone and use your remote
-project instead of this one, the submodules will be from your fork also.
+  repository instead, the submodules will also be from your fork.
 
-3. Verify the [commit or tag signature](https://www.qubes-os.org/security/verifying-signatures/#how-to-verify-signatures-on-git-repository-tags-and-commits).
+3. Acquire the maintainer signing key by other means and import it.
 
-### Dom0
+4. Verify the [commit or tag signature](https://www.qubes-os.org/security/verifying-signatures/#how-to-verify-signatures-on-git-repository-tags-and-commits) and expect a good signature, be surprised otherwise:
+  ```sh
+  git verify-commit HEAD
+  ```
+
+### Dom0 Installation
 
 Before copying anything to Dom0, read [Qubes OS warning about consequences of
 this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-dom0).
@@ -97,8 +105,38 @@ qvm-run -p <QUBE> tar -cC </PATH/TO> qusal | tar -xvC ~/QubesIncoming/<QUBE> qus
 
 2. Copy the project to the Salt directories:
 ```sh
-cd ~/QubesIncoming/<QUBE>/qusal
+~/QubesIncoming/<QUBE>/qusal/scripts/setup.sh
-./scripts/setup.sh
+```
+
+## Update
+
+To update, you can copy the repository again to dom0 as instructed in the
+[installation](#installation) instructions above or you can fetch it with Git,
+as will be demonstrated below.
+
+### DomU Update
+
+Update the repository state in your trusted DomU:
+```sh
+git -C ~/src/qusal fetch --recurse-submodules
+```
+
+### Dom0 Update
+
+1. Install git on Dom0, allow the Qrexec protocol to work in submodules and
+   clone the repository to `~/src/qusal` (only has to be run once):
+```sh
+mkdir -p ~/src
+sudo qubesctl state.apply sys-git.install-client
+git config --file ~/.gitconfig.local protocol.qrexec.allow always
+git clone --recurse-submodules qrexec://@default/qusal.git ~/src/qusal
+```
+
+2. Fetch from the app qube and place the files in the salt tree (git merge and
+   pull will verify the HEAD signature automatically)
+```sh
+git -C ~/src/qusal fetch --recurse-submodules
+~/src/qusal/scripts/setup.sh
 ```
 
 ## Usage

salt/sys-git/README.md

@@ -40,13 +40,36 @@ implementation:
 | Fetch | True | True  | True (only tags) | True |
 | Push  | True | True  | False | True |
 | Init  | True | False | False | False |
-| Validates Git communication | False | False | True | False |
+| Validates git communication | False | False | True | False |
 | Verifies tag signature | False | False | True | False |
 
 ## Security
 
 It is not possible to filter Git's stdout from a Qrexec call as it is used by
-the local running git process.
+the local running git process, we rely on Git's parsing and filtering for
+remote operations. A remote can send up to 4 bytes of UTF-8 character to it's
+stdout as packet information during the initial server client negotiation, the
+client will display the characters on stderr with an error message containing
+the character. Git only filters for control characters but other characters
+that are valid UTF-8 such as multibyte are not filtered. The same characters
+can be present in the git log.
+
+A remote helper that validates the data received can increase the security
+by not printing untrusted data, which is the case with
+[qubes-app-split-git](https://github.com/QubesOS-contrib/qubes-app-split-git/commits/master/),
+but unfortunately it demands signed tags and doesn't work for normal git
+operations with signed commits and branches, as the later can't be signed.
+A fork of the aforementioned project might be the future of this helper.
+
+Even if the transport is secure, the tool that renders the information of your
+recently acquired repository
+[can](https://nvd.nist.gov/vuln/detail/CVE-2022-23521)
+[contain](https://nvd.nist.gov/vuln/detail/CVE-2022-41902)
+[bugs](https://nvd.nist.gov/vuln/detail/CVE-2022-46663)
+[that](https://nvd.nist.gov/vuln/detail/CVE-2023-25652)
+[result](https://nvd.nist.gov/vuln/detail/CVE-2023-29007)
+in local code execution and remote code execution. In the end, if you don't
+trust the origin, don't use it.
 
 ## Installation