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) server-digest SHA256) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 17BC4697DE for ; Fri, 7 Aug 2020 07:15:11 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id E81FC21DA2 for ; Fri, 7 Aug 2020 07:15:10 +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) server-digest SHA256) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id 90A5521D94 for ; Fri, 7 Aug 2020 07:15:09 +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 6057F438A6 for ; Fri, 7 Aug 2020 07:15:09 +0200 (CEST) Date: Fri, 7 Aug 2020 07:14:57 +0200 (CEST) From: Dietmar Maurer To: Proxmox Backup Server development discussion , Dylan Whyte Message-ID: <1055772705.439.1596777298591@webmail.proxmox.com> In-Reply-To: <20200806100331.12257-1-d.whyte@proxmox.com> References: <20200806100331.12257-1-d.whyte@proxmox.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-Priority: 3 Importance: Normal X-Mailer: Open-Xchange Mailer v7.10.3-Rev19 X-Originating-Client: open-xchange-appsuite X-SPAM-LEVEL: Spam detection results: 0 AWL 0.097 Adjusted score from AWL reputation of From: address 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 URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [proxmox.com] Subject: [pbs-devel] applied: [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: Fri, 07 Aug 2020 05:15:11 -0000 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 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 > --- > 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