docs: Update docs to reflect LUKS secret changes

Commit id's 'c8438010', '9bbf0d7e', and '2552fec24' altered the documentation
to describe adding a 'passphrase' type secret usage model in order to reference
the secret for a luks volume. After commit, it was deemed that a 'volume'
usage model should be used, so adjust the various documents in order rephrase
descriptions in order to follow the correct usage model.

Signed-off-by: John Ferlan <jferlan@redhat.com>

docs/formatsecret.html.in

@@ -41,19 +41,20 @@
       <dd>
         Specifies what this secret is used for.  A mandatory
         <code>type</code> attribute specifies the usage category, currently
-        only <code>volume</code>, <code>ceph</code>, <code>iscsi</code>,
+        only <code>volume</code>, <code>ceph</code>, and <code>iscsi</code>
-        and <code>passphrase</code> are defined. Specific usage categories
+        are defined. Specific usage categories are described below.
-        are described below.
       </dd>
     </dl>
 
     <h3><a name="VolumeUsageType">Usage type "volume"</a></h3>
 
     <p>
-      This secret is associated with a volume, and it is safe to delete the
+      This secret is associated with a volume, whether the format is either
-      secret after the volume is deleted.  The <code>&lt;usage
+      for a "qcow" or a "luks" encrypted volume. Each volume will have a
-      type='volume'&gt;</code> element must contain a
+      unique secret associated with it and it is safe to delete the
-      single <code>volume</code> element that specifies the key of the volume
+      secret after the volume is deleted. The
+      <code>&lt;usage type='volume'&gt;</code> element must contain a
+      single <code>volume</code> element that specifies the path of the volume
       this secret is associated with. For example, create a volume-secret.xml
       file as follows:
     </p>
@@ -69,7 +70,7 @@
     </pre>
 
     <p>
-      Define the secret and set the pass phrase as follows:
+      Define the secret and set the passphrase as follows:
     </p>
     <pre>
       # virsh secret-define volume-secret.xml
@@ -82,8 +83,8 @@
     </pre>
 
     <p>
-      The volume type secret can then be used in the XML for a storage volume
+      The volume type secret can be supplied in domain XML for a qcow storage
-      <a href="formatstorageencryption.html">encryption</a> as follows:
+      volume <a href="formatstorageencryption.html">encryption</a> as follows:
     </p>
     <pre>
       &lt;encryption format='qcow'&gt;
@@ -91,6 +92,33 @@
       &lt;/encryption&gt;
     </pre>
 
+    <p>
+      The volume type secret can be supplied either in volume XML during
+      creation of a <a href="formatstorage.html#StorageVol">storage volume</a>
+      in order to provide the passphrase to encrypt the volume or in
+      domain XML <a href="formatdomain.html#elementsDisks">disk device</a>
+      in order to provide the passphrase to decrypt the volume,
+      <span class="since">since 2.1.0</span>. An example follows:
+    </p>
+    <pre>
+      # cat luks-secret.xml
+      &lt;secret ephemeral='no' private='yes'&gt;
+         &lt;description&gt;LUKS Sample Secret&lt;/description&gt;
+         &lt;uuid&gt;f52a81b2-424e-490c-823d-6bd4235bc57&lt;/uuid&gt;
+         &lt;usage type='volume'&gt;
+            &lt;volume&gt;/var/lib/libvirt/images/luks-sample.img&lt;/volume&gt;
+         &lt;/usage&gt;
+      &lt;/secret&gt;
+
+      # virsh secret-define luks-secret.xml
+      Secret f52a81b2-424e-490c-823d-6bd4235bc57 created
+      #
+      # MYSECRET=`printf %s "letmein" | base64`
+      # virsh secret-set-value f52a81b2-424e-490c-823d-6bd4235bc57 $MYSECRET
+      Secret value set
+      #
+    </pre>
+
     <h3><a name="CephUsageType">Usage type "ceph"</a></h3>
     <p>
       This secret is associated with a Ceph RBD (rados block device).
@@ -243,61 +271,5 @@
       &lt;/auth&gt;
     </pre>
 
