1
0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-23 21:34:54 +03:00
libvirt/docs/formatstorageencryption.html.in
John Ferlan 47e88b33be util: Add 'usage' for encryption
In order to use more common code and set up for a future type, modify the
encryption secret to allow the "usage" attribute or the "uuid" attribute
to define the secret. The "usage" in the case of a volume secret would be
the path to the volume as dictated by the backwards compatibility brought
on by virStorageGenerateQcowEncryption where it set up the usage field as
the vol->target.path and didn't allow someone to provide it. This carries
into virSecretObjListFindByUsageLocked which takes the secret usage attribute
value from from the domain disk definition and compares it against the
usage type from the secret definition. Since none of the code dealing
with qcow/qcow2 encryption secrets uses usage for lookup, it's a mostly
cosmetic change. The real usage comes in a future path where the encryption
is expanded to be a luks volume and the secret will allow definition of
the usage field.

This code will make use of the virSecretLookup{Parse|Format}Secret common code.

Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-01 15:46:24 -04:00

72 lines
3.2 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<body>
<h1>Storage volume encryption XML format</h1>
<ul id="toc"></ul>
<h2><a name="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> and <code>qcow</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>passphrase</code>. The
<code>uuid</code> is "uuid" of the <code>secret</code> while
<code>usage</code> is the value "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 name="StorageEncryptionDefault">"default" format</a></h3>
<p>
<code>&lt;encryption format="default"/&gt;</code> can be specified only
when creating a 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 name="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>&lt;secret type='passphrase'&gt;</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>
<h2><a name="example">Example</a></h2>
<p>
Here is a simple example, specifying use of the <code>qcow</code> format:
</p>
<pre>
&lt;encryption format='qcow'&gt;
&lt;secret type='passphrase' uuid='c1f11a6d-8c5d-4a3e-ac7a-4e171c5e0d4a' /&gt;
&lt;/encryption&gt;</pre>
</body>
</html>