[pbs-devel] [PATCH pbs-docs] admin-guide: add section explaining master keys

[pbs-devel] [PATCH pbs-docs] admin-guide: add section explaining master keys

[Dylan Whyte]

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

[pbs-devel] applied: [PATCH pbs-docs] admin-guide: add section explaining master keys

[Dietmar Maurer]

applied, great!

I fixed one headline:

diff --git a/docs/administration-guide.rst b/docs/administration-guide.rst
index fd6052c..b98d4cb 100644
--- a/docs/administration-guide.rst
+++ b/docs/administration-guide.rst
@@ -697,7 +697,7 @@ You can avoid entering the passwords by setting the environment
 variables ``PBS_PASSWORD`` and ``PBS_ENCRYPTION_PASSWORD``.
 
 Using a master key to store and recover encryption keys
-^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


And moved the Encryption headline one level up, so that it is
visible in the TOC.


Please can you additionally add instructions where to store the 
private master key?. One should put that into the vault instead
of leaving it on the server.


> On 08/06/2020 12:03 PM Dylan Whyte <d.whyte@proxmox.com> wrote:
> 
>  
> 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
> 
> 
> 
> _______________________________________________
> pbs-devel mailing list
> pbs-devel@lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel