docs/formatstorageencryption.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>Storage volume encryption XML format</h1>
   6
   7     <ul id="toc"></ul>
   8
   9     <h2><a id="StorageEncryption">Storage volume encryption XML</a></h2>
  10
  11     <p>
  12       Storage volumes may be encrypted, the XML snippet described below is used
  13       to represent the details of the encryption.  It can be used as a part
  14       of a domain or storage configuration.
  15     </p>
  16     <p>
  17       The top-level tag of volume encryption specification
  18       is <code>encryption</code>, with a mandatory
  19       attribute <code>format</code>.  Currently defined values
  20       of <code>format</code> are <code>default</code>, <code>qcow</code>,
  21       and <code>luks</code>.
  22       Each value of <code>format</code> implies some expectations about the
  23       content of the <code>encryption</code> tag.  Other format values may be
  24       defined in the future.
  25     </p>
  26     <p>
  27       The <code>encryption</code> tag can currently contain a sequence of
  28       <code>secret</code> tags, each with mandatory attributes <code>type</code>
  29       and either <code>uuid</code> or <code>usage</code>
  30       (<span class="since">since 2.1.0</span>). The only currently defined
  31       value of <code>type</code> is <code>volume</code>. The
  32       <code>uuid</code> is "uuid" of the <code>secret</code> while
  33       <code>usage</code> is the "usage" subelement field.
  34       A secret value can be set in libvirt by the
  35       <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
  36       <code>virSecretSetValue</code></a> API. Alternatively, if supported
  37       by the particular volume format and driver, automatically generate a
  38       secret value at the time of volume creation, and store it using the
  39       specified <code>uuid</code>.
  40     </p>
  41     <h3><a id="StorageEncryptionDefault">"default" format</a></h3>
  42     <h3><a id="StorageEncryptionQcow">"qcow" format</a></h3>
  43     <p>
  44       <span class="since">Since 4.5.0,</span> encryption formats
  45       <code>default</code> and <code>qcow</code> may no longer be used
  46       to create an encrypted volume. Usage of qcow encrypted volumes
  47       in QEMU began phasing out in QEMU 2.3 and by QEMU 2.9 creation
  48       of a qcow encrypted volume via qemu-img required usage of secret
  49       objects, but that support was not added to libvirt.
  50     </p>
  51     <h3><a id="StorageEncryptionLuks">"luks" format</a></h3>
  52     <p>
  53       The <code>luks</code> format is specific to a luks encrypted volume
  54       and the secret is used in order to either encrypt during volume creation
  55       or decrypt the volume for usage by the domain. A single
  56       <code>&lt;secret type='passphrase'...&gt;</code> element is expected.
  57       <span class="since">Since 2.1.0</span>.
  58     </p>
  59     <p>
  60       For volume creation, it is possible to specify the encryption
  61       algorithm used to encrypt the luks volume. The following two
  62       optional elements may be provided for that purpose. It is hypervisor
  63       dependent as to which algorithms are supported. The default algorithm
  64       used by the storage driver backend when using qemu-img to create
  65       the volume is 'aes-256-cbc' using 'essiv' for initialization vector
  66       generation and 'sha256' hash algorithm for both the cipher and the
  67       initialization vector generation.
  68     </p>
  69
  70     <dl>
  71       <dt><code>cipher</code></dt>
  72       <dd>This element describes the cipher algorithm to be used to either
  73           encrypt or decrypt the luks volume. This element has the following
  74           attributes:
  75           <dl>
  76             <dt><code>name</code></dt>
  77             <dd>The name of the cipher algorithm used for data encryption,
  78             such as 'aes', 'des', 'cast5', 'serpent', 'twofish', etc.
  79             Support of the specific algorithm is storage driver
  80             implementation dependent.</dd>
  81             <dt><code>size</code></dt>
  82             <dd>The size of the cipher in bits, such as '256', '192', '128',
  83             etc. Support of the specific size for a specific cipher is
  84             hypervisor dependent.</dd>
  85             <dt><code>mode</code></dt>
  86             <dd>An optional cipher algorithm mode such as 'cbc', 'xts',
  87             'ecb', etc. Support of the specific cipher mode is
  88             hypervisor dependent.</dd>
  89             <dt><code>hash</code></dt>
  90             <dd>An optional master key hash algorithm such as 'md5', 'sha1',
  91             'sha256', etc. Support of the specific hash algorithm is
  92             hypervisor dependent.</dd>
  93           </dl>
  94       </dd>
  95       <dt><code>ivgen</code></dt>
  96       <dd>This optional element describes the initialization vector
  97           generation algorithm used in conjunction with the
  98           <code>cipher</code>. If the <code>cipher</code> is not provided,
  99           then an error will be generated by the parser.
 100           <dl>
 101             <dt><code>name</code></dt>
 102             <dd>The name of the algorithm, such as 'plain', 'plain64',
 103             'essiv', etc. Support of the specific algorithm is hypervisor
 104             dependent.</dd>
 105             <dt><code>hash</code></dt>
 106             <dd>An optional hash algorithm such as 'md5', 'sha1', 'sha256',
 107             etc. Support of the specific ivgen hash algorithm is hypervisor
 108             dependent.</dd>
 109           </dl>
 110       </dd>
 111     </dl>
 112
 113
 114     <h2><a id="example">Examples</a></h2>
 115
 116     <p>
 117       Assuming a <a href="formatsecret.html#VolumeUsageType">
 118       <code>luks volume type secret</code></a> is already defined,
 119       a simple example specifying use of the <code>luks</code> format
 120       for either volume creation without a specific cipher being defined or
 121       as part of a domain volume definition:
 122     </p>
 123     <pre>
 124 &lt;encryption format='luks'&gt;
 125   &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/&gt;
 126 &lt;/encryption&gt;
 127     </pre>
 128
 129     <p>
 130       Here is an example specifying use of the <code>luks</code> format for
 131       a specific cipher algorithm for volume creation:
 132     </p>
 133     <pre>
 134 &lt;volume&gt;
 135   &lt;name&gt;twofish.luks&lt;/name&gt;
 136   &lt;capacity unit='G'&gt;5&lt;/capacity&gt;
 137   &lt;target&gt;
 138     &lt;path&gt;/var/lib/libvirt/images/demo.luks&lt;/path&gt;
 139     &lt;format type='raw'/&gt;
 140     &lt;encryption format='luks'&gt;
 141        &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/&gt;
 142        &lt;cipher name='twofish' size='256' mode='cbc' hash='sha256'/&gt;
 143        &lt;ivgen name='plain64' hash='sha256'/&gt;
 144     &lt;/encryption&gt;
 145   &lt;/target&gt;
 146 &lt;/volume&gt;
 147     </pre>
 148
 149   </body>
 150 </html>