mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2025-01-03 11:35:19 +00:00
docs: Convert 'formatstorageencryption' page to rST
Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Erik Skultety <eskultet@redhat.com>
This commit is contained in:
Peter Krempa
parent
ca5ddcc748
commit
4dfbf28e6a
@ -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>
|
|
||||||
142
docs/formatstorageencryption.rst
Normal file
142
docs/formatstorageencryption.rst
Normal file
@ -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>
|
||||||
@ -28,7 +28,6 @@ docs_html_in_files = [
|
|||||||
'formatnode',
|
'formatnode',
|
||||||
'formatnwfilter',
|
'formatnwfilter',
|
||||||
'formatstoragecaps',
|
'formatstoragecaps',
|
||||||
'formatstorageencryption',
|
|
||||||
'hooks',
|
'hooks',
|
||||||
'index',
|
'index',
|
||||||
'internals',
|
'internals',
|
||||||
@ -88,6 +87,7 @@ docs_rst_files = [
|
|||||||
'formatsecret',
|
'formatsecret',
|
||||||
'formatsnapshot',
|
'formatsnapshot',
|
||||||
'formatstorage',
|
'formatstorage',
|
||||||
|
'formatstorageencryption',
|
||||||
'glib-adoption',
|
'glib-adoption',
|
||||||
'goals',
|
'goals',
|
||||||
'governance',
|
'governance',
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user