Upgrading Whonix Deb Packages from Source Code

From Whonix
Jump to navigation Jump to search


Introduction[edit]

This assumes you are updating Whonix debian packages while you are using Whonix.

Prerequisites[edit]

Might be a good idea to create a backup and/or clone before trying to update.

If you haven't done already, disable Whonix APT repository. [1]

sudo repository-dist --disable

Upgrade from Debian packages.

sudo apt update && sudo apt --yes full-upgrade

Get the Source Code[edit]

Get the Signing Key[edit]

Info This step is recommended for better security, but is not strictly required. (See Trust.)

Get the Whonix Signing Key and import it.

Get the Source Code[edit]

FREE

Note: By proceeding, you acknowledge that you have read, understood and agreed to our Terms of Service and License Agreement.

1. Install git.

sudo apt update && sudo apt install git

2. Get the source code including git submodules. [2] [3]

Note: Replace 17.2.8.5-stable with the actual tag you want to build.

git clone --depth=1 --branch 17.2.8.5-stable --jobs=4 --recurse-submodules --shallow-submodules https://github.com/Whonix/derivative-maker.git

3. Check if above command succeeded.

If there have been errors such as: 

fatal: unable to access 'https://github.com/.../': Could not resolve host: github.com

Or. 

fatal: unable to access 'https://github.com/.../': gnutls_handshake() failed: The TLS connection was non-properly terminated.

Then the download probably failed.

Checking if the download failed or succeeded can be done by checking the exit code.

Choose your shell.

Zsh in Kicksecure or Derivatives

If the last line contains something such as the following. 

zsh: exit 1

Then do not proceed and see footnote. [4]

bash and other Shells

Show the exit code.

echo $?

Output should show. 

0

If any other exit code is shown, do not proceed and see footnote. [4]

4. Done.

Git repository cloning has been completed.

Change Directory[edit]

Get into the Whonix source code folder because later on package build commands using ./derivative-maker are expected to be run from the root of the source folder.

cd derivative-maker

OpenPGP Verify the Source Code[edit]

This chapter is recommended for better security, but is not strictly required. (See Trust.)

  • Digital signatures are a tool enhancing download security. They are commonly used across the internet and nothing special to worry about.
  • Optional, not required: Digital signatures are optional and not mandatory for using Whonix, but an extra security measure for advanced users. If you've never used them before, it might be overwhelming to look into them at this stage. Just ignore them for now.
  • Learn more: Curious? If you are interested in becoming more familiar with advanced computer security concepts, you can learn more about digital signatures here digital software signatures.

1. Verify the chosen tag to build.

Note: Replace with tag you want to build.

git verify-tag 17.2.8.5-stable

2. Check the output of the verification step.

If the file is verified successfully, the output will include Good signature, which is the most important thing to check. 

gpg: Good signature

This output might be followed by a warning as follows. 

gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.

This message does not alter the validity of the signature related to the downloaded key. Rather, this warning refers to the level of trust placed in the Whonix signing key and the web of trust. To remove this warning, the Whonix signing key must be personally signed with your own key.

warning Remember to check the GPG signature timestamp. For instance, if you previously saw a signature from 2023 and now see one from 2022, this could indicate a potential rollback (downgrade) or indefinite freeze attack.[5]

2. Verify the git commit to build. [6]

Note: Replace 17.2.8.5 with the actual git tag being verified.

git verify-commit 17.2.8.5-stable^{commit}

3. Check the output of the verification step.

4. Done.

Choose Version[edit]

1. Retrieve a list of available git tags.

git --no-pager tag

2. Use git checkout to select the preferred version to build.

Note: Replace 17.2.8.5-stable with the actual version chosen for the build: the stable, testers-only or developers version. Common sense is required when choosing the right version number. For example, the latest available version number is not necessarily the most stable or suitable. Follow the Whonix News Blog as it might contain information.

git checkout --recurse-submodules 17.2.8.5-stable

3. Digital signature verification.

Optional. If you choose to perform digital signature verification above, you could verify the currently chosen commit ("HEAD") yet again for extra security.

git verify-commit HEAD

4. Done.

Version selection has been completed.

Check Git[edit]

1. Check if you really got the version you want.

git describe

The output should show. 

{{{version}}}

2. Check if source folder is pristine.

git status

Output should be the following.

  • A)

HEAD detached at {{{version}}}
nothing to commit, working tree clean
or,

  • B)
Not currently on any branch.
nothing to commit, working tree clean

If it shows something else, do not continue.

3. Done.

Build Dependencies[edit]

Get all build dependencies.

sudo -E ./build-steps.d/1100_prepare-build-machine --internalrun --build --target root

Why --target root? This is correct, if you want to know why, see footnote. [7]

Create the Packages[edit]

If you're not debugging, create the packages with:

sudo -E ./build-steps.d/1200_create-debian-packages --build --internalrun --target root

If debugging, use the following command. Developers only! [8] Potentially insecure unless the untagged / uncommited changes are by you or by a trusted developer with a git gpg signature that you verified.

sudo -E ./build-steps.d/1200_create-debian-packages --build --allow-untagged true --allow-uncommitted true --internalrun --target root

