From: Dylan Whyte <d.whyte@proxmox.com>
To: pbs-devel@lists.proxmox.com
Subject: [pbs-devel] [PATCH pbs-docs] admin-guide: add section explaining master keys
Date: Thu, 6 Aug 2020 12:03:31 +0200 [thread overview]
Message-ID: <20200806100331.12257-1-d.whyte@proxmox.com> (raw)
Adds a section under encryption which goes into detail on how to
use a master key to store and recover backup encryption keys.
Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
---
docs/administration-guide.rst | 87 ++++++++++++++++++++++++++++++++++-
1 file changed, 86 insertions(+), 1 deletion(-)
diff --git a/docs/administration-guide.rst b/docs/administration-guide.rst
index b8ee4ade..fd6052c0 100644
--- a/docs/administration-guide.rst
+++ b/docs/administration-guide.rst
@@ -677,6 +677,8 @@ extra protection, you can also create it without a password:
# proxmox-backup-client key create /path/to/my-backup.key --kdf none
+Having created this key, it is now possible to create an encrypted backup, by
+passing the ``--keyfile`` parameter, with the path to the key file.
.. code-block:: console
@@ -685,12 +687,95 @@ extra protection, you can also create it without a password:
Encryption Key Password: **************
...
+.. Note:: If you do not specify the name of the backup key, the key will be
+ created in the default location
+ ``~/.config/proxmox-backup/encryption-key.json``. ``proxmox-backup-client``
+ will also search this location by default, in case the ``--keyfile``
+ parameter is not specified.
You can avoid entering the passwords by setting the environment
variables ``PBS_PASSWORD`` and ``PBS_ENCRYPTION_PASSWORD``.
-.. todo:: Explain master-key
+Using a master key to store and recover encryption keys
+^^^^^^^^^^
+
+You can also use ``proxmox-backup-client key`` to create an RSA public/private
+key pair, which can be used to store an encrypted version of the symmetric
+backup encryption key alongside each backup and recover it later.
+
+To set up a master key:
+
+1. Create an encryption key for the backup:
+
+ .. code-block:: console
+
+ # proxmox-backup-client key create
+ creating default key at: "~/.config/proxmox-backup/encryption-key.json"
+ Encryption Key Password: **********
+ ...
+
+ The resulting file will be saved to ``~/.config/proxmox-backup/encryption-key.json``.
+
+2. Create an RSA public/private key pair:
+
+ .. code-block:: console
+
+ # proxmox-backup-client key create-master-key
+ Master Key Password: *********
+ ...
+
+ This will create two files in your current directory, ``master-public.pem``
+ and ``master-private.pem``.
+
+3. Import the newly created ``master-public.pem`` public certificate, so that
+ ``proxmox-backup-client`` can find and use it upon backup.
+
+ .. code-block:: console
+
+ # proxmox-backup-client key import-master-pubkey /path/to/master-public.pem
+ Imported public master key to "~/.config/proxmox-backup/master-public.pem"
+
+4. With all these files in place, run a backup job:
+
+ .. code-block:: console
+
+ # proxmox-backup-client backup etc.pxar:/etc
+
+ The key will be stored in your backup, under the name ``rsa-encrypted.key``.
+
+ .. Note:: The ``--keyfile`` parameter can be excluded, if the encryption key
+ is in the default path. If you specified another path upon creation, you
+ must pass the ``--keyfile`` parameter.
+
+5. To test that everything worked, you can restore the key from the backup:
+
+ .. code-block:: console
+
+ # proxmox-backup-client restore /path/to/backup/ rsa-encrypted.key /path/to/target
+
+ .. Note:: You should not need an encryption key to extract this file. However, if
+ a key exists at the default location
+ (``~/.config/proxmox-backup/encryption-key.json``) the program will prompt
+ you for an encryption key password. Simply moving ``encryption-key.json``
+ out of this directory will fix this issue.
+
+6. Then, use the previously generated master key to decrypt the file:
+
+ .. code-block:: console
+
+ # openssl rsautl -decrypt -inkey master-private.pem -in rsa-encrypted.key -out /path/to/target
+ Enter pass phrase for ./master-private.pem: *********
+
+7. The target file will now contain the encryption key information in plain
+ text. The success of this can be confirmed by passing the resulting ``json``
+ file, with the ``--keyfile`` parameter, when decrypting files from the backup.
+.. warning:: Without their key, backed up files will be inaccessible. Thus, you should
+ keep keys ordered and in a place that is separate from the contents being
+ backed up. It can happen, for example, that you back up an entire system, using
+ a key on that system. If the system then becomes inaccessable for any reason
+ and needs to be restored, this will not be possible as the encryption key will be
+ lost along with the broken system.
Restoring Data
~~~~~~~~~~~~~~
--
2.20.1
next reply other threads:[~2020-08-06 10:04 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-08-06 10:03 Dylan Whyte [this message]
2020-08-07 5:14 ` [pbs-devel] applied: " Dietmar Maurer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200806100331.12257-1-d.whyte@proxmox.com \
--to=d.whyte@proxmox.com \
--cc=pbs-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox