From 04c8bc634251861365ddf0a7135f534af3711b52 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sun, 24 Mar 2024 17:46:22 +0100 Subject: [PATCH] docs: simplify TAM-related upgrade docs using the new commands --- docs/changes.rst | 56 ++++++++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 21 deletions(-) diff --git a/docs/changes.rst b/docs/changes.rst index 50c29ee9bf..96da705b59 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -29,49 +29,63 @@ places. Borg now considers archives without TAM as garbage or an attack. We are not aware of others having discovered, disclosed or exploited this vulnerability. -Below, if we speak of borg 1.2.6, we mean a borg version >= 1.2.6 **or** a -borg version that has the relevant security patches for this vulnerability applied +Below, if we speak of borg 1.2.8, we mean a borg version >= 1.2.8 **or** a +borg version that has the relevant patches for this vulnerability applied (could be also an older version in that case). Steps you must take to upgrade a repository (this applies to all kinds of repos no matter what encryption mode they use, including "none"): -1. Upgrade all clients using this repository to borg 1.2.6. +1. Upgrade all clients using this repository to borg 1.2.8. Note: it is not required to upgrade a server, except if the server-side borg is also used as a client (and not just for "borg serve"). - Do **not** run ``borg check`` with borg 1.2.6 before completing the upgrade steps: + Do **not** run ``borg check`` with borg > 1.2.4 before completing the upgrade steps: - ``borg check`` would complain about archives without a valid archive TAM. - ``borg check --repair`` would remove such archives! -2. Run: ``BORG_WORKAROUNDS=ignore_invalid_archive_tam borg info --debug 2>&1 | grep TAM | grep -i manifest`` +2. Do this step on every client using this repo: ``borg upgrade --show-rc --check-tam `` - a) If you get "TAM-verified manifest", continue with 3. - b) If you get "Manifest TAM not found and not required", run - ``borg upgrade --tam --force `` *on every client*. + This will check the manifest TAM authentication setup in the repo and on this client. + The command will exit with rc=0 if all is OK, otherwise with rc=1. -3. Run: ``BORG_WORKAROUNDS=ignore_invalid_archive_tam borg list --consider-checkpoints --format='{name} {time} tam:{tam}{NL}' `` + a) If you get "Manifest authentication setup OK for this client and this repository." + and rc=0, continue with 3. + b) If you get some warnings and rc=1, run: + ``borg upgrade --tam --force `` - "tam:verified" means that the archive has a valid TAM authentication. - "tam:none" is expected as output for archives created by borg <1.0.9. - "tam:none" is also expected for archives resulting from a borg rename - or borg recreate operation (see #7791). - "tam:none" could also come from archives created by an attacker. - You should verify that "tam:none" archives are authentic and not malicious +3. Run: ``borg upgrade --show-rc --check-archives-tam `` + + This will create a report about the TAM status for all archives. + In the last line(s) of the report, it will also report the overall status. + The command will exit with rc=0 if all archives are TAM authenticated or with rc=1 + if there are some archives with TAM issues. + + If there are no issues and all archives are TAM authenticated, continue with 5. + + Archive TAM issues are expected for: + + - archives created by borg <1.0.9. + - archives resulting from a borg rename or borg recreate operation (see #7791) + + But, important, archive TAM issues could also come from archives created by an attacker. + You should verify that archives with TAM issues are authentic and not malicious (== have good content, have correct timestamp, can be extracted successfully). In case you find crappy/malicious archives, you must delete them before proceeding. + In low-risk, trusted environments, you may decide on your own risk to skip step 3 and just trust in everything being OK. -4. If there are no tam:none archives left at this point, you can skip this step. - Run ``BORG_WORKAROUNDS=ignore_invalid_archive_tam borg upgrade --archives-tam ``. +4. If there are no archives with TAM issues left at this point, you can skip this step. + + Run ``borg upgrade --archives-tam ``. + This will unconditionally add a correct archive TAM to all archives not having one. ``borg check`` would consider TAM-less or invalid-TAM archives as garbage or a potential attack. - To see that all archives now are "tam:verified" run: ``borg list --consider-checkpoints --format='{name} {time} tam:{tam}{NL}' `` -5. Please note that you should never use BORG_WORKAROUNDS=ignore_invalid_archive_tam - for normal production operations - it is only needed once to get the archives in a - repository into a good state. All archives have a valid TAM now. + To see that all archives are OK now, you can optionally repeat the command from step 3. + +5. Done. Manifest and archives are TAM authenticated now. Vulnerability time line: