Secret manipulation public API

This patch adds a "secret" as a separately managed object, using a
special-purpose API to transfer the secret values between nodes and
libvirt users.

* docs/schemas/secret.rng, docs/schemas/Makefilem.am: Add new
  schema for virSecret objects
* docs/*html: Re-generated
* docs/formatsecret.html.in, docs/sitemap.html.in: Add page
  describing the virSecret XML schema
* include/libvirt/libvirt.h.in: Define the new virSecret public
  API
* src/libvirt_public.syms: Export symbols for new public APIs
* mingw32-libvirt.spec.in, libvirt.spec.in: Add secret.rng to
  files list

diff --git a/docs/format.html b/docs/format.html
index e97d0e747518b0cd2aff66cd7564e4f7b0117bac..3c20b5fbc2268b2b52f82f315b4070e436d42985 100644 (file)
--- a/docs/format.html
+++ b/docs/format.html
@@ -70,6 +70,10 @@
                         <div>
                           <a title="The host device XML format" class="inactive" href="formatnode.html">Node Devices</a>
                         </div>
+                      </li><li>
+                        <div>
+                          <a title="The secret XML format" class="inactive" href="formatsecret.html">Secrets</a>
+                        </div>
                       </li></ul>
                   </div>
                 </li><li>

diff --git a/docs/formatcaps.html b/docs/formatcaps.html
index 5b20aacfe83fb41f3b2b17233db811f5e7c98358..5f2bc72723b992272bb8854306fa1760ecefca16 100644 (file)
--- a/docs/formatcaps.html
+++ b/docs/formatcaps.html
@@ -70,6 +70,10 @@
                         <div>
                           <a title="The host device XML format" class="inactive" href="formatnode.html">Node Devices</a>
                         </div>
+                      </li><li>
+                        <div>
+                          <a title="The secret XML format" class="inactive" href="formatsecret.html">Secrets</a>
+                        </div>
                       </li></ul>
                   </div>
                 </li><li>

diff --git a/docs/formatdomain.html b/docs/formatdomain.html
index 5415200342f8b58984061661c1696b94e58cf95d..6b655ad4439186fba668b8f04c40ecf090d04864 100644 (file)
--- a/docs/formatdomain.html
+++ b/docs/formatdomain.html
@@ -70,6 +70,10 @@
                         <div>
                           <a title="The host device XML format" class="inactive" href="formatnode.html">Node Devices</a>
                         </div>
+                      </li><li>
+                        <div>
+                          <a title="The secret XML format" class="inactive" href="formatsecret.html">Secrets</a>
+                        </div>
                       </li></ul>
                   </div>
                 </li><li>

diff --git a/docs/formatnetwork.html b/docs/formatnetwork.html
index 0b25a0be1180104fa52e1be79b97b7561ed1460e..72a3cda3c6bfc95a9046a54ee220dbfda6652961 100644 (file)
--- a/docs/formatnetwork.html
+++ b/docs/formatnetwork.html
@@ -70,6 +70,10 @@
                         <div>
                           <a title="The host device XML format" class="inactive" href="formatnode.html">Node Devices</a>
                         </div>
+                      </li><li>
+                        <div>
+                          <a title="The secret XML format" class="inactive" href="formatsecret.html">Secrets</a>
+                        </div>
                       </li></ul>
                   </div>
                 </li><li>

diff --git a/docs/formatnode.html b/docs/formatnode.html
index 4d30b0c1d7bd4a262cd95c55110c29673d51d63c..516c27b12cb0acb4c054586e7f3fc4d1d87f204b 100644 (file)
--- a/docs/formatnode.html
+++ b/docs/formatnode.html
@@ -70,6 +70,10 @@
                         <div>
                           <span class="active">Node Devices</span>
                         </div>
+                      </li><li>
+                        <div>
+                          <a title="The secret XML format" class="inactive" href="formatsecret.html">Secrets</a>
+                        </div>
                       </li></ul>
                   </div>
                 </li><li>

diff --git a/docs/formatsecret.html b/docs/formatsecret.html
new file mode 100644 (file)
index 0000000..998e874
--- /dev/null
+++ b/docs/formatsecret.html
@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<!--
+        This file is autogenerated from formatsecret.html.in
+        Do not edit this file. Changes will be lost.
+      -->
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+    <link rel="stylesheet" type="text/css" href="main.css" />
+    <link rel="SHORTCUT ICON" href="32favicon.png" />
+    <title>libvirt: Secret XML format</title>
+    <meta name="description" content="libvirt, virtualization, virtualization API" />
+  </head>
+  <body>
+    <div id="header">
+      <div id="headerLogo"></div>
+      <div id="headerSearch">
+        <form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><div>
+            <input id="query" name="query" type="text" size="12" value="" />
+            <input id="submit" name="submit" type="submit" value="Search" />
+          </div></form>
+      </div>
+    </div>
+    <div id="body">
+      <div id="menu">
+        <ul class="l0"><li>
+            <div>
+              <a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
+            </div>
+          </li><li>
+            <div>
+              <a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
+            </div>
+          </li><li>
+            <div>
+              <a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
+            </div>
+          </li><li>
+            <div>
+              <a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
+              <ul class="l1"><li>
+                  <div>
+                    <a title="Information about deploying and using libvirt" class="inactive" href="deployment.html">Deployment</a>
+                  </div>
+                </li><li>
+                  <div>
+                    <a title="Overview of the logical subsystems in the libvirt API" class="inactive" href="intro.html">Architecture</a>
+                  </div>
+                </li><li>
+                  <div>
+                    <a title="Description of the XML formats used in libvirt" class="active" href="format.html">XML format</a>
+                    <ul class="l2"><li>
+                        <div>
+                          <a title="The domain XML format" class="inactive" href="formatdomain.html">Domains</a>
+                        </div>
+                      </li><li>
+                        <div>
+                          <a title="The virtual network XML format" class="inactive" href="formatnetwork.html">Networks</a>
+                        </div>
+                      </li><li>
+                        <div>
+                          <a title="The storage pool and volume XML format" class="inactive" href="formatstorage.html">Storage</a>
+                        </div>
+                      </li><li>
+                        <div>
+                          <a title="The driver capabilities XML format" class="inactive" href="formatcaps.html">Capabilities</a>
+                        </div>
+                      </li><li>
+                        <div>
+                          <a title="The host device XML format" class="inactive" href="formatnode.html">Node Devices</a>
+                        </div>
+                      </li><li>
+                        <div>
+                          <span class="active">Secrets</span>
+                        </div>
+                      </li></ul>
+                  </div>
+                </li><li>
+                  <div>
+                    <a title="Hypervisor specific driver information" class="inactive" href="drivers.html">Drivers</a>
+                  </div>
+                </li><li>
+                  <div>
+                    <a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
+                  </div>
+                </li><li>
+                  <div>
+                    <a title="Bindings of the libvirt API for other languages" class="inactive" href="bindings.html">Language bindings</a>
+                  </div>
+                </li><li>
+                  <div>
+                    <a title="Working on the internals of libvirt API, driver and daemon code" class="inactive" href="internals.html">Internals</a>
+                  </div>
+                </li></ul>
+            </div>
+          </li><li>
+            <div>
+              <a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
+            </div>
+          </li><li>
+            <div>
+              <a title="Frequently asked questions" class="inactive" href="FAQ.html">FAQ</a>
+            </div>
+          </li><li>
+            <div>
+              <a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
+            </div>
+          </li><li>
+            <div>
+              <a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
+            </div>
+          </li><li>
+            <div>
+              <a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
+            </div>
+          </li><li>
+            <div>
+              <a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
+            </div>
+          </li></ul>
+      </div>
+      <div id="content">
+        <h1>Secret XML format</h1>
+        <ul><li>
+            <a href="#SecretAttributes">Secret XML</a>
+          </li><li>
+            <a href="#example">Example</a>
+          </li></ul>
+        <h2>
+          <a name="SecretAttributes" id="SecretAttributes">Secret XML</a>
+        </h2>
+        <p>
+      Secrets stored by libvirt may have attributes associated with them, using
+      the <code>secret</code> element.  The <code>secret</code> element has two
+      optional attributes, each with values '<code>yes</code>' and
+      '<code>no</code>', and defaulting to '<code>no</code>':
+    </p>
+        <dl><dt><code>ephemeral</code></dt><dd>This secret must only be kept in memory, never stored persistently.
+      </dd><dt><code>private</code></dt><dd>The value of the secret must not be revealed to any caller of libvirt,
+        nor to any other node.
+      </dd></dl>
+        <p>
+      The top-level <code>secret</code> element may contain the following
+      elements:
+    </p>
+        <dl><dt><code>uuid</code></dt><dd>
+        An unique identifier for this secret (not necessarily in the UUID
+        format).  If omitted when defining a new secret, a random UUID is
+        generated.
+      </dd><dt><code>volume</code></dt><dd>Key of a volume this secret is associated with.  It is safe to delete
+        the secret after the volume is deleted.
+      </dd><dt><code>description</code></dt><dd>A human-readable description of the purpose of the secret.
+      </dd></dl>
+        <h2>
+          <a name="example" id="example">Example</a>
+        </h2>
+        <pre>
+      &lt;secret ephemeral='no' private='yes'&gt;
+         &lt;volume&gt;/var/lib/libvirt/images/mail.img&lt;/volume&gt;
+         &lt;description&gt;LUKS passphrase for the main hard drive of our mail server&lt;/description&gt;
+      &lt;/secret&gt;</pre>
+      </div>
+    </div>
+    <div id="footer">
+      <p id="sponsor">
+           Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
+    </div>
+  </body>
+</html>

diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in
new file mode 100644 (file)
index 0000000..7471bf7
--- /dev/null
+++ b/docs/formatsecret.html.in
@@ -0,0 +1,52 @@
+<html>
+  <body>
+    <h1>Secret XML format</h1>
+
+    <ul id="toc"></ul>
+
+    <h2><a name="SecretAttributes">Secret XML</a></h2>
+
+    <p>
+      Secrets stored by libvirt may have attributes associated with them, using
+      the <code>secret</code> element.  The <code>secret</code> element has two
+      optional attributes, each with values '<code>yes</code>' and
+      '<code>no</code>', and defaulting to '<code>no</code>':
+    </p>
+    <dl>
+      <dt><code>ephemeral</code></dt>
+      <dd>This secret must only be kept in memory, never stored persistently.
+      </dd>
+      <dt><code>private</code></dt>
+      <dd>The value of the secret must not be revealed to any caller of libvirt,
+        nor to any other node.
+      </dd>
+    </dl>
+    <p>
+      The top-level <code>secret</code> element may contain the following
+      elements:
+    </p>
+    <dl>
+      <dt><code>uuid</code></dt>
+      <dd>
+        An unique identifier for this secret (not necessarily in the UUID
+        format).  If omitted when defining a new secret, a random UUID is
+        generated.
+      </dd>
+      <dt><code>volume</code></dt>
+      <dd>Key of a volume this secret is associated with.  It is safe to delete
+        the secret after the volume is deleted.
+      </dd>
+      <dt><code>description</code></dt>
+      <dd>A human-readable description of the purpose of the secret.
+      </dd>
+    </dl>
+
+    <h2><a name="example">Example</a></h2>
+
+    <pre>
+      &lt;secret ephemeral='no' private='yes'&gt;
+         &lt;volume&gt;/var/lib/libvirt/images/mail.img&lt;/volume&gt;
+         &lt;description&gt;LUKS passphrase for the main hard drive of our mail server&lt;/description&gt;
+      &lt;/secret&gt;</pre>
+  </body>
+</html>

diff --git a/docs/formatstorage.html b/docs/formatstorage.html
index 91e63b4c3329a2b880ac7410c3742fa4749fbe81..02cbcaca1cf6973f07d3faaeea2c2b14d8763ff0 100644 (file)
--- a/docs/formatstorage.html
+++ b/docs/formatstorage.html
@@ -70,6 +70,10 @@
                         <div>
                           <a title="The host device XML format" class="inactive" href="formatnode.html">Node Devices</a>
                         </div>
+                      </li><li>
+                        <div>
+                          <a title="The secret XML format" class="inactive" href="formatsecret.html">Secrets</a>
+                        </div>
                       </li></ul>
                   </div>
                 </li><li>

diff --git a/docs/schemas/Makefile.am b/docs/schemas/Makefile.am
index ef41a63aa981e73e3610c1c2d59d45a46eacc3dc..a064518607c746237226e8ada1d452ce4aef0c54 100644 (file)
--- a/docs/schemas/Makefile.am
+++ b/docs/schemas/Makefile.am
@@ -5,6 +5,7 @@ schema_DATA = \
        domain.rng \
        interface.rng \
        network.rng \
+       secret.rng \
        storagepool.rng \
        storagevol.rng \
        nodedev.rng \

diff --git a/docs/schemas/secret.rng b/docs/schemas/secret.rng
new file mode 100644 (file)
index 0000000..05e04f2
--- /dev/null
+++ b/docs/schemas/secret.rng
@@ -0,0 +1,44 @@
+<!-- A Relax NG schema for the libvirt secret properties XML format -->
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+  <start>
+    <ref name='secret'/>
+  </start>
+
+  <define name='secret'>
+    <element name='secret'>
+      <optional>
+       <attribute name='ephemeral'>
+         <choice>
+           <value>yes</value>
+           <value>no</value>
+         </choice>
+       </attribute>
+      </optional>
+      <optional>
+       <attribute name='private'>
+         <choice>
+           <value>yes</value>
+           <value>no</value>
+         </choice>
+       </attribute>
+      </optional>
+      <interleave>
+       <optional>
+         <element name='uuid'>
+           <text/>
+         </element>
+       </optional>
+       <optional>
+         <element name='description'>
+           <text/>
+         </element>
+       </optional>
+       <optional>
+         <element name='volume'>
+           <text/>
+         </element>
+       </optional>
+      </interleave>
+    </element>
+  </define>
+</grammar>

diff --git a/docs/sitemap.html b/docs/sitemap.html
index f79a533fa5150f5053e3b96a212b552dd2299858..901633d502385097e40b3f6d85d560b438d6f7b0 100644 (file)
--- a/docs/sitemap.html
+++ b/docs/sitemap.html
@@ -141,6 +141,9 @@
               </li><li>
                 <a href="formatnode.html">Node Devices</a>
                 <span>The host device XML format</span>
+              </li><li>
+                <a href="formatsecret.html">Secrets</a>
+                <span>The secret XML format</span>
               </li></ul></li><li>
             <a href="drivers.html">Drivers</a>
             <span>Hypervisor specific driver information</span>

diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in
index 958987846404e7ec50c25b5108ec3f661e0f2129..2ed25c6cacf8572bec7e7efc89f5c650aad4940a 100644 (file)
--- a/docs/sitemap.html.in
+++ b/docs/sitemap.html.in
@@ -106,6 +106,10 @@
                 <a href="formatnode.html">Node Devices</a>
                 <span>The host device XML format</span>
               </li>
+              <li>
+                <a href="formatsecret.html">Secrets</a>
+                <span>The secret XML format</span>
+              </li>
             </ul>
           </li>
           <li>

diff --git a/include/libvirt/libvirt.h b/include/libvirt/libvirt.h
index 855f755601896aa488868bcc71711f4d17068548..1779b08961edadee4c8efb5ebb22d09846439f14 100644 (file)
--- a/include/libvirt/libvirt.h
+++ b/include/libvirt/libvirt.h
@@ -1448,6 +1448,44 @@ void virEventRegisterImpl(virEventAddHandleFunc addHandle,
                           virEventAddTimeoutFunc addTimeout,
                           virEventUpdateTimeoutFunc updateTimeout,
                           virEventRemoveTimeoutFunc removeTimeout);
+
+/*
+ * Secret manipulation API
+ */
+
+/**
+ * virSecret:
+ *
+ * A virSecret stores a secret value (e.g. a passphrase or encryption key)
+ * and associated metadata.
+ */
+typedef struct _virSecret virSecret;
+typedef virSecret *virSecretPtr;
+
+virConnectPtr           virSecretGetConnect     (virSecretPtr secret);
+int                     virConnectNumOfSecrets  (virConnectPtr conn);
+int                     virConnectListSecrets   (virConnectPtr conn,
+                                                 char **uuids,
+                                                 int maxuuids);
+virSecretPtr            virSecretLookupByUUIDString(virConnectPtr conn,
+                                                    const char *uuid);
+virSecretPtr            virSecretDefineXML      (virConnectPtr conn,
+                                                 const char *xml,
+                                                 unsigned int flags);
+char *                  virSecretGetUUIDString  (virSecretPtr secret);
+char *                  virSecretGetXMLDesc     (virSecretPtr secret,
+                                                 unsigned int flags);
+int                     virSecretSetValue       (virSecretPtr secret,
+                                                 const unsigned char *value,
+                                                 size_t value_size,
+                                                 unsigned int flags);
+unsigned char *         virSecretGetValue       (virSecretPtr secret,
+                                                 size_t *value_size,
+                                                 unsigned int flags);
+int                     virSecretUndefine       (virSecretPtr secret);
+int                     virSecretRef            (virSecretPtr secret);
+int                     virSecretFree           (virSecretPtr secret);
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index e6536c78d0b16c7078d7c01a91011e0af06b3c79..8e26e4861c53c05ba844b970abe39ddcd38c56ed 100644 (file)
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -1448,6 +1448,44 @@ void virEventRegisterImpl(virEventAddHandleFunc addHandle,
                           virEventAddTimeoutFunc addTimeout,
                           virEventUpdateTimeoutFunc updateTimeout,
                           virEventRemoveTimeoutFunc removeTimeout);
