From a02997b89e0f900397c653f5d86c076f48c9e69c Mon Sep 17 00:00:00 2001 From: Ben Grande Date: Wed, 8 Jan 2025 14:38:48 +0100 Subject: [PATCH] doc: simplify installation command Many people reported problems with the installation command, most of them had typos, understandable due to the long command. Tar is available even on minimal templates. Using tar is not more dangerous than using qfile-unpacker in this case because the project has no signed archives and passing a directory to dom0 is insecure, considering a git repo, an attacker could find information in the .git directory or modify files and add them to git exclude, which won't be noticed when verifying the commit signature. In the future, if a signed tarball were to be provided, qvm-run and pipe would be used instead, making the command even simpler. --- .reuse/dep5 | 4 ++-- docs/INSTALL.md | 46 ++++++++++++++++++++++++++++----------- scripts/copyright-lint.sh | 4 ++++ 3 files changed, 39 insertions(+), 15 deletions(-) diff --git a/.reuse/dep5 b/.reuse/dep5 index 74e80d8..f61c351 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -4,11 +4,11 @@ Upstream-Contact: Benjamin Grande M. S. Source: https://github.com/ben-grande/qusal Files: README.md */README.md docs/* .github/*_TEMPLATE/* .github/*.md -Copyright: 2023 - 2024 Benjamin Grande M. S. +Copyright: 2023 - 2025 Benjamin Grande M. S. License: CC-BY-SA-4.0 Files: version salt/*/version dependencies/* .ecrc -Copyright: 2023 - 2024 Benjamin Grande M. S. +Copyright: 2023 - 2025 Benjamin Grande M. S. License: CC0-1.0 Files: salt/electrum/files/client/keys/* diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 23002ca..2de930e 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -27,6 +27,12 @@ You current setup needs to fulfill the following requisites: ### DomU Installation +It is recommended to use separate qube from your normal operations as this +installation will eventually be copied to dom0. Apart from that, it is also +recommended to use a separate qube for fetching the signing keys, different +from the one acquiring Qusal. The separate qubes should be DispVM, but AppVM +or StandaloneVM will also work. + 1. Install `git` in the qube, if it is an AppVM, install it it's the TemplateVM and restart the AppVM. @@ -35,17 +41,24 @@ You current setup needs to fulfill the following requisites: from your fork). ```sh - git clone --recurse-submodules https://github.com/ben-grande/qusal.git + git clone --recurse-submodules https://github.com/ben-grande/qusal.git ~/qusal ``` 3. Copy the [maintainer's signing key](https://github.com/ben-grande/ben-grande/raw/main/DF3834875B65758713D92E91A475969DE4E371E3.asc) - to your text editor and save the file to `/home/user/ben-code.asc`. + to your text editor and save to the file `/home/user/ben-code.asc`. ### 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). + + 1. Copy the repository `$file` from the DomU `$qube` to Dom0 (substitute `CHANGEME` for the desired valued): @@ -53,16 +66,16 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d qube="CHANGEME" # qube name where you downloaded the repository file="CHANGEME" # path to the repository in the qube - qvm-run --pass-io --localcmd="UPDATES_MAX_FILES=10000 - /usr/libexec/qubes/qfile-dom0-unpacker user - ~/QubesIncoming/${qube}/qusal" \ - "${qube}" /usr/lib/qubes/qfile-agent "${file}" + mkdir -p -- ~/QubesIncoming/"${qube}" + qvm-run --no-gui --pass-io -- "${qube}" "tar -cf - -C ~ qusal" | + tar -xf - -C ~/QubesIncoming/"${qube}" ``` 2. Pass the maintainer's key from the qube to Dom0: ```sh - qvm-run --pass-io "${qube}" -- "cat /home/user/ben-code.asc" | tee /tmp/ben-code.asc + qvm-run --no-gui --pass-io -- "${qube}" "cat -- /home/user/ben-code.asc" | + tee -- /tmp/ben-code.asc >/dev/null ``` 3. Verify that the key fingerprint matches @@ -81,7 +94,13 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d gpg --import /tmp/ben-code.asc ``` -5. Verify the [commit or tag signature](https://www.qubes-os.org/security/verifying-signatures/#how-to-verify-signatures-on-git-repository-tags-and-commits) +5. Enter the repository: + + ```sh + cd ~/QubesIncoming/"${qube}"/qusal + ``` + +6. 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 @@ -93,19 +112,20 @@ this procedure](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-d ```sh tag_list="$(git tag --points-at=HEAD)" - verification=0 + verified=0 for tag in ${tag_list}; do if git verify-tag "${tag}" - verification=1 + verified=1 break fi done - if test "${verification}" = "0"; then + if test "${verified}" = "0"; then + printf '%s\n' "Failed to verify qusal" >&2 false fi ``` -6. Copy the project to the Salt directories: +7. Copy the project to the Salt directories: ```sh ~/QubesIncoming/"${qube}"/qusal/scripts/setup.sh @@ -183,7 +203,7 @@ files from being tracked and signature verification won't catch it. file="CHANGEME" # path to the repository in the qube rm -rf ~/QubesIncoming/"${qube}"/qusal - UPDATES_MAX_FILES=10000 qvm-copy-to-dom0 "${qube}" "${file}" + UPDATES_MAX_FILES=50000 qvm-copy-to-dom0 "${qube}" "${file}" ``` 3. Verify the commit or tag signature as shown in diff --git a/scripts/copyright-lint.sh b/scripts/copyright-lint.sh index 2accb79..ad3b1ea 100755 --- a/scripts/copyright-lint.sh +++ b/scripts/copyright-lint.sh @@ -54,6 +54,10 @@ test "${xtrace}" = 0 || set -x for file in ${files}; do test "${xtrace}" = 0 || set -x + case "${file}" in + .reuse/dep5) continue;; + *) ;; + esac file="${file#./}" set +x awk -v year="${year}" -v email="${email}" -v file="${file}" -- '