mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-23 14:15:28 +00:00
169 lines
7.2 KiB
XML
169 lines
7.2 KiB
XML
<?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>,
|
|
and <code>luks</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 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>
|
|
<p>
|
|
<code><encryption format="default"/></code> can be specified only
|
|
when creating a qcow volume. If the volume is successfully created, the
|
|
encryption formats, parameters and secrets will be auto-generated by
|
|
libvirt and the attached <code>encryption</code> tag will be updated.
|
|
The unmodified contents of the <code>encryption</code> tag can be used
|
|
in later operations with the volume, or when setting up a domain that
|
|
uses the volume.
|
|
</p>
|
|
<h3><a id="StorageEncryptionQcow">"qcow" format</a></h3>
|
|
<p>
|
|
The <code>qcow</code> format specifies that the built-in encryption
|
|
support in <code>qcow</code>- or <code>qcow2</code>-formatted volume
|
|
images should be used. A single
|
|
<code><secret type='passphrase'></code> element is expected. If
|
|
the <code>secret</code> element is not present during volume creation,
|
|
a secret is automatically generated and attached to the volume.
|
|
</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>
|
|
|
|
|
|
<h2><a id="example">Examples</a></h2>
|
|
|
|
<p>
|
|
Here is a simple example, specifying use of the <code>qcow</code> format:
|
|
</p>
|
|
|
|
<pre>
|
|
<encryption format='qcow'>
|
|
<secret type='passphrase' uuid='c1f11a6d-8c5d-4a3e-ac7a-4e171c5e0d4a' />
|
|
</encryption></pre>
|
|
|
|
<p>
|
|
Assuming a <a href="formatsecret.html#VolumeUsageType">
|
|
<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:
|
|
</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>
|