From 6acc17af8c2e763988cb8e6c7d6ae03aeadf08e0 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Miloslav=20Trma=C4=8D?= Date: Tue, 28 Jul 2009 02:39:48 +0200 Subject: [PATCH] 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 --- docs/format.html | 4 + docs/formatcaps.html | 4 + docs/formatdomain.html | 4 + docs/formatnetwork.html | 4 + docs/formatnode.html | 4 + docs/formatsecret.html | 170 +++++++++++++++++++++++++++++++++++ docs/formatsecret.html.in | 52 +++++++++++ docs/formatstorage.html | 4 + docs/schemas/Makefile.am | 1 + docs/schemas/secret.rng | 44 +++++++++ docs/sitemap.html | 3 + docs/sitemap.html.in | 4 + include/libvirt/libvirt.h | 38 ++++++++ include/libvirt/libvirt.h.in | 38 ++++++++ libvirt.spec.in | 1 + mingw32-libvirt.spec.in | 1 + src/libvirt_public.syms | 16 ++++ 17 files changed, 392 insertions(+) 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 e97d0e7475..3c20b5fbc2 100644 --- a/docs/format.html +++ b/docs/format.html @@ -70,6 +70,10 @@
Node Devices
+
  • +
    + Secrets +
  • diff --git a/docs/formatcaps.html b/docs/formatcaps.html index 5b20aacfe8..5f2bc72723 100644 --- a/docs/formatcaps.html +++ b/docs/formatcaps.html @@ -70,6 +70,10 @@
    Node Devices
    +
  • +
    + Secrets +
  • diff --git a/docs/formatdomain.html b/docs/formatdomain.html index 5415200342..6b655ad443 100644 --- a/docs/formatdomain.html +++ b/docs/formatdomain.html @@ -70,6 +70,10 @@
    Node Devices
    +
  • +
    + Secrets +
  • diff --git a/docs/formatnetwork.html b/docs/formatnetwork.html index 0b25a0be11..72a3cda3c6 100644 --- a/docs/formatnetwork.html +++ b/docs/formatnetwork.html @@ -70,6 +70,10 @@
    Node Devices
    +
  • +
    + Secrets +
  • diff --git a/docs/formatnode.html b/docs/formatnode.html index 4d30b0c1d7..516c27b12c 100644 --- a/docs/formatnode.html +++ b/docs/formatnode.html @@ -70,6 +70,10 @@
    Node Devices
    +
  • +
    + Secrets +
  • diff --git a/docs/formatsecret.html b/docs/formatsecret.html new file mode 100644 index 0000000000..998e874d05 --- /dev/null +++ b/docs/formatsecret.html @@ -0,0 +1,170 @@ + + + + + + + + + libvirt: Secret XML format + + + + +
    + +
    +

    Secret XML format

    + +

    + Secret XML +

    +

    + Secrets stored by libvirt may have attributes associated with them, using + the secret element. The secret element has two + optional attributes, each with values 'yes' and + 'no', and defaulting to 'no': +

    +
    ephemeral
    This secret must only be kept in memory, never stored persistently. +
    private
    The value of the secret must not be revealed to any caller of libvirt, + nor to any other node. +
    +

    + The top-level secret element may contain the following + elements: +

    +
    uuid
    + An unique identifier for this secret (not necessarily in the UUID + format). If omitted when defining a new secret, a random UUID is + generated. +
    volume
    Key of a volume this secret is associated with. It is safe to delete + the secret after the volume is deleted. +
    description
    A human-readable description of the purpose of the secret. +
    +

    + Example +

    + 
    +      <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>
    +
    +
    + + + diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in new file mode 100644 index 0000000000..7471bf7207 --- /dev/null +++ b/docs/formatsecret.html.in @@ -0,0 +1,52 @@ + + +

    Secret XML format

    + + + +

    Secret XML

    + +

    + Secrets stored by libvirt may have attributes associated with them, using + the secret element. The secret element has two + optional attributes, each with values 'yes' and + 'no', and defaulting to 'no': +

    +
    +
    ephemeral
    +
    This secret must only be kept in memory, never stored persistently. +
    +
    private
    +
    The value of the secret must not be revealed to any caller of libvirt, + nor to any other node. +
    +
    +

    + The top-level secret element may contain the following + elements: +

    +
    +
    uuid
    +
    + An unique identifier for this secret (not necessarily in the UUID + format). If omitted when defining a new secret, a random UUID is + generated. +
    +
    volume
    +
    Key of a volume this secret is associated with. It is safe to delete + the secret after the volume is deleted. +
    +
    description
    +
    A human-readable description of the purpose of the secret. +
    +
    + +

    Example

    + + 
    +      <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>
    + + diff --git a/docs/formatstorage.html b/docs/formatstorage.html index 91e63b4c33..02cbcaca1c 100644 --- a/docs/formatstorage.html +++ b/docs/formatstorage.html @@ -70,6 +70,10 @@
    Node Devices
    +
  • +
    + Secrets +
  • diff --git a/docs/schemas/Makefile.am b/docs/schemas/Makefile.am index ef41a63aa9..a064518607 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 0000000000..05e04f21c4 --- /dev/null +++ b/docs/schemas/secret.rng @@ -0,0 +1,44 @@ + + + + + + + + + + + + yes + no + + + + + + + yes + no + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/sitemap.html b/docs/sitemap.html index f79a533fa5..901633d502 100644 --- a/docs/sitemap.html +++ b/docs/sitemap.html @@ -141,6 +141,9 @@
  • Node Devices The host device XML format +
  • + Secrets + The secret XML format
  • Drivers Hypervisor specific driver information diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in index 9589878464..2ed25c6cac 100644 --- a/docs/sitemap.html.in +++ b/docs/sitemap.html.in @@ -106,6 +106,10 @@ Node Devices The host device XML format
    • +
  • + Secrets + The secret XML format +
  • diff --git a/include/libvirt/libvirt.h b/include/libvirt/libvirt.h index 855f755601..1779b08961 100644 --- 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 e6536c78d0..8e26e4861c 100644 --- 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 067b83521e..966cdf137a 100644 --- 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 40a8124df1..093c45a08b 100644 --- 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 c06f51ec31..65080ed84e 100644 --- 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; -- 2.47.2