+
+/*
+ * Secret manipulation API
+ */
+
+/**
+ * virSecret:
+ *
+ * A virSecret stores a secret value (e.g. a passphrase or encryption key)
+ * and associated metadata.
+ */
+typedef struct _virSecret virSecret;
+typedef virSecret *virSecretPtr;
+
+virConnectPtr           virSecretGetConnect     (virSecretPtr secret);
+int                     virConnectNumOfSecrets  (virConnectPtr conn);
+int                     virConnectListSecrets   (virConnectPtr conn,
+                                                 char **uuids,
+                                                 int maxuuids);
+virSecretPtr            virSecretLookupByUUIDString(virConnectPtr conn,
+                                                    const char *uuid);
+virSecretPtr            virSecretDefineXML      (virConnectPtr conn,
+                                                 const char *xml,
+                                                 unsigned int flags);
+char *                  virSecretGetUUIDString  (virSecretPtr secret);
+char *                  virSecretGetXMLDesc     (virSecretPtr secret,
+                                                 unsigned int flags);
+int                     virSecretSetValue       (virSecretPtr secret,
+                                                 const unsigned char *value,
+                                                 size_t value_size,
+                                                 unsigned int flags);
+unsigned char *         virSecretGetValue       (virSecretPtr secret,
+                                                 size_t *value_size,
+                                                 unsigned int flags);
+int                     virSecretUndefine       (virSecretPtr secret);
+int                     virSecretRef            (virSecretPtr secret);
+int                     virSecretFree           (virSecretPtr secret);
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/libvirt.spec.in b/libvirt.spec.in
index 067b83521e14c4d9dbcabb4101d1404a4189bf49..966cdf137a33a05776f326148f895128e7ca5fd8 100644 (file)
--- a/libvirt.spec.in
+++ b/libvirt.spec.in
@@ -581,6 +581,7 @@ fi
 %{_datadir}/libvirt/schemas/nodedev.rng
 %{_datadir}/libvirt/schemas/capability.rng
 %{_datadir}/libvirt/schemas/interface.rng
