3:28 p.m.
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.
Rather than add explicit accessors for attributes of secrets, and
hard-code the "secrets are related to storage volumes" association in
the API, the API uses XML to manipulate the association as well as
other attributes, similarly to other areas of libvirt.
The user can allocate an ID for the secret using virSecretAllocateID()
(or use some other way to allocate secret IDs, e.g. reuse IDs used by
the user in other databases), set attributes of the secret using XML, e.g.
<secret ephemeral='no' private='yes'>
<volume>/var/lib/libvirt/images/mail.img</volume>
<description>LUKS passphrase for our mail server</description>
</secret>
The secret value can be either generated and stored by libvirt during
volume creation, or supplied by the user using virSecretSetValue().
A simple API is provided for enumeration of all secrets. Very large
deployments will manage secret IDs automatically, so it is probably not
necessary to provide a specialized lookup function (allowing the volume
key -> secret ID lookup in less than O(number of secrets)). These
functions can eventually be added later.
---
docs/format.html | 4 +
docs/formatcaps.html | 4 +
docs/formatdomain.html | 4 +
docs/formatnetwork.html | 4 +
docs/formatnode.html | 4 +
docs/formatsecret.html | 166 ++++++++++++++++++++++++++++++++++++++++++
docs/formatsecret.html.in | 46 ++++++++++++
docs/formatstorage.html | 4 +
docs/schemas/Makefile.am | 1 +
docs/schemas/secret.rng | 39 ++++++++++
docs/sitemap.html | 3 +
docs/sitemap.html.in | 4 +
include/libvirt/libvirt.h | 24 ++++++
include/libvirt/libvirt.h.in | 24 ++++++
src/libvirt_public.syms | 8 ++
15 files changed, 339 insertions(+), 0 deletions(-)
create mode 100644 docs/formatsecret.html
create mode 100644 docs/formatsecret.html.in
create mode 100644 docs/schemas/secret.rng
diff --git a/docs/format.html b/docs/format.html
index e97d0e7..8aed8d3 100644
--- 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 attribute 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 5b20aac..8e2e5d1 100644
--- 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 attribute 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 5415200..bbce989 100644
--- 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 attribute 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 0b25a0b..6049492 100644
--- 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 attribute 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 4d30b0c..cca75ff 100644
--- 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 attribute 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
index 0000000..8c6e0c6
--- /dev/null
+++ b/docs/formatsecret.html
@@ -0,0 +1,166 @@
+<?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 attributes 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 attributes XML format</h1>
+ <ul><li>
+ <a href="#SecretAttributes">Secret attributes XML</a>
+ </li><li>
+ <a href="#example">Example</a>
+ </li></ul>
+ <h2>
+ <a name="SecretAttributes"
id="SecretAttributes">Secret attributes 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>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>
+ <secret ephemeral='no' private='yes'>
+ <volume>/var/lib/libvirt/images/mail.img</volume>
+ <description>LUKS passphrase for the main hard drive of our mail
server</description>
+ </secret></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
index 0000000..0960d86
--- /dev/null
+++ b/docs/formatsecret.html.in
@@ -0,0 +1,46 @@
+<html>
+ <body>
+ <h1>Secret attributes XML format</h1>
+
+ <ul id="toc"></ul>
+
+ <h2><a name="SecretAttributes">Secret attributes
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>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>
+ <secret ephemeral='no' private='yes'>
+ <volume>/var/lib/libvirt/images/mail.img</volume>
+ <description>LUKS passphrase for the main hard drive of our mail
server</description>
+ </secret></pre>
+ </body>
+</html>
diff --git a/docs/formatstorage.html b/docs/formatstorage.html
index 91e63b4..e21e3d2 100644
--- 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 attribute 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 ef41a63..a064518 100644
--- 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
index 0000000..3d70412
--- /dev/null
+++ b/docs/schemas/secret.rng
@@ -0,0 +1,39 @@
+<!-- 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='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 f79a533..cf43088 100644
--- 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 attribute 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 9589878..4c4dfa4 100644
--- 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 attribute XML format</span>
+ </li>
</ul>
</li>
<li>
diff --git a/include/libvirt/libvirt.h b/include/libvirt/libvirt.h
index 86f56e5..eca9816 100644
--- a/include/libvirt/libvirt.h
+++ b/include/libvirt/libvirt.h
@@ -1448,6 +1448,30 @@ void virEventRegisterImpl(virEventAddHandleFunc addHandle,
virEventAddTimeoutFunc addTimeout,
virEventUpdateTimeoutFunc updateTimeout,
virEventRemoveTimeoutFunc removeTimeout);
+
+/*
+ * Secret manipulation API
+ */
+char * virSecretAllocateID (virConnectPtr conn);
+int virSecretSetXML (virConnectPtr conn,
+ const char *secret_id,
+ const char *xml);
+char * virSecretGetXML (virConnectPtr conn,
+ const char *secret_id);
+int virSecretSetValue (virConnectPtr conn,
+ const char *secret_id,
+ const void *secret,
+ size_t secret_size);
+void * virSecretGetValue (virConnectPtr conn,
+ const char *secret_id,
+ size_t *secret_size);
+int virSecretDelete (virConnectPtr conn,
+ const char *secret_id);
+int virSecretNumOfSecrets (virConnectPtr conn);
+int virSecretListSecrets (virConnectPtr conn,
+ char **ids,
+ int maxids);
+
#ifdef __cplusplus
}
#endif
diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index e6536c7..093c89e 100644
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -1448,6 +1448,30 @@ void virEventRegisterImpl(virEventAddHandleFunc addHandle,
virEventAddTimeoutFunc addTimeout,
virEventUpdateTimeoutFunc updateTimeout,
virEventRemoveTimeoutFunc removeTimeout);
+
+/*
+ * Secret manipulation API
+ */
+char * virSecretAllocateID (virConnectPtr conn);
+int virSecretSetXML (virConnectPtr conn,
+ const char *secret_id,
+ const char *xml);
+char * virSecretGetXML (virConnectPtr conn,
+ const char *secret_id);
+int virSecretSetValue (virConnectPtr conn,
+ const char *secret_id,
+ const void *secret,
+ size_t secret_size);
+void * virSecretGetValue (virConnectPtr conn,
+ const char *secret_id,
+ size_t *secret_size);
+int virSecretDelete (virConnectPtr conn,
+ const char *secret_id);
+int virSecretNumOfSecrets (virConnectPtr conn);
+int virSecretListSecrets (virConnectPtr conn,
+ char **ids,
+ int maxids);
+
#ifdef __cplusplus
}
#endif
diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
index c06f51e..fc21082 100644
--- a/src/libvirt_public.syms
+++ b/src/libvirt_public.syms
@@ -289,6 +289,14 @@ LIBVIRT_0.7.0 {
global:
virConnectNumOfDefinedInterfaces;
virConnectListDefinedInterfaces;
+ virSecretAllocateID;
+ virSecretSetXML;
+ virSecretGetXML;
+ virSecretSetValue;
+ virSecretGetValue;
+ virSecretDelete;
+ virSecretNumOfSecrets;
+ virSecretListSecrets;
} LIBVIRT_0.6.4;
# .... define new API here using predicted next version number ....
--
1.6.2.5