Repository: borgbackup/borg

Issue:
update docs bounty (44)
there are quite some docs issues: https://github.com/borgbackup/borg/labels/documentation

grab some doc update issues, create a PR against master (and, after discussion, also to 1.2-maint and 1.1-maint, if applicable, see here, also linked from PR submission template)

the bounty is for fixing 2 small issues or 1 bigger issue.
docs issues that already have a bounty on them do not qualify.


---

:moneybag: [there is a bounty for this](https://app.bountysource.com/issues/106643669-update-docs-bounty-44)


Discussion:

Resolving patch:
diff --git a/setup_docs.py b/setup_docs.py
--- a/setup_docs.py
+++ b/setup_docs.py
@@ -302,6 +302,8 @@ class build_man(Command):
         'with-lock': 'lock',
 
         'key_change-passphrase': 'key',
+        'key_change-location': 'key',
+        'key_change-algorithm': 'key',
         'key_export': 'key',
         'key_import': 'key',
         'key_migrate-to-repokey': 'key',
@@ -310,6 +312,7 @@ class build_man(Command):
         'import-tar': 'tar',
 
         'benchmark_crud': 'benchmark',
+        'benchmark_cpu': 'benchmark',
 
         'umount': 'mount',
     }
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -4248,10 +4248,11 @@ def define_borg_mount(parser):
 
         1. Ask you to come up with a passphrase.
         2. Create a borg key (which contains some 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).
+        3. Derive a "key encryption key" from your passphrase
+        4. Encrypt and sign the key with the key encryption key
+        5. 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
+        6. 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`).
@@ -4259,7 +4260,7 @@ def define_borg_mount(parser):
            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
+        7. 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.
 
         Picking a passphrase
@@ -4330,6 +4331,25 @@ def define_borg_mount(parser):
 
         If you do **not** want to encrypt the contents of your backups, but still want to detect
         malicious tampering use an `authenticated` mode. It's like `repokey` minus encryption.
+
+        Key derivation functions
+        ++++++++++++++++++++++++
+
+        - ``--key-algorithm argon2`` is the default and is recommended.
+          The key encryption key is derived from your passphrase via argon2-id.
+          Argon2 is considered more modern and secure than pbkdf2.
+
+        - You can use ``--key-algorithm pbkdf2`` if you want to access your repo via old versions of borg.
+
+        Our implementation of argon2-based key algorithm follows the cryptographic best practices:
+
+        - It derives two separate keys from your passphrase: one to encrypt your key and another one
+          to sign it. ``--key-algorithm pbkdf2`` uses the same key for both.
+
+        - It uses encrypt-then-mac instead of encrypt-and-mac used by ``--key-algorithm pbkdf2``
+
+        Neither is inherently linked to the key derivation function, but since we were going
+        to break backwards compatibility anyway we took the opportunity to fix all 3 issues at once.
         """)
         subparser = subparsers.add_parser('init', parents=[common_parser], add_help=False,
                                           description=self.do_init.__doc__, epilog=init_epilog,
@@ -4352,7 +4372,8 @@ def define_borg_mount(parser):
                                help='Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.')
         subparser.add_argument('--make-parent-dirs', dest='make_parent_dirs', action='store_true',
                                help='create the parent directories of the repository directory, if they are missing.')
-        subparser.add_argument('--key-algorithm', dest='key_algorithm', default='argon2', choices=list(KEY_ALGORITHMS))
+        subparser.add_argument('--key-algorithm', dest='key_algorithm', default='argon2', choices=list(KEY_ALGORITHMS),
+                               help='the algorithm we use to derive a key encryption key from your passphrase. Default: argon2')
 
         # borg key
         subparser = subparsers.add_parser('key', parents=[mid_common_parser], add_help=False,
@@ -4486,15 +4507,33 @@ def define_borg_mount(parser):
         change_algorithm_epilog = process_epilog("""
         Change the algorithm we use to encrypt and authenticate the borg key.
 
+        Important: In a `repokey` mode (e.g. repokey-blake2) all users share the same key.
+        In this mode upgrading to `argon2` will make it impossible to access the repo for users who use an old version of borg.
+        We recommend upgrading to the latest stable version.
+
+        Important: In a `keyfile` mode (e.g. keyfile-blake2) each user has their own key (in ``~/.config/borg/keys``).
+        In this mode this command will only change the key used by the current user.
+        If you want to upgrade to `argon2` to strengthen security, you will have to upgrade each user's key individually.
+
         Your repository is encrypted and authenticated with a key that is randomly generated by ``borg init``.
         The key is encrypted and authenticated with your passphrase.
 
         We currently support two choices:
+
         1. argon2 - recommended. This algorithm is used by default when initialising a new repository.
            The key encryption key is derived from your passphrase via argon2-id.
            Argon2 is considered more modern and secure than pbkdf2.
-        1. pbkdf2 - the legacy algorithm. Use this if you want to access your repo via old versions of borg.
+        2. pbkdf2 - the legacy algorithm. Use this if you want to access your repo via old versions of borg.
            The key encryption key is derived from your passphrase via PBKDF2-HMAC-SHA256.
+
+        Examples::
+
+            # Upgrade an existing key to argon2
+            borg key change-algorithm /path/to/repo argon2
+            # Downgrade to pbkdf2 - use this if upgrading borg is not an option
+            borg key change-algorithm /path/to/repo pbkdf2
+
+
         """)
         subparser = key_parsers.add_parser('change-algorithm', parents=[common_parser], add_help=False,
                                            description=self.do_change_algorithm.__doc__,


Test patch: