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.
This commit is contained in:
Ben Grande 2024-01-18 15:22:35 +01:00
parent 9b740d8314
commit f8ea066b2b
2 changed files with 79 additions and 18 deletions

View File

@ -13,8 +13,11 @@ and will be introduced in the meantime. You've been warned.
* [Design](#design)
* [Prerequisites](#prerequisites)
* [Installation](#installation)
* [DomU](#domu)
* [Dom0](#dom0)
* [DomU Installation](#domu-installation)
* [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
TemplateVM.
1. Install `git` in the downloader qube, if it is an AppVM, install it it's
the TemplateVM.
2. Clone this repository in an app qube:
```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
project instead of this one, the submodules will be from your fork also.
2. Clone this repository:
```sh
git clone --recurse-submodules https://github.com/ben-grande/qusal.git
```
If you made a fork, fork the submodule(s) before clone and use your remote
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
./scripts/setup.sh
~/QubesIncoming/<QUBE>/qusal/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

View File

@ -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