upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-04-08 10:26:24 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge pull request #9103 from PhrozenByte/docs-repokey-change-passphrase
Some checks are pending
CI / lint (push) Waiting to run
Details
CI / pytest (push) Blocked by required conditions
Details
CodeQL / Analyze (push) Waiting to run
Details
Windows CI / msys2-ucrt64 (push) Waiting to run
Details

Browse source 
Docs: Rewrite `borg init --encryption` docs
This commit is contained in:
TW 2025-10-29 19:24:45 +01:00 committed by GitHub
commit 83d9d28fa4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 197 additions and 98 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
docs/borg_theme/css/borg.css
View file

@ -122,10 +122,26 @@ 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;
}
.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,

2
docs/usage/general/environment.rst.inc
View file

@ -1,3 +1,5 @@
.. _environment-variables:
Environment Variables
~~~~~~~~~~~~~~~~~~~~~

275
src/borg/archiver.py
View file

@ -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):
@ -4507,138 +4509,217 @@ 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 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 on 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 corruption 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 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 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 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
(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
++++++++++++++++++++
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.
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.
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 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 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).
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 also 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 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
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 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.
**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.
``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 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.
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,