From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 97D7F69641 for ; Thu, 6 Aug 2020 12:04:17 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 87AD41BA82 for ; Thu, 6 Aug 2020 12:03:47 +0200 (CEST) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [212.186.127.180]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id B34B31BA7A for ; Thu, 6 Aug 2020 12:03:46 +0200 (CEST) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 7054743945 for ; Thu, 6 Aug 2020 12:03:41 +0200 (CEST) From: Dylan Whyte To: pbs-devel@lists.proxmox.com Date: Thu, 6 Aug 2020 12:03:31 +0200 Message-Id: <20200806100331.12257-1-d.whyte@proxmox.com> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pbs-devel] [PATCH pbs-docs] admin-guide: add section explaining master keys X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 06 Aug 2020 10:04:17 -0000 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 --- 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