External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-25 15:15:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
4074a82c0c
libvirt/docs/formatstorageencryption.html.in

173 lines
7.7 KiB
HTML
Raw Normal View History

Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-03 14:25:37 +00:00
<?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">
Add volume encryption information handling. Define an <encryption> tag specifying volume encryption format and format-depenedent parameters (e.g. passphrase, cipher name, key length, key). Currently the only defined parameter is a reference to a "secret" (passphrase/key) managed using the virSecret* API. Only the qcow/qcow2 encryption format, and a "default" format used to let libvirt choose the format during volume creation, is currently supported. This patch does not add any users; the <encryption> tag is added in the following patches to both volumes (to support encrypted volume creation) and domains. * docs/*.html: Re-generate * docs/formatstorageencryption.html.in, docs/sitemap.html.in: Add page describing storage encryption data format * docs/schemas/Makefile.am, docs/schemas/storageencryption.rng: Add RNG schema for storage encryption format * po/POTFILES.in: Add src/storage_encryption_conf.c * src/libvirt_private.syms: Export virStorageEncryption* functions * src/storage_encryption_conf.h, src/storage_encryption_conf.c: Internal helper APIs for dealing with storage encryption format * libvirt.spec.in, mingw32-libvirt.spec.in: Add storageencryption.rng RNG schema
2009-08-19 19:50:10 +00:00
<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>
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-05-30 11:47:46 +00:00
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
Add volume encryption information handling. Define an <encryption> tag specifying volume encryption format and format-depenedent parameters (e.g. passphrase, cipher name, key length, key). Currently the only defined parameter is a reference to a "secret" (passphrase/key) managed using the virSecret* API. Only the qcow/qcow2 encryption format, and a "default" format used to let libvirt choose the format during volume creation, is currently supported. This patch does not add any users; the <encryption> tag is added in the following patches to both volumes (to support encrypted volume creation) and domains. * docs/*.html: Re-generate * docs/formatstorageencryption.html.in, docs/sitemap.html.in: Add page describing storage encryption data format * docs/schemas/Makefile.am, docs/schemas/storageencryption.rng: Add RNG schema for storage encryption format * po/POTFILES.in: Add src/storage_encryption_conf.c * src/libvirt_private.syms: Export virStorageEncryption* functions * src/storage_encryption_conf.h, src/storage_encryption_conf.c: Internal helper APIs for dealing with storage encryption format * libvirt.spec.in, mingw32-libvirt.spec.in: Add storageencryption.rng RNG schema
2009-08-19 19:50:10 +00:00
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>.
docs: correct invalid xml * docs/internals.html.in: Fix xml errors. * docs/formatstorageencryption.html.in: Likewise. * docs/drvesx.html.in: Likewise. * docs/archnetwork.html.in: Likewise. * docs/logging.html.in: Likewise. * docs/drvvmware.html.in: Likewise. * docs/api.html.in: Likewise. * docs/formatnwfilter.html.in: Likewise. * docs/formatdomain.html.in: Likewise. * docs/windows.html.in: Likewise.
2011-04-01 22:02:10 +00:00
</p>
Add volume encryption information handling. Define an <encryption> tag specifying volume encryption format and format-depenedent parameters (e.g. passphrase, cipher name, key length, key). Currently the only defined parameter is a reference to a "secret" (passphrase/key) managed using the virSecret* API. Only the qcow/qcow2 encryption format, and a "default" format used to let libvirt choose the format during volume creation, is currently supported. This patch does not add any users; the <encryption> tag is added in the following patches to both volumes (to support encrypted volume creation) and domains. * docs/*.html: Re-generate * docs/formatstorageencryption.html.in, docs/sitemap.html.in: Add page describing storage encryption data format * docs/schemas/Makefile.am, docs/schemas/storageencryption.rng: Add RNG schema for storage encryption format * po/POTFILES.in: Add src/storage_encryption_conf.c * src/libvirt_private.syms: Export virStorageEncryption* functions * src/storage_encryption_conf.h, src/storage_encryption_conf.c: Internal helper APIs for dealing with storage encryption format * libvirt.spec.in, mingw32-libvirt.spec.in: Add storageencryption.rng RNG schema
2009-08-19 19:50:10 +00:00
<h3><a name="StorageEncryptionDefault">"default" format</a></h3>
<p>
docs: fix encryption format attribute in example The correct attribute name is 'format', not 'type'. https://bugzilla.redhat.com/show_bug.cgi?id=1139910
2014-09-10 07:25:40 +00:00
<code>&lt;encryption format="default"/&gt;</code> can be specified only
Add volume encryption information handling. Define an <encryption> tag specifying volume encryption format and format-depenedent parameters (e.g. passphrase, cipher name, key length, key). Currently the only defined parameter is a reference to a "secret" (passphrase/key) managed using the virSecret* API. Only the qcow/qcow2 encryption format, and a "default" format used to let libvirt choose the format during volume creation, is currently supported. This patch does not add any users; the <encryption> tag is added in the following patches to both volumes (to support encrypted volume creation) and domains. * docs/*.html: Re-generate * docs/formatstorageencryption.html.in, docs/sitemap.html.in: Add page describing storage encryption data format * docs/schemas/Makefile.am, docs/schemas/storageencryption.rng: Add RNG schema for storage encryption format * po/POTFILES.in: Add src/storage_encryption_conf.c * src/libvirt_private.syms: Export virStorageEncryption* functions * src/storage_encryption_conf.h, src/storage_encryption_conf.c: Internal helper APIs for dealing with storage encryption format * libvirt.spec.in, mingw32-libvirt.spec.in: Add storageencryption.rng RNG schema
2009-08-19 19:50:10 +00:00
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>
encryption: Add luks parsing for storageencryption Add parse and format of the luks/passphrase secret including tests for volume XML parsing. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-06-01 19:01:31 +00:00
<h3><a name="StorageEncryptionLuks">"luks" format</a></h3>
<p>
The <code>luks</code> format is specific to a luks encrypted volume
and the secret used in order to either encrypt or decrypt the volume.
A single <code>&lt;secret type='passphrase'...&gt;</code> element is
expected. The secret may be referenced via either a <code>uuid</code> or
<code>usage</code> attribute. One of the two must be present. When
present for volume creation, the secret will be used in order for
volume encryption. When present for domain usage, the secret will
be used as the passphrase to decrypt the volume.
<span class="since">Since 2.1.0</span>.
</p>
encryption: Add <cipher> and <ivgen> to encryption For a luks device, allow the configuration of a specific cipher to be used for encrypting the volume. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-06-01 23:21:26 +00:00
<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>
Add volume encryption information handling. Define an <encryption> tag specifying volume encryption format and format-depenedent parameters (e.g. passphrase, cipher name, key length, key). Currently the only defined parameter is a reference to a "secret" (passphrase/key) managed using the virSecret* API. Only the qcow/qcow2 encryption format, and a "default" format used to let libvirt choose the format during volume creation, is currently supported. This patch does not add any users; the <encryption> tag is added in the following patches to both volumes (to support encrypted volume creation) and domains. * docs/*.html: Re-generate * docs/formatstorageencryption.html.in, docs/sitemap.html.in: Add page describing storage encryption data format * docs/schemas/Makefile.am, docs/schemas/storageencryption.rng: Add RNG schema for storage encryption format * po/POTFILES.in: Add src/storage_encryption_conf.c * src/libvirt_private.syms: Export virStorageEncryption* functions * src/storage_encryption_conf.h, src/storage_encryption_conf.c: Internal helper APIs for dealing with storage encryption format * libvirt.spec.in, mingw32-libvirt.spec.in: Add storageencryption.rng RNG schema
2009-08-19 19:50:10 +00:00
encryption: Add luks parsing for storageencryption Add parse and format of the luks/passphrase secret including tests for volume XML parsing. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-06-01 19:01:31 +00:00
<h2><a name="example">Examples</a></h2>
Add volume encryption information handling. Define an <encryption> tag specifying volume encryption format and format-depenedent parameters (e.g. passphrase, cipher name, key length, key). Currently the only defined parameter is a reference to a "secret" (passphrase/key) managed using the virSecret* API. Only the qcow/qcow2 encryption format, and a "default" format used to let libvirt choose the format during volume creation, is currently supported. This patch does not add any users; the <encryption> tag is added in the following patches to both volumes (to support encrypted volume creation) and domains. * docs/*.html: Re-generate * docs/formatstorageencryption.html.in, docs/sitemap.html.in: Add page describing storage encryption data format * docs/schemas/Makefile.am, docs/schemas/storageencryption.rng: Add RNG schema for storage encryption format * po/POTFILES.in: Add src/storage_encryption_conf.c * src/libvirt_private.syms: Export virStorageEncryption* functions * src/storage_encryption_conf.h, src/storage_encryption_conf.c: Internal helper APIs for dealing with storage encryption format * libvirt.spec.in, mingw32-libvirt.spec.in: Add storageencryption.rng RNG schema
2009-08-19 19:50:10 +00:00
<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>
encryption: Add luks parsing for storageencryption Add parse and format of the luks/passphrase secret including tests for volume XML parsing. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-06-01 19:01:31 +00:00
<p>
encryption: Add <cipher> and <ivgen> to encryption For a luks device, allow the configuration of a specific cipher to be used for encrypting the volume. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-06-01 23:21:26 +00:00
Assuming a <a href="formatsecret.html#luksUsageType">
<code>luks secret</code></a> is already defined using a
<code>usage</code> element with an <code>name</code> of "luks_example",
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:
encryption: Add luks parsing for storageencryption Add parse and format of the luks/passphrase secret including tests for volume XML parsing. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-06-01 19:01:31 +00:00
</p>
<pre>
&lt;encryption format='luks'&gt;
&lt;secret type='passphrase' usage='luks_example'/&gt;
&lt;/encryption&gt;
</pre>
encryption: Add <cipher> and <ivgen> to encryption For a luks device, allow the configuration of a specific cipher to be used for encrypting the volume. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-06-01 23:21:26 +00:00
<p>
Here is an example, specifying use of the <code>luks</code> format for
a specific cipher algorihm for volume creation:
</p>
<pre>
&lt;volume&gt;
&lt;name&gt;twofish.luks&lt;/name&gt;
&lt;capacity unit='G'&gt;5&lt;/capacity&gt;
&lt;target&gt;
&lt;path&gt;/var/lib/libvirt/images/demo.luks&lt;/path&gt;
&lt;format type='luks'/&gt;
&lt;encryption format='luks'&gt;
&lt;secret type='passphrase' usage='luks_example'/&gt;
&lt;cipher name='twofish' size='256' mode='cbc' hash='sha256'/&gt;
&lt;ivgen name='plain64' hash='sha256'/&gt;
&lt;/encryption&gt;
&lt;/target&gt;
&lt;/volume&gt;
</pre>
Add volume encryption information handling. Define an <encryption> tag specifying volume encryption format and format-depenedent parameters (e.g. passphrase, cipher name, key length, key). Currently the only defined parameter is a reference to a "secret" (passphrase/key) managed using the virSecret* API. Only the qcow/qcow2 encryption format, and a "default" format used to let libvirt choose the format during volume creation, is currently supported. This patch does not add any users; the <encryption> tag is added in the following patches to both volumes (to support encrypted volume creation) and domains. * docs/*.html: Re-generate * docs/formatstorageencryption.html.in, docs/sitemap.html.in: Add page describing storage encryption data format * docs/schemas/Makefile.am, docs/schemas/storageencryption.rng: Add RNG schema for storage encryption format * po/POTFILES.in: Add src/storage_encryption_conf.c * src/libvirt_private.syms: Export virStorageEncryption* functions * src/storage_encryption_conf.h, src/storage_encryption_conf.c: Internal helper APIs for dealing with storage encryption format * libvirt.spec.in, mingw32-libvirt.spec.in: Add storageencryption.rng RNG schema
2009-08-19 19:50:10 +00:00
</body>
</html>
Reference in New Issue Copy Permalink