libvirt/docs/formatstorageencryption.html.in

<html>
  <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 <code>uuid</code>.  The only currently defined value of
      <code>type</code> is <code>passphrase</code>.  <code>uuid</code>
      refers to a secret known to libvirt.  libvirt can use a secret value
      previously set using <code>virSecretSetValue()</code>, or, 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 type="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>
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			`<html>`
			`<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 <code>uuid</code>. The only currently defined value of`
			`<code>type</code> is <code>passphrase</code>. <code>uuid</code>`
			`refers to a secret known to libvirt. libvirt can use a secret value`
			`previously set using <code>virSecretSetValue()</code>, or, 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><encryption type="default"/></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><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>`

			`<h2><a name="example">Example</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>`
			`</body>`
			`</html>`