Upgrade Whonix Debian Packages[edit]

Upgrade Whonix Debian Packages without contacting a Whonix APT Repository, using your own locally created apt package repository.

For Whonix-Gateway™.

sudo ./packages/kicksecure/developer-meta-files/debug-steps/locally-upgrade-whonix-debian-packages --build --target root --flavor whonix-gateway

[9]

For Whonix-Workstation™.

sudo ./packages/kicksecure/developer-meta-files/debug-steps/locally-upgrade-whonix-debian-packages --build --target root --flavor whonix-workstation

There will be a lot debug output. [10]

If everything went well, you will see [11] [12]

########################################################################
## INFO: Successfully configured (postinst script) Whonix-Workstation. #
########################################################################

The last few highlighted messages will be similar to:

+ true 'INFO: Skipping script, because --target root: /home/user/whonix_dot/Whonix/help-steps/unmount-img'
+ true 'INFO: End of: ./debug-steps/locally-upgrade-whonix-debian-packages | exit_code: 0 | error(s) detected: 0 | benchmark: 00:01:40'

In case any error is caught, the script will loudly complain by echoing in a red colored error message:

ERROR in ./debug-steps/locally-upgrade-whonix-debian-packages! Aborted.

Lets hope it works well. Please get in Contact should there be any issues. Leave feedback if you are using this, if it worked for you, which issues you may have had, so these instructions can be updated.

Cleanup[edit]

Info This step is optional.

Remove temporary files.

Warning: This command will run git clean -d --force --force in Whonix's main source code folderarchive.org iconarchive.today icon (~/derivative-maker) as well as in all subfolders of the Whonix packages folderarchive.org iconarchive.today icon (~/derivative-maker/packages). This means if any files were purposefully added to any of these folders that have not been committed to git, these will be deleted. [13]

./help-steps/cleanup-files


See Also[edit]

Footnotes[edit]

  1. ↑ Project-APT-Repository#Disable_Whonix_APT_Repository
  2. ↑ Optional git parameters:
    • --depth=1: Used to speed up the download.
    • --branch 17.2.8.5-stable: Usability. Used to speed up the download.
    • --jobs=4: Used to speed up the download.
    • --recurse-submodules --shallow-submodules: Usability.
    Knowledgeable git users are free to drop any of these optional parameters.
  3. ↑ Alternatively, this can be achieved with the following commands in several steps. This is useful if network issues arise.
    • Over HTTPS:
      • git clone --depth=1 --branch 17.2.8.5-stable https://github.com/Whonix/derivative-maker.git
    • Over SSH.
      • Might work better over slow networks but requires a GitHub account and a configured SSH public key at GitHub. See footnote [A] below.
      • git clone --depth=1 --branch 17.2.8.5-stable git@github.com:Whonix/derivative-maker.git
    cd derivative-maker git submodule update --init --recursive --progress --jobs=4

    [A] GitHub SSH public key setup.

    1. You need to create an SSH public key.

    Undocumented.

    2. You view your your SSH public key.

    cat ~/.ssh/id_ed25519.pub

    3. Copy it.

    4. And paste your the SSH public key on GitHub.

    https://github.com/settings/keysarchive.org iconarchive.today icon

  4. ↑ 4.0 4.1 Delete the derivative-maker source code folder and retry. 
    sudo rm -r derivative-maker
  5. ↑ As defined by TUF: Attacks and Weaknesses:
  6. ↑ It is advisable to verify the signature of the git commit as well. By convention, git tags should point to signed git commits. Beginning from git tag 9.6 and above. (forum discussionarchive.org iconarchive.today icon)
  7. ↑ Setting the --target parameter to root will result in installing fewer build dependencies. For example VirtualBox will not be installed. These are only required to build full images, but since we just want to create updated Whonix Debian Packages, this is unnecessary. Not much harm done when forgetting to use --target root, because the user is free to remove any build dependencies later.
  8. ↑ Packages are possibly not matching the quality for redistributable testes or stable builds. This is because the package will potentially built from git master, which has no proper debian/changelog release version, and no signed git tag. There may be another package of that version in the repository that is different. Distinguishing these packages is hard and would cause confusion. Therefore this is considered unclean and only developers may do this for debugging purposes.
  9. ↑ Why use --target root"? Technical explanation: --target root in context of Whonix source code means "do it on the system currently running, i.e. do it directly on the root folder "/[...]", don't do it inside "vm_image/[...]".
  10. ↑ Unless you log in as root and run export WHONIX_DEB_DEBUG=0.
  11. ↑ Or saying Whonix-Gateway respectively
  12. ↑ It won't, if you have export WHONIX_DEB_DEBUG=0 set.
  13. ↑ https://github.com/Whonix/derivative-maker/blob/master/help-steps/cleanup-filesarchive.org iconarchive.today icon
Notification image
Your support makes
all the difference!

We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 13 year success story and maybe DONATE!

Retrieved from "https://www.whonix.org/w/index.php?title=Dev/Build_Documentation/Upgrading_Derivative_Deb_Packages_from_Source_Code&oldid=97032"