docs/formatsecret.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>Secret XML format</h1>
   6
   7     <ul id="toc"></ul>
   8
   9     <h2><a id="SecretAttributes">Secret XML</a></h2>
  10
  11     <p>
  12       Secrets stored by libvirt may have attributes associated with them, using
  13       the <code>secret</code> element.  The <code>secret</code> element has two
  14       optional attributes, each with values '<code>yes</code>' and
  15       '<code>no</code>', and defaulting to '<code>no</code>':
  16     </p>
  17     <dl>
  18       <dt><code>ephemeral</code></dt>
  19       <dd>This secret must only be kept in memory, never stored persistently.
  20       </dd>
  21       <dt><code>private</code></dt>
  22       <dd>The value of the secret must not be revealed to any caller of libvirt,
  23         nor to any other node.
  24       </dd>
  25     </dl>
  26     <p>
  27       The top-level <code>secret</code> element may contain the following
  28       elements:
  29     </p>
  30     <dl>
  31       <dt><code>uuid</code></dt>
  32       <dd>
  33         An unique identifier for this secret (not necessarily in the UUID
  34         format).  If omitted when defining a new secret, a random UUID is
  35         generated.
  36       </dd>
  37       <dt><code>description</code></dt>
  38       <dd>A human-readable description of the purpose of the secret.
  39       </dd>
  40       <dt><code>usage</code></dt>
  41       <dd>
  42         Specifies what this secret is used for.  A mandatory
  43         <code>type</code> attribute specifies the usage category, currently
  44         only <code>volume</code>, <code>ceph</code>, <code>iscsi</code>,
  45         <code>tls</code>, and <code>vtpm</code> are defined. Specific usage
  46         categories are described below.
  47       </dd>
  48     </dl>
  49
  50     <h3><a id="VolumeUsageType">Usage type "volume"</a></h3>
  51
  52     <p>
  53       This secret is associated with a volume, whether the format is either
  54       for a "luks" encrypted volume. Each volume will have a
  55       unique secret associated with it and it is safe to delete the
  56       secret after the volume is deleted. The
  57       <code>&lt;usage type='volume'&gt;</code> element must contain a
  58       single <code>volume</code> element that specifies the path of the volume
  59       this secret is associated with. For example, create a volume-secret.xml
  60       file as follows:
  61     </p>
  62
  63     <pre>
  64 &lt;secret ephemeral='no' private='yes'&gt;
  65    &lt;description&gt;Super secret name of my first puppy&lt;/description&gt;
  66    &lt;uuid&gt;0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f&lt;/uuid&gt;
  67    &lt;usage type='volume'&gt;
  68       &lt;volume&gt;/var/lib/libvirt/images/puppyname.img&lt;/volume&gt;
  69    &lt;/usage&gt;
  70 &lt;/secret&gt;
  71     </pre>
  72
  73     <p>
  74       Define the secret and set the passphrase as follows:
  75     </p>
  76     <pre>
  77 # virsh secret-define volume-secret.xml
  78 Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
  79 #
  80 # MYSECRET=`printf %s "open sesame" | base64`
  81 # virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET
  82 Secret value set
  83 #
  84     </pre>
  85
  86     <p>
  87       The volume type secret can be supplied either in volume XML during
  88       creation of a <a href="formatstorage.html#StorageVol">storage volume</a>
  89       in order to provide the passphrase to encrypt the volume or in
  90       domain XML <a href="formatdomain.html#elementsDisks">disk device</a>
  91       in order to provide the passphrase to decrypt the volume,
  92       <span class="since">since 2.1.0</span>. An example follows:
  93     </p>
  94     <pre>
  95 # cat luks-secret.xml
  96 &lt;secret ephemeral='no' private='yes'&gt;
  97    &lt;description&gt;LUKS Sample Secret&lt;/description&gt;
  98    &lt;uuid&gt;f52a81b2-424e-490c-823d-6bd4235bc57&lt;/uuid&gt;
  99    &lt;usage type='volume'&gt;
 100       &lt;volume&gt;/var/lib/libvirt/images/luks-sample.img&lt;/volume&gt;
 101    &lt;/usage&gt;
 102 &lt;/secret&gt;
 103
 104 # virsh secret-define luks-secret.xml
 105 Secret f52a81b2-424e-490c-823d-6bd4235bc57 created
 106 #
 107 # MYSECRET=`printf %s "letmein" | base64`
 108 # virsh secret-set-value f52a81b2-424e-490c-823d-6bd4235bc57 $MYSECRET
 109 Secret value set
 110 #
 111     </pre>
 112
 113     <p>
 114       The volume type secret can be supplied in domain XML for a luks storage
 115       volume <a href="formatstorageencryption.html">encryption</a> as follows:
 116     </p>
 117     <pre>
 118 &lt;encryption format='luks'&gt;
 119   &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc57'/&gt;
 120 &lt;/encryption&gt;
 121     </pre>
 122
 123     <h3><a id="CephUsageType">Usage type "ceph"</a></h3>
 124     <p>
 125       This secret is associated with a Ceph RBD (rados block device).
 126       The <code>&lt;usage type='ceph'&gt;</code> element must contain
 127       a single <code>name</code> element that specifies a usage name
 128       for the secret.  The Ceph secret can then be used by UUID or by
 129       this usage name via the <code>&lt;auth&gt;</code> element of
 130       a <a href="formatdomain.html#elementsDisks">disk device</a> or
 131       a <a href="formatstorage.html">storage pool (rbd)</a>.
 132       <span class="since">Since 0.9.7</span>. The following is an example
 133       of the steps to be taken.  First create a ceph-secret.xml file:
 134     </p>
 135
 136     <pre>
 137 &lt;secret ephemeral='no' private='yes'&gt;
 138    &lt;description&gt;CEPH passphrase example&lt;/description&gt;
 139    &lt;usage type='ceph'&gt;
 140       &lt;name&gt;ceph_example&lt;/name&gt;
 141    &lt;/usage&gt;
 142 &lt;/secret&gt;
 143     </pre>
 144
 145     <p>
 146       Next, use <code>virsh secret-define ceph-secret.xml</code> to define
 147       the secret and <code>virsh secret-set-value</code> using the generated
 148       UUID value and a base64 generated secret value in order to define the
 149       chosen secret pass phrase.
 150     </p>
 151     <pre>
 152 # virsh secret-define ceph-secret.xml
 153 Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created
 154 #
 155 # virsh secret-list
 156  UUID                                 Usage
 157 -----------------------------------------------------------
 158  1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example
 159 #
 160 # CEPHPHRASE=`printf %s "pass phrase" | base64`
 161 # virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE
 162 Secret value set
 163
 164 #
 165     </pre>
 166
 167     <p>
 168       The ceph secret can then be used by UUID or by the
 169       usage name via the <code>&lt;auth&gt;</code> element in a domain's
 170       <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
 171       element as follows:
 172     </p>
 173     <pre>
 174 &lt;auth username='myname'&gt;
 175   &lt;secret type='ceph' usage='ceph_example'/&gt;
 176 &lt;/auth&gt;
 177     </pre>
 178
 179     <p>
 180       As well as the <code>&lt;auth&gt;</code> element in a
 181       <a href="formatstorage.html">storage pool (rbd)</a>
 182       <code>&lt;source&gt;</code> element as follows:
 183     </p>
 184     <pre>
 185 &lt;auth type='ceph' username='myname'&gt;
 186   &lt;secret usage='ceph_example'/&gt;
 187 &lt;/auth&gt;
 188     </pre>
 189
 190     <h3><a id="iSCSIUsageType">Usage type "iscsi"</a></h3>
 191
 192     <p>
 193       This secret is associated with an iSCSI target for CHAP authentication.
 194       The <code>&lt;usage type='iscsi'&gt;</code> element must contain
 195       a single <code>target</code> element that specifies a usage name
 196       for the secret. The iSCSI secret can then be used by UUID or by
 197       this usage name via the <code>&lt;auth&gt;</code> element of
 198       a <a href="formatdomain.html#elementsDisks">disk device</a> or
 199       a <a href="formatstorage.html">storage pool (iscsi)</a>.
 200       <span class="since">Since 1.0.4</span>. The following is an example
 201       of the XML that may be used to generate a secret for iSCSI CHAP
 202       authentication. Assume the following sample entry in an iSCSI
 203       authentication file:
 204     </p>
 205       <pre>
 206 &lt;target iqn.2013-07.com.example:iscsi-pool&gt;
 207 backing-store /home/tgtd/iscsi-pool/disk1
 208 backing-store /home/tgtd/iscsi-pool/disk2
 209 incominguser myname mysecret
 210 &lt;/target&gt;
 211       </pre>
 212     <p>
 213       Define an iscsi-secret.xml file to describe the secret. Use the
 214       <code>incominguser</code> username used in your iSCSI authentication
 215       configuration file as the value for the <code>username</code> attribute.
 216       The <code>description</code> attribute should contain configuration
 217       specific data. The <code>target</code> name may be any name of your
 218       choosing to be used as the <code>usage</code> when used in the pool
 219       or disk XML description.
 220     </p>
 221     <pre>
 222 &lt;secret ephemeral='no' private='yes'&gt;
 223    &lt;description&gt;Passphrase for the iSCSI example.com server&lt;/description&gt;
 224    &lt;usage type='iscsi'&gt;
 225       &lt;target&gt;libvirtiscsi&lt;/target&gt;
 226    &lt;/usage&gt;
 227 &lt;/secret&gt;
 228     </pre>
 229
 230     <p>
 231       Next, use <code>virsh secret-define iscsi-secret.xml</code> to define
 232       the secret and <code>virsh secret-set-value</code> using the generated
 233       UUID value and a base64 generated secret value in order to define the
 234       chosen secret pass phrase.  The pass phrase must match the password
 235       used in the iSCSI authentication configuration file.
 236     </p>
 237     <pre>
 238 # virsh secret-define secret.xml
 239 Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created
 240
 241 # virsh secret-list
 242  UUID                                 Usage
 243 -----------------------------------------------------------
 244  c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi
 245
 246 # MYSECRET=`printf %s "mysecret" | base64`
 247 # virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET
 248 Secret value set
 249 #
 250     </pre>
 251
 252     <p>
 253       The iSCSI secret can then be used by UUID or by the
 254       usage name via the <code>&lt;auth&gt;</code> element in a domain's
 255       <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
 256       element as follows:
 257     </p>
 258     <pre>
 259 &lt;auth username='myname'&gt;
 260   &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
 261 &lt;/auth&gt;
 262     </pre>
 263
 264     <p>
 265       As well as the <code>&lt;auth&gt;</code> element in a
 266       <a href="formatstorage.html">storage pool (iscsi)</a>
 267       <code>&lt;source&gt;</code> element as follows:
 268     </p>
 269     <pre>
 270 &lt;auth type='chap' username='myname'&gt;
 271   &lt;secret usage='libvirtiscsi'/&gt;
 272 &lt;/auth&gt;
 273     </pre>
 274
 275     <h3><a id="tlsUsageType">Usage type "tls"</a></h3>
 276
 277     <p>
 278       This secret may be used in order to provide the passphrase for the
 279       private key used to provide TLS credentials.
 280       The <code>&lt;usage type='tls'&gt;</code> element must contain a
 281       single <code>name</code> element that specifies a usage name
 282       for the secret.
 283       <span class="since">Since 2.3.0</span>.
 284       The following is an example of the expected XML and processing to
 285       define the secret:
 286     </p>
 287
 288     <pre>
 289 # cat tls-secret.xml
 290 &lt;secret ephemeral='no' private='yes'&gt;
 291    &lt;description&gt;sample tls secret&lt;/description&gt;
 292    &lt;usage type='tls'&gt;
 293       &lt;name&gt;TLS_example&lt;/name&gt;
 294    &lt;/usage&gt;
 295 &lt;/secret&gt;
 296
 297 # virsh secret-define tls-secret.xml
 298 Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created
 299
 300 # virsh secret-list
 301  UUID                                 Usage
 302 -----------------------------------------------------------
 303  718c71bd-67b5-4a2b-87ec-a24e8ca200dc  tls TLS_example
 304 #
 305
 306     </pre>
 307
 308     <p>
 309       A secret may also be defined via the
 310       <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML">
 311        <code>virSecretDefineXML</code></a> API.
 312
 313       Once the secret is defined, a secret value will need to be set. The
 314       secret would be the passphrase used to access the TLS credentials.
 315       The following is a simple example of using
 316       <code>virsh secret-set-value</code> to set the secret value. The
 317       <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
 318       <code>virSecretSetValue</code></a> API may also be used to set
 319       a more secure secret without using printable/readable characters.
 320     </p>
 321
 322     <pre>
 323 # MYSECRET=`printf %s "letmein" | base64`
 324 # virsh secret-set-value 718c71bd-67b5-4a2b-87ec-a24e8ca200dc $MYSECRET
 325 Secret value set
 326
 327     </pre>
 328
 329     <h3><a id="vTPMUsageType">Usage type "vtpm"</a></h3>
 330
 331     <p>
 332       This secret is associated with a virtualized TPM (vTPM) and serves
 333       as a passphrase for deriving a key from for encrypting the state
 334       of the vTPM.
 335       The <code>&lt;usage type='vtpm'&gt;</code> element must contain
 336       a single <code>name</code> element that specifies a usage name
 337       for the secret.  The vTPM secret can then be used by UUID or by
 338       this usage name via the <code>&lt;encryption&gt;</code> element of
 339       a <a href="formatdomain.html#elementsTpm">tpm</a> when using an
 340       emulator.
 341       <span class="since">Since 5.6.0</span>. The following is an example
 342       of the steps to be taken.  First create a vtpm-secret.xml file:    </p>
 343
 344     <pre>
 345 # cat vtpm-secret.xml
 346 &lt;secret ephemeral='no' private='yes'&gt;
 347    &lt;description&gt;sample vTPM secret&lt;/description&gt;
 348    &lt;usage type='vtpm'&gt;
 349       &lt;name&gt;VTPM_example&lt;/name&gt;
 350    &lt;/usage&gt;
 351 &lt;/secret&gt;
 352
 353 # virsh secret-define vtpm-secret.xml
 354 Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created
 355
 356 # virsh secret-list
 357  UUID                                   Usage
 358 ----------------------------------------------------------------------------------------
 359  6dd3e4a5-1d76-44ce-961f-f119f5aad935   vtpm VTPM_example
 360
 361 #
 362
 363     </pre>
 364
 365     <p>
 366       A secret may also be defined via the
 367       <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML">
 368        <code>virSecretDefineXML</code></a> API.
 369
 370       Once the secret is defined, a secret value will need to be set. The
 371       secret would be the passphrase used to decrypt the vTPM state.
 372       The following is a simple example of using
 373       <code>virsh secret-set-value</code> to set the secret value. The
 374       <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
 375       <code>virSecretSetValue</code></a> API may also be used to set
 376       a more secure secret without using printable/readable characters.
 377     </p>
 378
 379     <pre>
 380 # MYSECRET=`printf %s "open sesame" | base64`
 381 # virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 $MYSECRET
 382 Secret value set
 383
 384     </pre>
 385
 386   </body>
 387 </html>