+%{_datadir}/libvirt/schemas/secret.rng
 
 %if %{with_sasl}
 %config(noreplace) %{_sysconfdir}/sasl2/libvirt.conf

diff --git a/mingw32-libvirt.spec.in b/mingw32-libvirt.spec.in
index 40a8124df114f4c65832c81b6057a2866595cadf..093c45a08b8e4c49c802f2f74e0456b770393930 100644 (file)
--- a/mingw32-libvirt.spec.in
+++ b/mingw32-libvirt.spec.in
@@ -94,6 +94,7 @@ rm -rf $RPM_BUILD_ROOT
 %{_mingw32_datadir}/libvirt/schemas/nodedev.rng
 %{_mingw32_datadir}/libvirt/schemas/capability.rng
 %{_mingw32_datadir}/libvirt/schemas/interface.rng
+%{_mingw32_datadir}/libvirt/schemas/secret.rng
 
 %{_mingw32_datadir}/locale/*/LC_MESSAGES/libvirt.mo
 

diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
index c06f51ec310791161ecf9ce5738a04acebb66c43..65080ed84eb81b6ac282bfe5eeb10312691160f0 100644 (file)
--- a/src/libvirt_public.syms
+++ b/src/libvirt_public.syms
@@ -292,3 +292,19 @@ LIBVIRT_0.7.0 {
 } LIBVIRT_0.6.4;
 
 # .... define new API here using predicted next version number ....
+
+LIBVIRT_0.7.1 {
+    global:
+        virSecretGetConnect;
+        virConnectNumOfSecrets;
+        virConnectListSecrets;
+        virSecretLookupByUUIDString;
+        virSecretDefineXML;
+        virSecretGetUUIDString;
+        virSecretGetXMLDesc;
+        virSecretSetValue;
+        virSecretGetValue;
+        virSecretUndefine;
+        virSecretRef;
+        virSecretFree;
+} LIBVIRT_0.7.0;