-    <h3><a name="passphraseUsageType">Usage type "passphrase"</a></h3>
-
-    <p>
-      This secret is a general purpose secret to be used by various libvirt
-      objects to provide a single passphrase as required by the object in
-      order to perform its authentication. For example, this secret will
-      be used either by the
-      <a href="formatstorage.html#StorageVol">storage volume</a> in order to
-      provide the passphrase to encrypt a luks volume or by the
-      <a href="formatdomain.html#elementsDisks">disk device</a> in order to
-      provide the passphrase to decrypt the luks volume for usage.
-      <span class="since">Since 2.1.0</span>. The following is an example
-      of a secret.xml file:
-    </p>
-
-    <pre>
-      # cat secret.xml
-      &lt;secret ephemeral='no' private='yes'&gt;
-         &lt;description&gt;sample passphrase secret&lt;/description&gt;
-         &lt;usage type='passphrase'&gt;
-            &lt;name&gt;name_example&lt;/name&gt;
-         &lt;/usage&gt;
-      &lt;/secret&gt;
-
-      # virsh secret-define secret.xml
-      Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created
-
-      # virsh secret-list
-       UUID                                 Usage
-      -----------------------------------------------------------
-       718c71bd-67b5-4a2b-87ec-a24e8ca200dc  passphrase  name_example
-      #
-
-    </pre>
-
-    <p>
-      A secret may also be defined via the
-      <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML">
-       <code>virSecretDefineXML</code></a> API.
-
-      Once the secret is defined, a secret value will need to be set. This
-      value would be the same used to create and use the volume.
-      The following is a simple example of using
-      <code>virsh secret-set-value</code> to set the secret value. The
-      <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
-      <code>virSecretSetValue</code></a> API may also be used to set
-      a more secure secret without using printable/readable characters.
-    </p>
-
-    <pre>
-      # MYSECRET=`printf %s "letmein" | base64`
-      # virsh secret-set-value 718c71bd-67b5-4a2b-87ec-a24e8ca200dc $MYSECRET
-      Secret value set
-
-    </pre>
-
   </body>
 </html>

docs/formatstorage.html.in

@@ -752,5 +752,21 @@
           </permissions>
         </target>
       &lt;/volume&gt;</pre>
+
+    <h3><a name="exampleLuks">Storage volume using LUKS</a></h3>
+
+    <pre>
+      &lt;volume&gt;
+        &lt;name&gt;MyLuks.img&lt;/name&gt;
+        &lt;capacity unit="G"&gt;5&lt;/capacity&gt;
+        &lt;target&gt;
+          &lt;path&gt;/var/lib/virt/images/MyLuks.img&lt;/path&gt;
+          &lt;format type='luks'/&gt;
+          &lt;encryption format='luks'&gt;
+            &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/&gt;
+          &lt;/encryption&gt;
+        &lt;/target&gt;
+      &lt;/volume&gt;
+    </pre>
   </body>
 </html>

docs/formatstorageencryption.html.in

@@ -27,9 +27,9 @@
       <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
+      value of <code>type</code> is <code>volume</code>. The
       <code>uuid</code> is "uuid" of the <code>secret</code> while
-      <code>usage</code> is the value "usage" subelement field.
+      <code>usage</code> is the "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
@@ -40,7 +40,7 @@
     <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
+      when creating a qcow 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
@@ -59,13 +59,9 @@
     <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.
+      and the secret is used in order to either encrypt during volume creation
-      A single <code>&lt;secret type='passphrase'...&gt;</code> element is
+      or decrypt the volume for usage by the domain. A single
-      expected. The secret may be referenced via either a <code>uuid</code> or
+      <code>&lt;secret type='passphrase'...&gt;</code> element is expected.
-      <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>
     <p>
@@ -135,22 +131,21 @@
       &lt;/encryption&gt;</pre>
 
     <p>
-      Assuming a <a href="formatsecret.html#luksUsageType">
+      Assuming a <a href="formatsecret.html#VolumeUsageType">
-      <code>luks secret</code></a> is already defined using a
+      <code>luks volume type secret</code></a> is already defined,
-      <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:
     </p>
     <pre>
       &lt;encryption format='luks'&gt;
-         &lt;secret type='passphrase' usage='luks_example'/&gt;
+        &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/&gt;
       &lt;/encryption&gt;
     </pre>
 
     <p>
-      Here is an example, specifying use of the <code>luks</code> format for
+      Here is an example specifying use of the <code>luks</code> format for
-      a specific cipher algorihm for volume creation:
+      a specific cipher algorithm for volume creation:
     </p>
     <pre>
       &lt;volume&gt;
@@ -160,7 +155,7 @@
           &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;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/&gt;
              &lt;cipher name='twofish' size='256' mode='cbc' hash='sha256'/&gt;
              &lt;ivgen name='plain64' hash='sha256'/&gt;
           &lt;/encryption&gt;