From deab8ca7e230b004447441feca32ffc61c39c3c1 Mon Sep 17 00:00:00 2001 From: Marian Beermann Date: Tue, 17 May 2016 01:00:46 +0200 Subject: [PATCH] init: move epilogue from docs/usage into help output Also tell which algos are used and that HW accel is supported. --- borg/archiver.py | 43 ++++++++++++++++++++++++++++++++++++++++++- docs/usage.rst | 40 ---------------------------------------- 2 files changed, 42 insertions(+), 41 deletions(-) diff --git a/borg/archiver.py b/borg/archiver.py index 497f5cf99..8c9d018db 100644 --- a/borg/archiver.py +++ b/borg/archiver.py @@ -1167,7 +1167,48 @@ class Archiver: init_epilog = textwrap.dedent(""" This command initializes an empty repository. A repository is a filesystem directory containing the deduplicated data from zero or more archives. - Encryption can be enabled at repository init time. + + Encryption can be enabled at repository init time (the default). + + It is not recommended to disable encryption. Repository encryption protects you + e.g. against the case that an attacker has access to your backup repository. + + But be careful with the key / the passphrase: + + If you want "passphrase-only" security, use the repokey mode. The key will + be stored inside the repository (in its "config" file). In above mentioned + attack scenario, the attacker will have the key (but not the passphrase). + + If you want "passphrase and having-the-key" security, use the keyfile mode. + The key will be stored in your home directory (in .config/borg/keys). In + the attack scenario, the attacker who has just access to your repo won't have + the key (and also not the passphrase). + + Make a backup copy of the key file (keyfile mode) or repo config file + (repokey mode) and keep it at a safe place, so you still have the key in + case it gets corrupted or lost. Also keep the passphrase at a safe place. + The backup that is encrypted with that key won't help you with that, of course. + + 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, he 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. + + So better use a long passphrase made from simple ascii chars than one that + includes non-ascii stuff or characters that are hard/impossible to enter on + a different keyboard layout. + + You can change your passphrase for existing repos at any time, it won't affect + the encryption/decryption key or other secrets. + + When encrypting, AES-CTR-256 is used for encryption, and HMAC-SHA256 for + authentication. Hardware acceleration will be used automatically. """) subparser = subparsers.add_parser('init', parents=[common_parser], add_help=False, description=self.do_init.__doc__, epilog=init_epilog, diff --git a/docs/usage.rst b/docs/usage.rst index 7473e8597..d559c0bb0 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -236,46 +236,6 @@ Examples # Remote repository (store the key your home dir) $ borg init --encryption=keyfile user@hostname:backup -Important notes about encryption: - -It is not recommended to disable encryption. Repository encryption protects you -e.g. against the case that an attacker has access to your backup repository. - -But be careful with the key / the passphrase: - -If you want "passphrase-only" security, use the ``repokey`` mode. The key will -be stored inside the repository (in its "config" file). In above mentioned -attack scenario, the attacker will have the key (but not the passphrase). - -If you want "passphrase and having-the-key" security, use the ``keyfile`` mode. -The key will be stored in your home directory (in ``.config/borg/keys``). In -the attack scenario, the attacker who has just access to your repo won't have -the key (and also not the passphrase). - -Make a backup copy of the key file (``keyfile`` mode) or repo config file -(``repokey`` mode) and keep it at a safe place, so you still have the key in -case it gets corrupted or lost. Also keep the passphrase at a safe place. -The backup that is encrypted with that key won't help you with that, of course. - -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, he can't unlock and use it without knowing the -passphrase. - -Be careful with special or non-ascii characters in your passphrase: - -- |project_name| 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 better use a long passphrase made from simple ascii chars than one that -includes non-ascii stuff or characters that are hard/impossible to enter on -a different keyboard layout. - -You can change your passphrase for existing repos at any time, it won't affect -the encryption/decryption key or other secrets. - - .. include:: usage/create.rst.inc Examples