From d42453fde45aad5c5482750c3ca5203f6c2b55b6 Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Sun, 26 Oct 2025 23:13:59 +0100 Subject: [PATCH 1/6] Docs: Rewrite `borg init` docs --- docs/borg_theme/css/borg.css | 7 +- docs/usage/general/environment.rst.inc | 2 + src/borg/archiver.py | 244 ++++++++++++++++--------- 3 files changed, 168 insertions(+), 85 deletions(-) diff --git a/docs/borg_theme/css/borg.css b/docs/borg_theme/css/borg.css index 66712b418..36463d657 100644 --- a/docs/borg_theme/css/borg.css +++ b/docs/borg_theme/css/borg.css @@ -122,10 +122,15 @@ table.docutils.borg-options-table tr td:first-child:not([colspan="3"]) { margin: 0; } -.borg-options-table { +.borg-options-table, +.borg-encryption-table { width: 100%; } +.borg-encryption-table th { + text-align: center; +} + kbd, /* used in usage pages for options */ code, .rst-content tt.literal, diff --git a/docs/usage/general/environment.rst.inc b/docs/usage/general/environment.rst.inc index 89c1437de..ca2ad5e82 100644 --- a/docs/usage/general/environment.rst.inc +++ b/docs/usage/general/environment.rst.inc @@ -1,3 +1,5 @@ +.. _environment-variables: + Environment Variables ~~~~~~~~~~~~~~~~~~~~~ diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 5232a988c..409196bcb 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -4510,38 +4510,70 @@ class Archiver: This command initializes an empty repository. A repository is a filesystem directory containing the deduplicated data from zero or more archives. - Encryption mode TLDR - ++++++++++++++++++++ + Encryption mode tl;dr + +++++++++++++++++++++ - The encryption mode can only be configured when creating a new repository - - you can neither configure it on a per-archive basis nor change the - encryption mode of an existing repository. + The encryption mode can only be configured when creating a new + repository. You can neither configure encryption on a per-archive + basis, nor change the encryption mode of an existing repository. You + should thus take possible future use into account when deciding for + an encryption mode. - Use ``repokey``:: + As a general rule of thumb, use ``repokey`` with a strong passphrase: borg init --encryption repokey /path/to/repo - Or ``repokey-blake2`` depending on which is faster on your client machines (see below):: + However, there are many reasons to choose differently. See the section + below for details. In any case, Borg will: - borg init --encryption repokey-blake2 /path/to/repo + 1. Ask you to enter a unique and strong passphrase. + 2. Create a random Borg key (which actually consists of three random + secrets, see :ref:`key_files` for details). + 3. Encrypt the Borg key with your passphrase. + 4. Store the encrypted Borg key inside the repository directory (with + ``repokey`` and ``repokey-blake2`` modes; with ``keyfile`` and + ``keyfile-blake2`` modes the Borg key is stored in your home + directory instead, see below). Since we usually have to assume that + an attacker could gain access to the repository (that's why we + encrypt the data in the first place), choosing a strong and unique + passphrase is absolutely crucial. + 5. Encrypt and sign your backups with the Borg key to prevent anyone + from reading or forging them unless they have the Borg key *and* + know the passphrase. + 6. Use the Borg key to decrypt and thus access the data stored in your + repository, e.g. when extracting files. The contents can also be + verified to detect accidental or malicious tampering. - Borg will: + As you can see, you always need *both* the Borg key and passphrase + to access your data. Thus it's crucial to keep a backup of your key + *outside* both the repository and the system you create backups of. + You can easily run into a "leaving your keys inside your car" + situation otherwise. See :ref:`borg_key_export` to create a backup + of your key (e.g., by printing it on paper). - 1. Ask you to come up with a passphrase. - 2. Create a Borg key (which contains three random secrets. See :ref:`key_files`). - 3. Encrypt the key with your passphrase. - 4. Store the encrypted Borg key inside the repository directory (in the repo config). - This is why it is essential to use a secure passphrase. - 5. Encrypt and sign your backups to prevent anyone from reading or forging them unless they - have the key and know the passphrase. Make sure to keep a backup of - your key **outside** the repository - do not lock yourself out by - "leaving your keys inside your car" (see :ref:`borg_key_export`). - For remote backups the encryption is done locally - the remote machine - never sees your passphrase, your unencrypted key or your unencrypted files. - Chunking and ID generation are also based on your key to improve - your privacy. - 6. Use the key when extracting files to decrypt them and to verify that the contents of - the backups have not been accidentally or maliciously altered. + Encryption is done locally - i.e., if you backup to a remote machine, + the remote machine neither sees your passphrase, nor your unencrypted + Borg key, nor your unencrypted files. Chunking and ID generation is + based on your key to improve privacy. + + **About hardware acceleration:** + + Borg encrypts data with AES, which is pretty fast thanks to hardware + acceleration on basically all modern Intel, AMD, and ARM CPUs since + around the early 2010's (very cheap models since the mid 2010's). + + As hashing algorithm Borg can either use SHA256, or BLAKE2b. ARM CPUs + support hardware-accelerated SHA256 hashing since ARMv7 with NEON + (around 2011), or ARMv8 (around 2013). AMD CPUs support it since Zen 1 + (around 2017), i.e. all AMD Ryzen CPUs. Intel CPUs support it since + Ice Lake on mobile (10th gen, around 2021), and Rocket Lake on desktop + (11th gen, around 2021). Very cheap models have received support a few + years later. If your CPU doesn't support hardware-accelerated SHA256 + hashing, you might want to give BLAKE2b hashing a try - it's likely + faster then. So, instead of ``repokey`` mode, use ``repokey-blake2`` + (or any of the other ``-blake2`` modes for that matter). + + Hardware acceleration is always used automatically when available. Picking a passphrase ++++++++++++++++++++ @@ -4562,83 +4594,127 @@ class Archiver: a different keyboard layout. You can change your passphrase for existing repositories at any time; it won't affect - the encryption/decryption key or other secrets. + the encryption/decryption key or other secrets. See :ref:`borg_key_change-passphrase`. - More encryption modes - +++++++++++++++++++++ + More about encryption modes + +++++++++++++++++++++++++++ - Only use ``--encryption none`` if you are OK with anyone who has access to - your repository being able to read your backups and tamper with their - contents without you noticing. + Choosing the right encryption mode isn't always easy and many factors + can change which mode is best for you. However, note that you can't + really do anything *wrong* if you choose ``repokey`` with a strong + passphrase. So, if you're not sure, choose ``repokey`` (or + ``repokey-blake2``, depending on your hardware, see above). - If you want "passphrase and having-the-key" security, use ``--encryption keyfile``. - The key will be stored in your home directory (in ``~/.config/borg/keys``). - - If you do **not** want to encrypt the contents of your backups, but still - want to detect malicious tampering use ``--encryption authenticated``. - To normally work with ``authenticated`` repos, you will need the passphrase, but - there is an emergency workaround, see ``BORG_WORKAROUNDS=authenticated_no_key`` docs. - - If ``BLAKE2b`` is faster than ``SHA-256`` on your hardware, use ``--encryption authenticated-blake2``, - ``--encryption repokey-blake2`` or ``--encryption keyfile-blake2``. Note: for remote backups - the hashing is done on your local machine. + Borg supports the following encryption modes: .. nanorst: inline-fill + .. class:: borg-encryption-table - +----------+---------------+------------------------+--------------------------+ - | Hash/MAC | Not encrypted | Not encrypted, | Encrypted (AEAD w/ AES) | - | | no auth | but authenticated | and authenticated | - +----------+---------------+------------------------+--------------------------+ - | SHA-256 | none | `authenticated` | repokey | - | | | | keyfile | - +----------+---------------+------------------------+--------------------------+ - | BLAKE2b | n/a | `authenticated-blake2` | `repokey-blake2` | - | | | | `keyfile-blake2` | - +----------+---------------+------------------------+--------------------------+ + +----------+-------------------+--------------------------+-------------------------+ + | Hash/MAC | Not Encrypted | Encrypted (AEAD w/ AES) | + + +-------------------+--------------------------+-------------------------+ + | | Not Authenticated | Authenticated | + +==========+===================+==========================+=========================+ + | SHA-256 | ``none`` | ``authenticated`` | ``repokey`` | + | | | | ``keyfile`` | + +----------+-------------------+--------------------------+-------------------------+ + | BLAKE2b | n/a | ``authenticated-blake2`` | ``repokey-blake2`` | + | | | | ``keyfile-blake2`` | + +----------+-------------------+--------------------------+-------------------------+ .. nanorst: inline-replace - Modes `marked like this` in the above table are new in Borg 1.1 and are not - backwards-compatible with Borg 1.0.x. + Borg 1.0 and older support ``none``, ``repokey``, and ``keyfile`` + modes only. If you need such old clients to be able to access your + repo, you can't use any of the other modes. - On modern Intel/AMD CPUs (except very cheap ones), AES is usually - hardware-accelerated. - BLAKE2b is faster than SHA256 on Intel/AMD 64-bit CPUs - (except AMD Ryzen and future CPUs with SHA extensions), - which makes `authenticated-blake2` faster than `none` and `authenticated`. + **About modes without encryption:** - On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster - than BLAKE2b-256 there. NEON accelerates AES as well. + Avoid using ``none`` mode. If you think about using ``none`` mode, + please reconsider and be absolutely sure. Using any mode other than + ``none`` allows Borg to detect accidental or malicious tampering with + the repo. It also prevents denial-of-service attacks against clients. + Instead of ``none`` mode, you likely want to use ``authenticated`` + mode, or ``repokey`` or ``keyfile`` modes with an empty passphrase + instead (see below). - Hardware acceleration is always used automatically when available. + If you don't want to encrypt your data, use ``authenticated`` or + ``authenticated-blake2`` modes. These modes require a passphrase in + normal operation, but in emergency situations you can access the repo + without the passphrase with ``BORG_WORKAROUNDS=authenticated_no_key`` + (see :ref:`Environment_Variables`). - `repokey` and `keyfile` use AES-CTR-256 for encryption and HMAC-SHA256 for - authentication in an encrypt-then-MAC (EtM) construction. The chunk ID hash - is HMAC-SHA256 as well (with a separate key). - These modes are compatible with Borg 1.0.x. + If you just don't want to choose a passphrase, use ``keyfile`` or + ``keyfile-blake2`` modes with an empty passphrase. These modes are + generally safe even without a passphrase, but keeping an offsite + backup of the Borg key is especially important then. See below for + details. - `repokey-blake2` and `keyfile-blake2` are also authenticated encryption modes, - but use BLAKE2b-256 instead of HMAC-SHA256 for authentication. The chunk ID - hash is a keyed BLAKE2b-256 hash. - These modes are new and *not* compatible with Borg 1.0.x. + If you can assure that an attacker can't gain access to your repo, + e.g. when independently encrypting your repo with LUKS/dm-crypt, you + can think about using ``repokey`` or ``repokey-blake2`` modes with an + empty passphrase. However, keep in mind that if an attacker still + somehow manages to gain access, he has full access to your repo. In + such situations choosing ``repokey`` over ``authenticated`` mode has + the advantage of allowing you to add a passphrase later using + :ref:`borg_key_change-passphrase`. - `authenticated` mode uses no encryption, but authenticates repository contents - through the same HMAC-SHA256 hash as the `repokey` and `keyfile` modes (it uses it - as the chunk ID hash). The key is stored like `repokey`. - This mode is new and *not* compatible with Borg 1.0.x. + **About modes with encryption:** - `authenticated-blake2` is like `authenticated`, but uses the keyed BLAKE2b-256 hash - from the other blake2 modes. - This mode is new and *not* compatible with Borg 1.0.x. + With ``repokey`` and ``repokey-blake2`` modes the key is stored with + the repo and encrypted with your passphrase. If an attacker gains + access to your repo and knows the passphrase, he can access and tamper + with the repo. The repo's security thus relies on the strength of your + passphrase. Creating an offsite backup of your Borg key (e.g., by + printing it on paper) is recommended, see :ref:`borg_key_export`. - `none` mode uses no encryption and no authentication. It uses SHA256 as chunk - ID hash. This mode is not recommended, you should rather consider using an authenticated - or authenticated/encrypted mode. This mode has possible denial-of-service issues - when running ``borg create`` on contents controlled by an attacker. - Use it only for new repositories where no encryption is wanted **and** when compatibility - with 1.0.x is important. If compatibility with 1.0.x is not important, use - `authenticated-blake2` or `authenticated` instead. - This mode is compatible with Borg 1.0.x. + If you're thinking about storing the passphrase on the disk of the + system you're backing up, consider using the ``keyfile`` method + instead. It generally provides the same or better security then. + + With ``keyfile`` and ``keyfile-blake2`` modes the key is stored on + your local machine (in ``~/.config/borg/keys``) instead. An attacker + gaining access to your repo then needs both the Borg key, and your + passphrase to access and tamper with the repo. However, if you loose + the key, you loose access to the repo, too. You **must** create an + offsite backup of your Borg key, e.g. by printing it on paper. Storing + a copy of the Borg key on the system you're creating backups of is + **NOT** sufficient. Use :ref:`borg_key_export` to create the backup. + + The ``keyfile`` and ``keyfile-blake2`` modes allow for "passphrase and + having-the-key" security when using a strong passphrase, but can also + be used with an empty passphrase. Storing a passphrase on the disk of + the system you're backing up with ``keyfile`` and ``keyfile-blake2`` + modes adds no security over using an empty passphrase. + + **Technical details:** + + ``repokey`` and ``keyfile`` use AES-CTR-256 for encryption and + HMAC-SHA256 for authentication in an encrypt-then-MAC (EtM) + construction. The chunk ID hash is HMAC-SHA256 as well (with a + separate key). These modes are compatible with all Borg versions. + + ``repokey-blake2`` and ``keyfile-blake2`` are also authenticated + encryption modes, but use BLAKE2b-256 instead of HMAC-SHA256 for + authentication. The chunk ID hash is a keyed BLAKE2b-256 hash. These + modes are only compatible with Borg 1.1 and later. + + ``authenticated`` mode uses no encryption, but authenticates repo + contents through the same HMAC-SHA256 hash as the ``repokey`` and + ``keyfile`` modes (it uses it as the chunk ID hash). The key is stored + like ``repokey`` within the repo. This mode is only compatible with + Borg 1.1 and later. + + ``authenticated-blake2`` is like ``authenticated``, but uses the keyed + BLAKE2b-256 hash from the other BLAKE2b modes. This mode is only + compatible with Borg 1.1 and later. + + ``none`` mode uses no encryption and no authentication. It uses SHA256 + as chunk ID hash. This mode is not recommended. You should rather + consider using an authenticated or authenticated/encrypted mode. This + mode has possible denial-of-service issues when running ``borg create`` + on contents controlled by an attacker. See above for alternatives. + This mode is compatible with all Borg versions. """) subparser = subparsers.add_parser('init', parents=[common_parser], add_help=False, description=self.do_init.__doc__, epilog=init_epilog, From 4eb6773c2df5b2c0c7f1f6b3b5c1d83d4c84e6e6 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 29 Oct 2025 10:52:56 +0100 Subject: [PATCH 2/6] fix rst_plain_text_references --- src/borg/archiver.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 409196bcb..c68aaac16 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -3043,6 +3043,8 @@ class Archiver: 'borg_placeholders': '"borg help placeholders"', 'key_files': 'Internals -> Data structures and file formats -> Key files', 'borg_key_export': 'borg key export --help', + 'borg_key_change-passphrase': 'borg key change-passphrase', + 'environment-variables': 'Environment Variables', } def process_epilog(epilog): @@ -4642,7 +4644,7 @@ class Archiver: ``authenticated-blake2`` modes. These modes require a passphrase in normal operation, but in emergency situations you can access the repo without the passphrase with ``BORG_WORKAROUNDS=authenticated_no_key`` - (see :ref:`Environment_Variables`). + (see :ref:`environment-variables`). If you just don't want to choose a passphrase, use ``keyfile`` or ``keyfile-blake2`` modes with an empty passphrase. These modes are From 3c2daef474a98b43447bd8ad5e96af0f8f96366e Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 29 Oct 2025 11:19:49 +0100 Subject: [PATCH 3/6] fix typos and grammar Junie AI + TW --- src/borg/archiver.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index c68aaac16..b0b00ddcc 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -4512,13 +4512,13 @@ class Archiver: This command initializes an empty repository. A repository is a filesystem directory containing the deduplicated data from zero or more archives. - Encryption mode tl;dr + Encryption mode TL;DR +++++++++++++++++++++ The encryption mode can only be configured when creating a new repository. You can neither configure encryption on a per-archive basis, nor change the encryption mode of an existing repository. You - should thus take possible future use into account when deciding for + should thus take possible future use into account when deciding on an encryption mode. As a general rule of thumb, use ``repokey`` with a strong passphrase: @@ -4553,18 +4553,18 @@ class Archiver: situation otherwise. See :ref:`borg_key_export` to create a backup of your key (e.g., by printing it on paper). - Encryption is done locally - i.e., if you backup to a remote machine, + Encryption is done locally - i.e., if you back up to a remote machine, the remote machine neither sees your passphrase, nor your unencrypted - Borg key, nor your unencrypted files. Chunking and ID generation is + Borg key, nor your unencrypted files. Chunking and ID generation are based on your key to improve privacy. **About hardware acceleration:** Borg encrypts data with AES, which is pretty fast thanks to hardware acceleration on basically all modern Intel, AMD, and ARM CPUs since - around the early 2010's (very cheap models since the mid 2010's). + around the early 2010s (very cheap models since the mid-2010s). - As hashing algorithm Borg can either use SHA256, or BLAKE2b. ARM CPUs + As the hashing algorithm, Borg can use either SHA256 or BLAKE2b. ARM CPUs support hardware-accelerated SHA256 hashing since ARMv7 with NEON (around 2011), or ARMv8 (around 2013). AMD CPUs support it since Zen 1 (around 2017), i.e. all AMD Ryzen CPUs. Intel CPUs support it since @@ -4712,7 +4712,7 @@ class Archiver: compatible with Borg 1.1 and later. ``none`` mode uses no encryption and no authentication. It uses SHA256 - as chunk ID hash. This mode is not recommended. You should rather + as chunk ID hash. This mode is not recommended. You should instead consider using an authenticated or authenticated/encrypted mode. This mode has possible denial-of-service issues when running ``borg create`` on contents controlled by an attacker. See above for alternatives. From b22cc77453cba52094cc4b42d0c0d1f44f2424a8 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 29 Oct 2025 12:53:46 +0100 Subject: [PATCH 4/6] better clarity, generalisation, precision, less typos --- src/borg/archiver.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index b0b00ddcc..462c7eca4 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -4544,7 +4544,7 @@ class Archiver: know the passphrase. 6. Use the Borg key to decrypt and thus access the data stored in your repository, e.g. when extracting files. The contents can also be - verified to detect accidental or malicious tampering. + verified to detect accidental corruption or malicious tampering. As you can see, you always need *both* the Borg key and passphrase to access your data. Thus it's crucial to keep a backup of your key @@ -4582,8 +4582,8 @@ class Archiver: Make sure you use a good passphrase. Not too short, not too simple. The real encryption / decryption key is encrypted with / locked by your passphrase. - If an attacker gets your key, they can't unlock and use it without knowing the - passphrase. + If an attacker gets your borg key, they can't unlock and use it without knowing + the passphrase. Be careful with special or non-ASCII characters in your passphrase: @@ -4634,7 +4634,7 @@ class Archiver: Avoid using ``none`` mode. If you think about using ``none`` mode, please reconsider and be absolutely sure. Using any mode other than - ``none`` allows Borg to detect accidental or malicious tampering with + ``none`` allows Borg to detect accidental corruption or malicious tampering with the repo. It also prevents denial-of-service attacks against clients. Instead of ``none`` mode, you likely want to use ``authenticated`` mode, or ``repokey`` or ``keyfile`` modes with an empty passphrase @@ -4649,14 +4649,14 @@ class Archiver: If you just don't want to choose a passphrase, use ``keyfile`` or ``keyfile-blake2`` modes with an empty passphrase. These modes are generally safe even without a passphrase, but keeping an offsite - backup of the Borg key is especially important then. See below for + backup of the Borg key is also important then. See below for details. If you can assure that an attacker can't gain access to your repo, - e.g. when independently encrypting your repo with LUKS/dm-crypt, you + e.g. when independently encrypting your repository disk or filesystem, you can think about using ``repokey`` or ``repokey-blake2`` modes with an empty passphrase. However, keep in mind that if an attacker still - somehow manages to gain access, he has full access to your repo. In + somehow manages to gain access, they have full access to your repo. In such situations choosing ``repokey`` over ``authenticated`` mode has the advantage of allowing you to add a passphrase later using :ref:`borg_key_change-passphrase`. @@ -4677,15 +4677,15 @@ class Archiver: With ``keyfile`` and ``keyfile-blake2`` modes the key is stored on your local machine (in ``~/.config/borg/keys``) instead. An attacker gaining access to your repo then needs both the Borg key, and your - passphrase to access and tamper with the repo. However, if you loose - the key, you loose access to the repo, too. You **must** create an + passphrase to access and tamper with the repo. However, if you lose + the key, you lose access to the repo, too. You **must** create an offsite backup of your Borg key, e.g. by printing it on paper. Storing a copy of the Borg key on the system you're creating backups of is **NOT** sufficient. Use :ref:`borg_key_export` to create the backup. The ``keyfile`` and ``keyfile-blake2`` modes allow for "passphrase and having-the-key" security when using a strong passphrase, but can also - be used with an empty passphrase. Storing a passphrase on the disk of + be used with an empty passphrase. Storing a (easily readable) passphrase on the disk of the system you're backing up with ``keyfile`` and ``keyfile-blake2`` modes adds no security over using an empty passphrase. @@ -4693,7 +4693,7 @@ class Archiver: ``repokey`` and ``keyfile`` use AES-CTR-256 for encryption and HMAC-SHA256 for authentication in an encrypt-then-MAC (EtM) - construction. The chunk ID hash is HMAC-SHA256 as well (with a + construction. The chunk ID hash is HMAC-SHA256 (with a separate key). These modes are compatible with all Borg versions. ``repokey-blake2`` and ``keyfile-blake2`` are also authenticated From 9226d9c6a9b27f6e949234045f293ed99ac2268c Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 29 Oct 2025 13:26:31 +0100 Subject: [PATCH 5/6] reformat init_epilog to 80chars wide --- src/borg/archiver.py | 97 +++++++++++++++++++++++--------------------- 1 file changed, 50 insertions(+), 47 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 462c7eca4..0e660d5f4 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -4509,8 +4509,9 @@ class Archiver: # borg init init_epilog = process_epilog(""" - This command initializes an empty repository. A repository is a filesystem - directory containing the deduplicated data from zero or more archives. + This command initializes an empty repository. A repository is a + filesystem directory containing the deduplicated data from zero or more + archives. Encryption mode TL;DR +++++++++++++++++++++ @@ -4518,8 +4519,8 @@ class Archiver: The encryption mode can only be configured when creating a new repository. You can neither configure encryption on a per-archive basis, nor change the encryption mode of an existing repository. You - should thus take possible future use into account when deciding on - an encryption mode. + should thus take possible future use into account when deciding on an + encryption mode. As a general rule of thumb, use ``repokey`` with a strong passphrase: @@ -4546,12 +4547,12 @@ class Archiver: repository, e.g. when extracting files. The contents can also be verified to detect accidental corruption or malicious tampering. - As you can see, you always need *both* the Borg key and passphrase - to access your data. Thus it's crucial to keep a backup of your key + As you can see, you always need *both* the Borg key and passphrase to + access your data. Thus it's crucial to keep a backup of your key *outside* both the repository and the system you create backups of. - You can easily run into a "leaving your keys inside your car" - situation otherwise. See :ref:`borg_key_export` to create a backup - of your key (e.g., by printing it on paper). + You can easily run into a "leaving your keys inside your car" situation + otherwise. See :ref:`borg_key_export` to create a backup of your key + (e.g., by printing it on paper). Encryption is done locally - i.e., if you back up to a remote machine, the remote machine neither sees your passphrase, nor your unencrypted @@ -4564,11 +4565,11 @@ class Archiver: acceleration on basically all modern Intel, AMD, and ARM CPUs since around the early 2010s (very cheap models since the mid-2010s). - As the hashing algorithm, Borg can use either SHA256 or BLAKE2b. ARM CPUs - support hardware-accelerated SHA256 hashing since ARMv7 with NEON + As the hashing algorithm, Borg can use either SHA256 or BLAKE2b. ARM + CPUs support hardware-accelerated SHA256 hashing since ARMv7 with NEON (around 2011), or ARMv8 (around 2013). AMD CPUs support it since Zen 1 - (around 2017), i.e. all AMD Ryzen CPUs. Intel CPUs support it since - Ice Lake on mobile (10th gen, around 2021), and Rocket Lake on desktop + (around 2017), i.e. all AMD Ryzen CPUs. Intel CPUs support it since Ice + Lake on mobile (10th gen, around 2021), and Rocket Lake on desktop (11th gen, around 2021). Very cheap models have received support a few years later. If your CPU doesn't support hardware-accelerated SHA256 hashing, you might want to give BLAKE2b hashing a try - it's likely @@ -4580,23 +4581,25 @@ class Archiver: Picking a passphrase ++++++++++++++++++++ - Make sure you use a good passphrase. Not too short, not too simple. The real - encryption / decryption key is encrypted with / locked by your passphrase. - If an attacker gets your borg key, they can't unlock and use it without knowing - the passphrase. + Make sure you use a good passphrase. Not too short, not too simple. The + real encryption / decryption key is encrypted with / locked by your + passphrase. If an attacker gets your borg key, they can't unlock and use + it without knowing the passphrase. Be careful with special or non-ASCII characters in your passphrase: - - Borg processes the passphrase as Unicode (and encodes it as UTF-8), - so it does not have problems dealing with even the strangest characters. - - BUT: that does not necessarily apply to your OS / VM / keyboard configuration. + - Borg processes the passphrase as Unicode (and encodes it as UTF-8), so + it does not have problems dealing with even the strangest characters. + - BUT: that does not necessarily apply to your OS / VM / keyboard + configuration. - So it is better to use a long passphrase made from simple ASCII characters than one that - includes non-ASCII characters or characters that are hard or impossible to enter on - a different keyboard layout. + So it is better to use a long passphrase made from simple ASCII + characters than one that includes non-ASCII characters or characters + that are hard or impossible to enter on a different keyboard layout. - You can change your passphrase for existing repositories at any time; it won't affect - the encryption/decryption key or other secrets. See :ref:`borg_key_change-passphrase`. + You can change your passphrase for existing repositories at any time; it + won't affect the encryption/decryption key or other secrets. See + :ref:`borg_key_change-passphrase`. More about encryption modes +++++++++++++++++++++++++++ @@ -4634,11 +4637,11 @@ class Archiver: Avoid using ``none`` mode. If you think about using ``none`` mode, please reconsider and be absolutely sure. Using any mode other than - ``none`` allows Borg to detect accidental corruption or malicious tampering with - the repo. It also prevents denial-of-service attacks against clients. - Instead of ``none`` mode, you likely want to use ``authenticated`` - mode, or ``repokey`` or ``keyfile`` modes with an empty passphrase - instead (see below). + ``none`` allows Borg to detect accidental corruption or malicious + tampering with the repo. It also prevents denial-of-service attacks + against clients. Instead of ``none`` mode, you likely want to use + ``authenticated`` mode, or ``repokey`` or ``keyfile`` modes with an + empty passphrase instead (see below). If you don't want to encrypt your data, use ``authenticated`` or ``authenticated-blake2`` modes. These modes require a passphrase in @@ -4649,11 +4652,10 @@ class Archiver: If you just don't want to choose a passphrase, use ``keyfile`` or ``keyfile-blake2`` modes with an empty passphrase. These modes are generally safe even without a passphrase, but keeping an offsite - backup of the Borg key is also important then. See below for - details. + backup of the Borg key is also important then. See below for details. - If you can assure that an attacker can't gain access to your repo, - e.g. when independently encrypting your repository disk or filesystem, you + If you can assure that an attacker can't gain access to your repo, e.g. + when independently encrypting your repository disk or filesystem, you can think about using ``repokey`` or ``repokey-blake2`` modes with an empty passphrase. However, keep in mind that if an attacker still somehow manages to gain access, they have full access to your repo. In @@ -4674,27 +4676,28 @@ class Archiver: system you're backing up, consider using the ``keyfile`` method instead. It generally provides the same or better security then. - With ``keyfile`` and ``keyfile-blake2`` modes the key is stored on - your local machine (in ``~/.config/borg/keys``) instead. An attacker - gaining access to your repo then needs both the Borg key, and your - passphrase to access and tamper with the repo. However, if you lose - the key, you lose access to the repo, too. You **must** create an - offsite backup of your Borg key, e.g. by printing it on paper. Storing - a copy of the Borg key on the system you're creating backups of is - **NOT** sufficient. Use :ref:`borg_key_export` to create the backup. + With ``keyfile`` and ``keyfile-blake2`` modes the key is stored on your + local machine (in ``~/.config/borg/keys``) instead. An attacker gaining + access to your repo then needs both the Borg key, and your passphrase to + access and tamper with the repo. However, if you lose the key, you lose + access to the repo, too. You **must** create an offsite backup of your + Borg key, e.g. by printing it on paper. Storing a copy of the Borg key + on the system you're creating backups of is **NOT** sufficient. Use + :ref:`borg_key_export` to create the backup. The ``keyfile`` and ``keyfile-blake2`` modes allow for "passphrase and having-the-key" security when using a strong passphrase, but can also - be used with an empty passphrase. Storing a (easily readable) passphrase on the disk of - the system you're backing up with ``keyfile`` and ``keyfile-blake2`` - modes adds no security over using an empty passphrase. + be used with an empty passphrase. Storing a (easily readable) + passphrase on the disk of the system you're backing up with + ``keyfile`` and ``keyfile-blake2`` modes adds no security over using an + empty passphrase. **Technical details:** ``repokey`` and ``keyfile`` use AES-CTR-256 for encryption and HMAC-SHA256 for authentication in an encrypt-then-MAC (EtM) - construction. The chunk ID hash is HMAC-SHA256 (with a - separate key). These modes are compatible with all Borg versions. + construction. The chunk ID hash is HMAC-SHA256 (with a separate key). + These modes are compatible with all Borg versions. ``repokey-blake2`` and ``keyfile-blake2`` are also authenticated encryption modes, but use BLAKE2b-256 instead of HMAC-SHA256 for From 3edf5b347595d77efef75e37d45ba83570876506 Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Wed, 29 Oct 2025 17:48:14 +0100 Subject: [PATCH 6/6] Docs: Improve `borg init` encryption table formatting --- docs/borg_theme/css/borg.css | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/borg_theme/css/borg.css b/docs/borg_theme/css/borg.css index 36463d657..eed1488ab 100644 --- a/docs/borg_theme/css/borg.css +++ b/docs/borg_theme/css/borg.css @@ -131,6 +131,17 @@ table.docutils.borg-options-table tr td:first-child:not([colspan="3"]) { text-align: center; } +.borg-encryption-table th, +.borg-encryption-table td { + vertical-align: top; +} + +.borg-encryption-table .literal { + display: block; + margin: 0; + white-space: normal; +} + kbd, /* used in usage pages for options */ code, .rst-content tt.literal,