Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- docs/formatstorageencryption.html.in | 181 --------------------------- docs/formatstorageencryption.rst | 142 +++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 143 insertions(+), 182 deletions(-) delete mode 100644 docs/formatstorageencryption.html.in create mode 100644 docs/formatstorageencryption.rst diff --git a/docs/formatstorageencryption.html.in b/docs/formatstorageencryption.html.in deleted file mode 100644 index 395a7269b1..0000000000 --- a/docs/formatstorageencryption.html.in +++ /dev/null @@ -1,181 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml";> - <body> - <h1>Storage volume encryption XML format</h1> - - <ul id="toc"></ul> - - <h2><a id="StorageEncryption">Storage volume encryption XML</a></h2> - - <p> - Storage volumes may be encrypted, the XML snippet described below is used - to represent the details of the encryption. It can be used as a part - of a domain or storage configuration. - </p> - <p> - The top-level tag of volume encryption specification - is <code>encryption</code>, with a mandatory - attribute <code>format</code>. Currently defined values - of <code>format</code> are <code>default</code>, <code>qcow</code>, - <code>luks</code>, and <code>luks2</code>. - Each value of <code>format</code> implies some expectations about the - content of the <code>encryption</code> tag. Other format values may be - defined in the future. - </p> - <p> - The <code>encryption</code> tag supports an optional <code>engine</code> - tag, which allows selecting which component actually handles - the encryption. Currently defined values of <code>engine</code> are - <code>qemu</code> and <code>librbd</code>. - Both <code>qemu</code> and <code>librbd</code> require using the qemu - driver. - The <code>librbd</code> engine requires qemu version >= 6.1.0, both - ceph cluster and librbd1 >= 16.1.0, and is only applicable for RBD - network disks. - If the engine tag is not specified, the <code>qemu</code> engine will be - used by default (assuming the qemu driver is used). - Note that <code>librbd</code> engine is currently only supported by the - qemu VM driver, and is not supported by the storage driver. Furthermore, - the storage driver currently ignores the <code>engine</code> tag. - </p> - <p> - The <code>encryption</code> tag can currently contain a sequence of - <code>secret</code> tags, each with mandatory attributes <code>type</code> - and either <code>uuid</code> or <code>usage</code> - (<span class="since">since 2.1.0</span>). The only currently defined - value of <code>type</code> is <code>volume</code>. The - <code>uuid</code> is "uuid" of the <code>secret</code> while - <code>usage</code> is the "usage" subelement field. - A secret value can be set in libvirt by the - <a href="html/libvirt-libvirt-secret.html#virSecretSetValue"> - <code>virSecretSetValue</code></a> API. Alternatively, if supported - by the particular volume format and driver, automatically generate a - secret value at the time of volume creation, and store it using the - specified <code>uuid</code>. - </p> - <h3><a id="StorageEncryptionDefault">"default" format</a></h3> - <h3><a id="StorageEncryptionQcow">"qcow" format</a></h3> - <p> - <span class="since">Since 4.5.0,</span> encryption formats - <code>default</code> and <code>qcow</code> may no longer be used - to create an encrypted volume. Usage of qcow encrypted volumes - in QEMU began phasing out in QEMU 2.3 and by QEMU 2.9 creation - of a qcow encrypted volume via qemu-img required usage of secret - objects, but that support was not added to libvirt. - </p> - <h3><a id="StorageEncryptionLuks">"luks" format</a></h3> - <p> - The <code>luks</code> format is specific to a luks encrypted volume - and the secret is used in order to either encrypt during volume creation - or decrypt the volume for usage by the domain. A single - <code><secret type='passphrase'...></code> element is expected. - <span class="since">Since 2.1.0</span>. - </p> - <p> - For volume creation, it is possible to specify the encryption - algorithm used to encrypt the luks volume. The following two - optional elements may be provided for that purpose. It is hypervisor - dependent as to which algorithms are supported. The default algorithm - used by the storage driver backend when using qemu-img to create - the volume is 'aes-256-cbc' using 'essiv' for initialization vector - generation and 'sha256' hash algorithm for both the cipher and the - initialization vector generation. - </p> - - <dl> - <dt><code>cipher</code></dt> - <dd>This element describes the cipher algorithm to be used to either - encrypt or decrypt the luks volume. This element has the following - attributes: - <dl> - <dt><code>name</code></dt> - <dd>The name of the cipher algorithm used for data encryption, - such as 'aes', 'des', 'cast5', 'serpent', 'twofish', etc. - Support of the specific algorithm is storage driver - implementation dependent.</dd> - <dt><code>size</code></dt> - <dd>The size of the cipher in bits, such as '256', '192', '128', - etc. Support of the specific size for a specific cipher is - hypervisor dependent.</dd> - <dt><code>mode</code></dt> - <dd>An optional cipher algorithm mode such as 'cbc', 'xts', - 'ecb', etc. Support of the specific cipher mode is - hypervisor dependent.</dd> - <dt><code>hash</code></dt> - <dd>An optional master key hash algorithm such as 'md5', 'sha1', - 'sha256', etc. Support of the specific hash algorithm is - hypervisor dependent.</dd> - </dl> - </dd> - <dt><code>ivgen</code></dt> - <dd>This optional element describes the initialization vector - generation algorithm used in conjunction with the - <code>cipher</code>. If the <code>cipher</code> is not provided, - then an error will be generated by the parser. - <dl> - <dt><code>name</code></dt> - <dd>The name of the algorithm, such as 'plain', 'plain64', - 'essiv', etc. Support of the specific algorithm is hypervisor - dependent.</dd> - <dt><code>hash</code></dt> - <dd>An optional hash algorithm such as 'md5', 'sha1', 'sha256', - etc. Support of the specific ivgen hash algorithm is hypervisor - dependent.</dd> - </dl> - </dd> - </dl> - - <h3><a id="StorageEncryptionLuks2">"luks2" format</a></h3> - <p> - The <code>luks2</code> format is currently supported only by the - <code>librbd</code> engine, and can only be applied to RBD network disks - (RBD images). - Since the <code>librbd</code> engine is currently not supported by the - libvirt storage driver, you cannot use it to control such disks. However, - pre-formatted RBD luks2 disks can be loaded to a qemu VM using the qemu - VM driver. - A single - <code><secret type='passphrase'...></code> element is expected. - </p> - - - <h2><a id="example">Examples</a></h2> - - <p> - Assuming a <a href="formatsecret.html#usage-type-volume"> - <code>luks volume type secret</code></a> is already defined, - a simple example specifying use of the <code>luks</code> format - for either volume creation without a specific cipher being defined or - as part of a domain volume definition: - </p> - <pre> -<encryption format='luks'> - <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/> -</encryption> - </pre> - - <p> - Here is an example specifying use of the <code>luks</code> format for - a specific cipher algorithm for volume creation. - <span class="since">Since 6.10.0,</span> the <code>target</code> format - can also support <code>qcow2</code> type with <code>luks</code> encryption. - </p> - <pre> -<volume> - <name>twofish.luks</name> - <capacity unit='G'>5</capacity> - <target> - <path>/var/lib/libvirt/images/demo.luks</path> - <format type='raw'/> - <encryption format='luks'> - <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/> - <cipher name='twofish' size='256' mode='cbc' hash='sha256'/> - <ivgen name='plain64' hash='sha256'/> - </encryption> - </target> -</volume> - </pre> - - </body> -</html> diff --git a/docs/formatstorageencryption.rst b/docs/formatstorageencryption.rst new file mode 100644 index 0000000000..7b5cccaf5e --- /dev/null +++ b/docs/formatstorageencryption.rst @@ -0,0 +1,142 @@ +.. role:: since + +==================================== +Storage volume encryption XML format +==================================== + +.. contents:: + +Storage volume encryption XML +----------------------------- + +Storage volumes may be encrypted, the XML snippet described below is used to +represent the details of the encryption. It can be used as a part of a domain or +storage configuration. + +The top-level tag of volume encryption specification is ``encryption``, with a +mandatory attribute ``format``. Currently defined values of ``format`` are +``default``, ``qcow``, ``luks``, and ``luks2``. Each value of ``format`` implies +some expectations about the content of the ``encryption`` tag. Other format +values may be defined in the future. + +The ``encryption`` tag supports an optional ``engine`` tag, which allows +selecting which component actually handles the encryption. Currently defined +values of ``engine`` are ``qemu`` and ``librbd``. Both ``qemu`` and ``librbd`` +require using the qemu driver. The ``librbd`` engine requires qemu version >= +6.1.0, both ceph cluster and librbd1 >= 16.1.0, and is only applicable for RBD +network disks. If the engine tag is not specified, the ``qemu`` engine will be +used by default (assuming the qemu driver is used). Note that ``librbd`` engine +is currently only supported by the qemu VM driver, and is not supported by the +storage driver. Furthermore, the storage driver currently ignores the ``engine`` +tag. + +The ``encryption`` tag can currently contain a sequence of ``secret`` tags, each +with mandatory attributes ``type`` and either ``uuid`` or ``usage`` ( +:since:`since 2.1.0` ). The only currently defined value of ``type`` is +``volume``. The ``uuid`` is "uuid" of the ``secret`` while ``usage`` is the +"usage" subelement field. A secret value can be set in libvirt by the +`virSecretSetValue <html/libvirt-libvirt-secret.html#virSecretSetValue>`__ API. +Alternatively, if supported by the particular volume format and driver, +automatically generate a secret value at the time of volume creation, and store +it using the specified ``uuid``. + +"default" format +~~~~~~~~~~~~~~~~ + +"qcow" format +~~~~~~~~~~~~~ + +:since:`Since 4.5.0,` encryption formats ``default`` and ``qcow`` may no longer +be used to create an encrypted volume. Usage of qcow encrypted volumes in QEMU +began phasing out in QEMU 2.3 and by QEMU 2.9 creation of a qcow encrypted +volume via qemu-img required usage of secret objects, but that support was not +added to libvirt. + +"luks" format +~~~~~~~~~~~~~ + +The ``luks`` format is specific to a luks encrypted volume and the secret is +used in order to either encrypt during volume creation or decrypt the volume for +usage by the domain. A single ``<secret type='passphrase'...>`` element is +expected. :since:`Since 2.1.0` . + +For volume creation, it is possible to specify the encryption algorithm used to +encrypt the luks volume. The following two optional elements may be provided for +that purpose. It is hypervisor dependent as to which algorithms are supported. +The default algorithm used by the storage driver backend when using qemu-img to +create the volume is 'aes-256-cbc' using 'essiv' for initialization vector +generation and 'sha256' hash algorithm for both the cipher and the +initialization vector generation. + +``cipher`` + This element describes the cipher algorithm to be used to either encrypt or + decrypt the luks volume. This element has the following attributes: + + ``name`` + The name of the cipher algorithm used for data encryption, such as 'aes', + 'des', 'cast5', 'serpent', 'twofish', etc. Support of the specific + algorithm is storage driver implementation dependent. + ``size`` + The size of the cipher in bits, such as '256', '192', '128', etc. Support + of the specific size for a specific cipher is hypervisor dependent. + ``mode`` + An optional cipher algorithm mode such as 'cbc', 'xts', 'ecb', etc. + Support of the specific cipher mode is hypervisor dependent. + ``hash`` + An optional master key hash algorithm such as 'md5', 'sha1', 'sha256', + etc. Support of the specific hash algorithm is hypervisor dependent. +``ivgen`` + This optional element describes the initialization vector generation + algorithm used in conjunction with the ``cipher``. If the ``cipher`` is not + provided, then an error will be generated by the parser. + + ``name`` + The name of the algorithm, such as 'plain', 'plain64', 'essiv', etc. + Support of the specific algorithm is hypervisor dependent. + ``hash`` + An optional hash algorithm such as 'md5', 'sha1', 'sha256', etc. Support + of the specific ivgen hash algorithm is hypervisor dependent. + +"luks2" format +~~~~~~~~~~~~~~ + +The ``luks2`` format is currently supported only by the ``librbd`` engine, and +can only be applied to RBD network disks (RBD images). Since the ``librbd`` +engine is currently not supported by the libvirt storage driver, you cannot use +it to control such disks. However, pre-formatted RBD luks2 disks can be loaded +to a qemu VM using the qemu VM driver. A single +``<secret type='passphrase'...>`` element is expected. + +Examples +-------- + +Assuming a `luks volume type secret <formatsecret.html#VolumeUsageType>`__ is +already defined, a simple example specifying use of the ``luks`` format for +either volume creation without a specific cipher being defined or as part of a +domain volume definition: + +:: + + <encryption format='luks'> + <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/> + </encryption> + +Here is an example specifying use of the ``luks`` format for a specific cipher +algorithm for volume creation. :since:`Since 6.10.0,` the ``target`` format can +also support ``qcow2`` type with ``luks`` encryption. + +:: + + <volume> + <name>twofish.luks</name> + <capacity unit='G'>5</capacity> + <target> + <path>/var/lib/libvirt/images/demo.luks</path> + <format type='raw'/> + <encryption format='luks'> + <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/> + <cipher name='twofish' size='256' mode='cbc' hash='sha256'/> + <ivgen name='plain64' hash='sha256'/> + </encryption> + </target> + </volume> diff --git a/docs/meson.build b/docs/meson.build index b911292480..22eca7d8bd 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -25,7 +25,6 @@ docs_html_in_files = [ 'formatnetwork', 'formatnode', 'formatnwfilter', - 'formatstorageencryption', 'hooks', 'index', 'internals', @@ -88,6 +87,7 @@ docs_rst_files = [ 'formatsnapshot', 'formatstorage', 'formatstoragecaps', + 'formatstorageencryption', 'glib-adoption', 'goals', 'governance', -- 2.35.1
