Document the new encryption of secrets feature in secretencryption.rst. Signed-off-by: Arun Menon <armenon@redhat.com> --- docs/drvsecret.rst | 4 ++ docs/meson.build | 1 + docs/secretencryption.rst | 105 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 110 insertions(+) create mode 100644 docs/secretencryption.rst diff --git a/docs/drvsecret.rst b/docs/drvsecret.rst index 76a9097d2b..234551d5ae 100644 --- a/docs/drvsecret.rst +++ b/docs/drvsecret.rst @@ -63,3 +63,7 @@ the traditional system or session libvirt connections to QEMU. Normal practice would be to open the secret driver in embedded mode any time one of the other drivers is opened in embedded mode so that the two drivers can interact in-process. + +Further reading +---------------------------- +- `Secret Encryption <secretencryption.html>`__ diff --git a/docs/meson.build b/docs/meson.build index 21e0b19c25..0e74f9c4bf 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -97,6 +97,7 @@ docs_rst_files = [ 'programming-languages', 'python', 'remote', + 'secretencryption', 'securityprocess', 'ssh-proxy', 'storage', diff --git a/docs/secretencryption.rst b/docs/secretencryption.rst new file mode 100644 index 0000000000..4908339f2d --- /dev/null +++ b/docs/secretencryption.rst @@ -0,0 +1,105 @@ +.. role:: since + +============================= +Secret storage and encryption +============================= + +.. contents:: + +The secret objects can either be ephemeral or persistent. +Ephemeral secrets are only kept in memory, never stored persistently on the disk. +See `Secrets <formatsecret.html>`__ + +:since:`Since 12.1.0` if a secret is defined as persistent, then it is stored **encrypted** on the disk. + + +Systemd Credentials Sealing +--------------------------- + +Out of the box, secrets are sealed using systemd credentials. This ties the +encrypted secret files to the specific host. + +The `virt-secret-init-encryption` service automatically generates a random +32-byte key and encrypts it using `systemd-creds`, storing the result in +`/var/lib/libvirt/secrets/secrets-encryption-key`. The `virtsecretd` service +then automatically loads this key securely via the systemd `LoadCredentialEncrypted` +mechanism. + +Disabling Systemd Credentials +----------------------------- + +You can control encryption behavior by editing the `secret.conf` configuration +file located in ``@SYSCONFDIR@/libvirt/secret.conf`` or ``$XDG_CONFIG_HOME/libvirt/secret.conf`` +depending on how the daemon was started (system mode or session mode respectively). + +To **disable encryption entirely** (which effectively disables the use of any +systemd credentials for this purpose): + +:: + + encrypt_data = 0 + +Setting ``encrypt_data = 0`` takes precedence over any available systemd +credentials. If you have existing encrypted secrets, this setting will prevent +the secret driver from loading the encryption key, making those secrets +inaccessible. New or updated secrets will be stored in plain base64 format. + +To **use a custom encryption key** instead of the systemd credential. +Defining a custom key path takes precedence over the systemd credential + +:: + + secrets_encryption_key = "/path/to/custom/key" + +Configuring Encryption on Non-Systemd Hosts +------------------------------------------- + +On hosts without systemd, or if you prefer to manage the key manually, you can +create a raw encryption key and configure libvirt to use it. + +Generate a random 32-byte key: + +:: + + dd if=/dev/random of=/path/to/key/file bs=32 count=1 + +Update `secret.conf` to point to this key: + +:: + + secrets_encryption_key = "/path/to/key/file" + +Manual Systemd Credential Creation +---------------------------------- + +If you want to use systemd credentials but need to customize the encryption parameters +(for example, to specify which TPM PCRs to bind to), you can generate the +credential file manually. + +To create the default `/var/lib/libvirt/secrets/secrets-encryption-key` manually +using `systemd-creds` (adjusting arguments to `systemd-creds encrypt` as needed): + +:: + + dd if=/dev/random bs=32 count=1 | \ + systemd-creds encrypt --name=secrets-encryption-key - \ + /var/lib/libvirt/secrets/secrets-encryption-key + +You can pass extra arguments to `systemd-creds encrypt <https://www.freedesktop.org/software/systemd/man/latest/systemd-creds.html?#encrypt%20input%7C-%20output%7C->`__, +such as ``--tpm2-device=...`` or ``--tpm2-pcrs=...``, to customize the sealing policy. + +Upgrading Libvirt for secret encryption +--------------------------------------- +Starting 12.1.0, secrets can be stored on the disk in an encrypted format, rather than +the default base64 encoding. + +Any secret created before upgrading libvirt, remain stored in their original base64 +format on the disk. +A pre-existing secret will only be encrypted if you explicitly update its value using +**virsh secret-set-value** after the upgrade, provided that encryption is enabled in +secret.conf configuration file. + +It is important to note that encrypted secrets are not backwards compatible. In case of +a downgrade to an older version of libvirt, the encrypted secrets will not be loaded from +the disk. Therefore, before reverting to an older version libvirt, make sure that all the +secrets have been reverted to the standard base64 format, to avoid service disruptions. -- 2.51.1