7:10 a.m.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
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