Move virSecret related APIs out of libvirt.c

Introduce a src/libvirt-secret.c file to hold all the
methods related to the virSecret type.

docs/apibuild.py

@@ -29,6 +29,7 @@ included_files = {
   "libvirt-network.c": "Network interfaces for the libvirt library",
   "libvirt-nodedev.c": "Node device interfaces for the libvirt library",
   "libvirt-nwfilter.c": "NWFilter interfaces for the libvirt library",
+  "libvirt-secret.c": "Secret interfaces for the libvirt library",
   "virerror.c": "implements error handling and reporting code for libvirt",
   "virevent.c": "event loop for monitoring file handles",
   "virtypedparam.c": "virTypedParameters APIs",

po/POTFILES.in

@@ -61,6 +61,7 @@ src/libvirt-domain-snapshot.c
 src/libvirt-lxc.c
 src/libvirt-network.c
 src/libvirt-nwfilter.c
+src/libvirt-secret.c
 src/libvirt-qemu.c
 src/locking/lock_daemon.c
 src/locking/lock_daemon_config.c

src/Makefile.am

@@ -194,6 +194,7 @@ DRIVER_SOURCES =							\
 		libvirt-network.c	 				\
 		libvirt-nodedev.c	 				\
 		libvirt-nwfilter.c	 				\
+		libvirt-secret.c	 				\
 		locking/lock_manager.c locking/lock_manager.h		\
 		locking/lock_driver.h					\
 		locking/lock_driver_nop.h locking/lock_driver_nop.c	\
@@ -2196,6 +2197,7 @@ libvirt_setuid_rpc_client_la_SOURCES = 		\
 		libvirt-network.c		\
 		libvirt-nodedev.c		\
 		libvirt-nwfilter.c		\
+		libvirt-secret.c		\
 		libvirt-lxc.c			\
 		$(NULL)
 

src/libvirt-secret.c

+/*
+ * libvirt-secret.c: entry points for virSecretPtr APIs
+ *
+ * Copyright (C) 2006-2014 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library.  If not, see
+ * <http://www.gnu.org/licenses/>.
+ */
+
+#include <config.h>
+
+#include "datatypes.h"
+#include "virlog.h"
+
+VIR_LOG_INIT("libvirt.secret");
+
+#define VIR_FROM_THIS VIR_FROM_SECRET
+
+/**
+ * virSecretGetConnect:
+ * @secret: A virSecret secret
+ *
+ * Provides the connection pointer associated with a secret.  The reference
+ * counter on the connection is not increased by this call.
+ *
+ * WARNING: When writing libvirt bindings in other languages, do not use this
+ * function.  Instead, store the connection and the secret object together.
+ *
+ * Returns the virConnectPtr or NULL in case of failure.
+ */
+virConnectPtr
+virSecretGetConnect(virSecretPtr secret)
+{
+    VIR_DEBUG("secret=%p", secret);
+
+    virResetLastError();
+
+    virCheckSecretReturn(secret, NULL);
+
+    return secret->conn;
+}
+
+
+/**
+ * virConnectNumOfSecrets:
+ * @conn: virConnect connection
+ *
+ * Fetch number of currently defined secrets.
+ *
+ * Returns the number currently defined secrets.
+ */
+int
+virConnectNumOfSecrets(virConnectPtr conn)
+{
+    VIR_DEBUG("conn=%p", conn);
+
+    virResetLastError();
+
+    virCheckConnectReturn(conn, -1);
+
+    if (conn->secretDriver != NULL &&
+        conn->secretDriver->connectNumOfSecrets != NULL) {
+        int ret;
+
+        ret = conn->secretDriver->connectNumOfSecrets(conn);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return -1;
+}
+
+
+/**
+ * virConnectListAllSecrets:
+ * @conn: Pointer to the hypervisor connection.
+ * @secrets: Pointer to a variable to store the array containing the secret
+ *           objects or NULL if the list is not required (just returns the
+ *           number of secrets).
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * Collect the list of secrets, and allocate an array to store those
+ * objects.
+ *
+ * Normally, all secrets are returned; however, @flags can be used to
+ * filter the results for a smaller list of targeted secrets. The valid
+ * flags are divided into groups, where each group contains bits that
+ * describe mutually exclusive attributes of a secret, and where all bits
+ * within a group describe all possible secrets.
+ *
+ * The first group of @flags is used to filter secrets by its storage
+ * location. Flag VIR_CONNECT_LIST_SECRETS_EPHEMERAL selects secrets that
+ * are kept only in memory. Flag VIR_CONNECT_LIST_SECRETS_NO_EPHEMERAL
+ * selects secrets that are kept in persistent storage.
+ *
+ * The second group of @flags is used to filter secrets by privacy. Flag
+ * VIR_CONNECT_LIST_SECRETS_PRIVATE seclets secrets that are never revealed
+ * to any caller of libvirt nor to any other node. Flag
+ * VIR_CONNECT_LIST_SECRETS_NO_PRIVATE selects non-private secrets.
+ *
+ * Returns the number of secrets found or -1 and sets @secrets to NULL in case
+ * of error.  On success, the array stored into @secrets is guaranteed to
+ * have an extra allocated element set to NULL but not included in the return count,
+ * to make iteration easier.  The caller is responsible for calling
+ * virSecretFree() on each array element, then calling free() on @secrets.
+ */
+int
+virConnectListAllSecrets(virConnectPtr conn,
+                         virSecretPtr **secrets,
+                         unsigned int flags)
+{
+    VIR_DEBUG("conn=%p, secrets=%p, flags=%x", conn, secrets, flags);
+
+    virResetLastError();
+
+    if (secrets)
+        *secrets = NULL;
+
+    virCheckConnectReturn(conn, -1);
+
+    if (conn->secretDriver &&
+        conn->secretDriver->connectListAllSecrets) {
+        int ret;
+        ret = conn->secretDriver->connectListAllSecrets(conn, secrets, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return -1;
+}
+
+
+/**
+ * virConnectListSecrets:
+ * @conn: virConnect connection
+ * @uuids: Pointer to an array to store the UUIDs
+ * @maxuuids: size of the array.
+ *
+ * List UUIDs of defined secrets, store pointers to names in uuids.
+ *
+ * Returns the number of UUIDs provided in the array, or -1 on failure.
+ */
+int
+virConnectListSecrets(virConnectPtr conn, char **uuids, int maxuuids)
+{
+    VIR_DEBUG("conn=%p, uuids=%p, maxuuids=%d", conn, uuids, maxuuids);
+
+    virResetLastError();
+
+    virCheckConnectReturn(conn, -1);
+    virCheckNonNullArgGoto(uuids, error);
+    virCheckNonNegativeArgGoto(maxuuids, error);
+
+    if (conn->secretDriver != NULL && conn->secretDriver->connectListSecrets != NULL) {
+        int ret;
+
+        ret = conn->secretDriver->connectListSecrets(conn, uuids, maxuuids);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return -1;
+}
+
+
+/**
+ * virSecretLookupByUUID:
+ * @conn: pointer to the hypervisor connection
+ * @uuid: the raw UUID for the secret
+ *
+ * Try to lookup a secret on the given hypervisor based on its UUID.
+ * Uses the 16 bytes of raw data to describe the UUID
+ *
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
+ * Returns a new secret object or NULL in case of failure.  If the
+ * secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
+ */
+virSecretPtr
+virSecretLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
+{
+    VIR_UUID_DEBUG(conn, uuid);
+
+    virResetLastError();
+
+    virCheckConnectReturn(conn, NULL);
+    virCheckNonNullArgGoto(uuid, error);
+
+    if (conn->secretDriver &&
+        conn->secretDriver->secretLookupByUUID) {
+        virSecretPtr ret;
+        ret = conn->secretDriver->secretLookupByUUID(conn, uuid);
+        if (!ret)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return NULL;
+}
+
+
+/**
+ * virSecretLookupByUUIDString:
+ * @conn: pointer to the hypervisor connection
+ * @uuidstr: the string UUID for the secret
+ *
+ * Try to lookup a secret on the given hypervisor based on its UUID.
+ * Uses the printable string value to describe the UUID
+ *
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
+ * Returns a new secret object or NULL in case of failure.  If the
+ * secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
+ */
+virSecretPtr
+virSecretLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
+{
+    unsigned char uuid[VIR_UUID_BUFLEN];
+    VIR_DEBUG("conn=%p, uuidstr=%s", conn, NULLSTR(uuidstr));
+
+    virResetLastError();
+
+    virCheckConnectReturn(conn, NULL);
+    virCheckNonNullArgGoto(uuidstr, error);
+
+    if (virUUIDParse(uuidstr, uuid) < 0) {
+        virReportInvalidArg(uuidstr,
+                            _("uuidstr in %s must be a valid UUID"),
+                            __FUNCTION__);
+        goto error;
+    }
+
+    return virSecretLookupByUUID(conn, &uuid[0]);
+
+ error:
+    virDispatchError(conn);
+    return NULL;
+}
+
+
+/**
+ * virSecretLookupByUsage:
+ * @conn: pointer to the hypervisor connection
+ * @usageType: the type of secret usage
+ * @usageID: identifier of the object using the secret
+ *
+ * Try to lookup a secret on the given hypervisor based on its usage
+ * The usageID is unique within the set of secrets sharing the
+ * same usageType value.
+ *
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
+ * Returns a new secret object or NULL in case of failure.  If the
+ * secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
+ */
+virSecretPtr
+virSecretLookupByUsage(virConnectPtr conn,
+                       int usageType,
+                       const char *usageID)
+{
+    VIR_DEBUG("conn=%p, usageType=%d usageID=%s", conn, usageType, NULLSTR(usageID));
+
+    virResetLastError();
+
+    virCheckConnectReturn(conn, NULL);
+    virCheckNonNullArgGoto(usageID, error);
+
+    if (conn->secretDriver &&
+        conn->secretDriver->secretLookupByUsage) {
+        virSecretPtr ret;
+        ret = conn->secretDriver->secretLookupByUsage(conn, usageType, usageID);
+        if (!ret)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return NULL;
+}
+
+
+/**
+ * virSecretDefineXML:
+ * @conn: virConnect connection
+ * @xml: XML describing the secret.
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * If XML specifies a UUID, locates the specified secret and replaces all
+ * attributes of the secret specified by UUID by attributes specified in xml
+ * (any attributes not specified in xml are discarded).
+ *
+ * Otherwise, creates a new secret with an automatically chosen UUID, and
+ * initializes its attributes from xml.
+ *
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
+ * Returns a secret on success, NULL on failure.
+ */
+virSecretPtr
+virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
+{
+    VIR_DEBUG("conn=%p, xml=%s, flags=%x", conn, xml, flags);
+
+    virResetLastError();
+
+    virCheckConnectReturn(conn, NULL);
+    virCheckReadOnlyGoto(conn->flags, error);
+    virCheckNonNullArgGoto(xml, error);
+
+    if (conn->secretDriver != NULL && conn->secretDriver->secretDefineXML != NULL) {
+        virSecretPtr ret;
+
+        ret = conn->secretDriver->secretDefineXML(conn, xml, flags);
+        if (ret == NULL)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return NULL;
+}
+
+
+/**
+ * virSecretGetUUID:
+ * @secret: A virSecret secret
+ * @uuid: buffer of VIR_UUID_BUFLEN bytes in size
+ *
+ * Fetches the UUID of the secret.
+ *
+ * Returns 0 on success with the uuid buffer being filled, or
+ * -1 upon failure.
+ */
+int
+virSecretGetUUID(virSecretPtr secret, unsigned char *uuid)
+{
+    VIR_DEBUG("secret=%p", secret);
+
+    virResetLastError();
+
+    virCheckSecretReturn(secret, -1);
+    virCheckNonNullArgGoto(uuid, error);
+
+    memcpy(uuid, &secret->uuid[0], VIR_UUID_BUFLEN);
+
+    return 0;
+
+ error:
+    virDispatchError(secret->conn);
+    return -1;
+}
+
+
+/**
+ * virSecretGetUUIDString:
+ * @secret: a secret object
+ * @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
+ *
+ * Get the UUID for a secret as string. For more information about
+ * UUID see RFC4122.
+ *
+ * Returns -1 in case of error, 0 in case of success
+ */
+int
+virSecretGetUUIDString(virSecretPtr secret, char *buf)
+{
+    VIR_DEBUG("secret=%p, buf=%p", secret, buf);
+
+    virResetLastError();
+
+    virCheckSecretReturn(secret, -1);
+    virCheckNonNullArgGoto(buf, error);
+
+    virUUIDFormat(secret->uuid, buf);
+    return 0;
+
+ error:
+    virDispatchError(secret->conn);
+    return -1;
+}
+
+
+/**
+ * virSecretGetUsageType:
+ * @secret: a secret object
+ *
+ * Get the type of object which uses this secret. The returned
+ * value is one of the constants defined in the virSecretUsageType
+ * enumeration. More values may be added to this enumeration in
+ * the future, so callers should expect to see usage types they
+ * do not explicitly know about.
+ *
+ * Returns a positive integer identifying the type of object,
+ * or -1 upon error.
+ */
+int
+virSecretGetUsageType(virSecretPtr secret)
+{
+    VIR_DEBUG("secret=%p", secret);
+
+    virResetLastError();
+
+    virCheckSecretReturn(secret, -1);
+
+    return secret->usageType;
+}
+
+
+/**
+ * virSecretGetUsageID:
+ * @secret: a secret object
+ *
+ * Get the unique identifier of the object with which this
+ * secret is to be used. The format of the identifier is
+ * dependant on the usage type of the secret. For a secret
+ * with a usage type of VIR_SECRET_USAGE_TYPE_VOLUME the
+ * identifier will be a fully qualfied path name. The
+ * identifiers are intended to be unique within the set of
+ * all secrets sharing the same usage type. ie, there shall
+ * only ever be one secret for each volume path.
+ *
+ * Returns a string identifying the object using the secret,
+ * or NULL upon error
+ */
+const char *
+virSecretGetUsageID(virSecretPtr secret)
+{
+    VIR_DEBUG("secret=%p", secret);
+
+    virResetLastError();
+
+    virCheckSecretReturn(secret, NULL);
+
+    return secret->usageID;
+}
+
+
+/**
+ * virSecretGetXMLDesc:
+ * @secret: A virSecret secret
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * Fetches an XML document describing attributes of the secret.
+ *
+ * Returns the XML document on success, NULL on failure.  The caller must
+ * free() the XML.
+ */
+char *
+virSecretGetXMLDesc(virSecretPtr secret, unsigned int flags)
+{
+    virConnectPtr conn;
+
+    VIR_DEBUG("secret=%p, flags=%x", secret, flags);
+
+    virResetLastError();
+
+    virCheckSecretReturn(secret, NULL);
+    conn = secret->conn;
+
+    if (conn->secretDriver != NULL && conn->secretDriver->secretGetXMLDesc != NULL) {
+        char *ret;
+
+        ret = conn->secretDriver->secretGetXMLDesc(secret, flags);
+        if (ret == NULL)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return NULL;
+}
+
+
+/**
+ * virSecretSetValue:
+ * @secret: A virSecret secret
+ * @value: Value of the secret
+ * @value_size: Size of the value
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * Sets the value of a secret.
+ *
+ * Returns 0 on success, -1 on failure.
+ */
+int
+virSecretSetValue(virSecretPtr secret, const unsigned char *value,
+                  size_t value_size, unsigned int flags)
+{
+    virConnectPtr conn;
+
+    VIR_DEBUG("secret=%p, value=%p, value_size=%zu, flags=%x", secret, value,
+              value_size, flags);
+
+    virResetLastError();
+
+    virCheckSecretReturn(secret, -1);
+    conn = secret->conn;
+
+    virCheckReadOnlyGoto(conn->flags, error);
+    virCheckNonNullArgGoto(value, error);
+
+    if (conn->secretDriver != NULL && conn->secretDriver->secretSetValue != NULL) {
+        int ret;
+
+        ret = conn->secretDriver->secretSetValue(secret, value, value_size, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return -1;
+}
+
+
+/**
+ * virSecretGetValue:
+ * @secret: A virSecret connection
+ * @value_size: Place for storing size of the secret value
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * Fetches the value of a secret.
+ *
+ * Returns the secret value on success, NULL on failure.  The caller must
+ * free() the secret value.
+ */
+unsigned char *
+virSecretGetValue(virSecretPtr secret, size_t *value_size, unsigned int flags)
+{
+    virConnectPtr conn;
+
+    VIR_DEBUG("secret=%p, value_size=%p, flags=%x", secret, value_size, flags);
+
+    virResetLastError();
+
+    virCheckSecretReturn(secret, NULL);
+    conn = secret->conn;
+
+    virCheckReadOnlyGoto(conn->flags, error);
+    virCheckNonNullArgGoto(value_size, error);
+
+    if (conn->secretDriver != NULL && conn->secretDriver->secretGetValue != NULL) {
+        unsigned char *ret;
+
+        ret = conn->secretDriver->secretGetValue(secret, value_size, flags, 0);
+        if (ret == NULL)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return NULL;
+}
+
+
+/**
+ * virSecretUndefine:
+ * @secret: A virSecret secret
+ *
+ * Deletes the specified secret.  This does not free the associated
+ * virSecretPtr object.
+ *
+ * Returns 0 on success, -1 on failure.
+ */
+int
+virSecretUndefine(virSecretPtr secret)
+{
+    virConnectPtr conn;
+
+    VIR_DEBUG("secret=%p", secret);
+
+    virResetLastError();
+
+    virCheckSecretReturn(secret, -1);
+    conn = secret->conn;
+
+    virCheckReadOnlyGoto(conn->flags, error);
+
+    if (conn->secretDriver != NULL && conn->secretDriver->secretUndefine != NULL) {
+        int ret;
+
+        ret = conn->secretDriver->secretUndefine(secret);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return -1;
+}
+
+
+/**
+ * virSecretRef:
+ * @secret: the secret to hold a reference on
+ *
+ * Increment the reference count on the secret. For each additional call to
+ * this method, there shall be a corresponding call to virSecretFree to release
+ * the reference count, once the caller no longer needs the reference to this
+ * object.
+ *
+ * This method is typically useful for applications where multiple threads are
+ * using a connection, and it is required that the connection remain open until
+ * all threads have finished using it. ie, each new thread using a secret would
+ * increment the reference count.
+ *
+ * Returns 0 in case of success, -1 in case of failure.
+ */
+int
+virSecretRef(virSecretPtr secret)
+{
+    VIR_DEBUG("secret=%p refs=%d", secret,
+              secret ? secret->object.u.s.refs : 0);
+
+    virResetLastError();
+
+    virCheckSecretReturn(secret, -1);
+
+    virObjectRef(secret);
+    return 0;
+}
+
+
+/**
+ * virSecretFree:
+ * @secret: pointer to a secret
+ *
+ * Release the secret handle. The underlying secret continues to exist.
+ *
+ * Returns 0 on success, or -1 on error
+ */
+int
+virSecretFree(virSecretPtr secret)
+{
+    VIR_DEBUG("secret=%p", secret);
+
+    virResetLastError();
+
+    virCheckSecretReturn(secret, -1);
+
+    virObjectUnref(secret);
+    return 0;
+}

src/libvirt.c

@@ -12808,674 +12808,6 @@ virConnectDomainEventDeregister(virConnectPtr conn,
 }
 
 
-/**
- * virSecretGetConnect:
- * @secret: A virSecret secret
- *
- * Provides the connection pointer associated with a secret.  The reference
- * counter on the connection is not increased by this call.
- *
- * WARNING: When writing libvirt bindings in other languages, do not use this
- * function.  Instead, store the connection and the secret object together.
- *
- * Returns the virConnectPtr or NULL in case of failure.
- */
-virConnectPtr
-virSecretGetConnect(virSecretPtr secret)
-{
-    VIR_DEBUG("secret=%p", secret);
-
-    virResetLastError();
-
-    virCheckSecretReturn(secret, NULL);
-
-    return secret->conn;
-}
-
-
-/**
- * virConnectNumOfSecrets:
- * @conn: virConnect connection
- *
- * Fetch number of currently defined secrets.
- *
- * Returns the number currently defined secrets.
- */
-int
-virConnectNumOfSecrets(virConnectPtr conn)
-{
-    VIR_DEBUG("conn=%p", conn);
-
-    virResetLastError();
-
-    virCheckConnectReturn(conn, -1);
-
-    if (conn->secretDriver != NULL &&
-        conn->secretDriver->connectNumOfSecrets != NULL) {
-        int ret;
-
-        ret = conn->secretDriver->connectNumOfSecrets(conn);
-        if (ret < 0)
-            goto error;
-        return ret;
-    }
-
-    virReportUnsupportedError();
-
- error:
-    virDispatchError(conn);
-    return -1;
-}
-
-
-/**
- * virConnectListAllSecrets:
- * @conn: Pointer to the hypervisor connection.
- * @secrets: Pointer to a variable to store the array containing the secret
- *           objects or NULL if the list is not required (just returns the
- *           number of secrets).
- * @flags: extra flags; not used yet, so callers should always pass 0
- *
- * Collect the list of secrets, and allocate an array to store those
- * objects.
- *
- * Normally, all secrets are returned; however, @flags can be used to
- * filter the results for a smaller list of targeted secrets. The valid
- * flags are divided into groups, where each group contains bits that
- * describe mutually exclusive attributes of a secret, and where all bits
- * within a group describe all possible secrets.
- *
- * The first group of @flags is used to filter secrets by its storage
- * location. Flag VIR_CONNECT_LIST_SECRETS_EPHEMERAL selects secrets that
- * are kept only in memory. Flag VIR_CONNECT_LIST_SECRETS_NO_EPHEMERAL
- * selects secrets that are kept in persistent storage.
- *
- * The second group of @flags is used to filter secrets by privacy. Flag
- * VIR_CONNECT_LIST_SECRETS_PRIVATE seclets secrets that are never revealed
- * to any caller of libvirt nor to any other node. Flag
- * VIR_CONNECT_LIST_SECRETS_NO_PRIVATE selects non-private secrets.
- *
- * Returns the number of secrets found or -1 and sets @secrets to NULL in case
- * of error.  On success, the array stored into @secrets is guaranteed to
- * have an extra allocated element set to NULL but not included in the return count,
- * to make iteration easier.  The caller is responsible for calling
- * virSecretFree() on each array element, then calling free() on @secrets.
- */
-int
-virConnectListAllSecrets(virConnectPtr conn,
-                         virSecretPtr **secrets,
-                         unsigned int flags)
-{
-    VIR_DEBUG("conn=%p, secrets=%p, flags=%x", conn, secrets, flags);
-
-    virResetLastError();
-
-    if (secrets)
-        *secrets = NULL;
-
-    virCheckConnectReturn(conn, -1);
-
-    if (conn->secretDriver &&
-        conn->secretDriver->connectListAllSecrets) {
-        int ret;
-        ret = conn->secretDriver->connectListAllSecrets(conn, secrets, flags);
-        if (ret < 0)
-            goto error;
-        return ret;
-    }
-
-    virReportUnsupportedError();
-
- error:
-    virDispatchError(conn);
-    return -1;
-}
-
-
-/**
- * virConnectListSecrets:
- * @conn: virConnect connection
- * @uuids: Pointer to an array to store the UUIDs
- * @maxuuids: size of the array.
- *
- * List UUIDs of defined secrets, store pointers to names in uuids.
- *
- * Returns the number of UUIDs provided in the array, or -1 on failure.
- */
-int
-virConnectListSecrets(virConnectPtr conn, char **uuids, int maxuuids)
-{
-    VIR_DEBUG("conn=%p, uuids=%p, maxuuids=%d", conn, uuids, maxuuids);
-
-    virResetLastError();
-
-    virCheckConnectReturn(conn, -1);
-    virCheckNonNullArgGoto(uuids, error);
-    virCheckNonNegativeArgGoto(maxuuids, error);
-
-    if (conn->secretDriver != NULL && conn->secretDriver->connectListSecrets != NULL) {
-        int ret;
-
-        ret = conn->secretDriver->connectListSecrets(conn, uuids, maxuuids);
-        if (ret < 0)
-            goto error;
-        return ret;
-    }
-
-    virReportUnsupportedError();
-
- error:
-    virDispatchError(conn);
-    return -1;
-}
-
-
-/**
- * virSecretLookupByUUID:
- * @conn: pointer to the hypervisor connection
- * @uuid: the raw UUID for the secret
- *
- * Try to lookup a secret on the given hypervisor based on its UUID.
- * Uses the 16 bytes of raw data to describe the UUID
- *
- * virSecretFree should be used to free the resources after the
- * secret object is no longer needed.
- *
- * Returns a new secret object or NULL in case of failure.  If the
- * secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
- */
-virSecretPtr
-virSecretLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
-{
-    VIR_UUID_DEBUG(conn, uuid);
-
-    virResetLastError();
-
-    virCheckConnectReturn(conn, NULL);
-    virCheckNonNullArgGoto(uuid, error);
-
-    if (conn->secretDriver &&
-        conn->secretDriver->secretLookupByUUID) {
-        virSecretPtr ret;
-        ret = conn->secretDriver->secretLookupByUUID(conn, uuid);
-        if (!ret)
-            goto error;
-        return ret;
-    }
-
-    virReportUnsupportedError();
-
- error:
-    virDispatchError(conn);
-    return NULL;
-}
-
-
-/**
- * virSecretLookupByUUIDString:
- * @conn: pointer to the hypervisor connection
- * @uuidstr: the string UUID for the secret
- *
- * Try to lookup a secret on the given hypervisor based on its UUID.
- * Uses the printable string value to describe the UUID
- *
- * virSecretFree should be used to free the resources after the
- * secret object is no longer needed.
- *
- * Returns a new secret object or NULL in case of failure.  If the
- * secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
- */
-virSecretPtr
-virSecretLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
-{
-    unsigned char uuid[VIR_UUID_BUFLEN];
-    VIR_DEBUG("conn=%p, uuidstr=%s", conn, NULLSTR(uuidstr));
-
-    virResetLastError();
-
-    virCheckConnectReturn(conn, NULL);
-    virCheckNonNullArgGoto(uuidstr, error);
-
-    if (virUUIDParse(uuidstr, uuid) < 0) {
-        virReportInvalidArg(uuidstr,
-                            _("uuidstr in %s must be a valid UUID"),
-                            __FUNCTION__);
-        goto error;
-    }
-
-    return virSecretLookupByUUID(conn, &uuid[0]);
-
- error:
-    virDispatchError(conn);
-    return NULL;
-}
-
-
-/**
- * virSecretLookupByUsage:
- * @conn: pointer to the hypervisor connection
- * @usageType: the type of secret usage
- * @usageID: identifier of the object using the secret
- *
- * Try to lookup a secret on the given hypervisor based on its usage
- * The usageID is unique within the set of secrets sharing the
- * same usageType value.
- *
- * virSecretFree should be used to free the resources after the
- * secret object is no longer needed.
- *
- * Returns a new secret object or NULL in case of failure.  If the
- * secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
- */
-virSecretPtr
-virSecretLookupByUsage(virConnectPtr conn,
-                       int usageType,
-                       const char *usageID)
-{
-    VIR_DEBUG("conn=%p, usageType=%d usageID=%s", conn, usageType, NULLSTR(usageID));
-
-    virResetLastError();
-
-    virCheckConnectReturn(conn, NULL);
-    virCheckNonNullArgGoto(usageID, error);
-
-    if (conn->secretDriver &&
-        conn->secretDriver->secretLookupByUsage) {
-        virSecretPtr ret;
-        ret = conn->secretDriver->secretLookupByUsage(conn, usageType, usageID);
-        if (!ret)
-            goto error;
-        return ret;
-    }
-
-    virReportUnsupportedError();
-
- error:
-    virDispatchError(conn);
-    return NULL;
-}
-
-
-/**
- * virSecretDefineXML:
- * @conn: virConnect connection
- * @xml: XML describing the secret.
- * @flags: extra flags; not used yet, so callers should always pass 0
- *
- * If XML specifies a UUID, locates the specified secret and replaces all
- * attributes of the secret specified by UUID by attributes specified in xml
- * (any attributes not specified in xml are discarded).
- *
- * Otherwise, creates a new secret with an automatically chosen UUID, and
- * initializes its attributes from xml.
- *
- * virSecretFree should be used to free the resources after the
- * secret object is no longer needed.
- *
- * Returns a secret on success, NULL on failure.
- */
-virSecretPtr
-virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
-{
-    VIR_DEBUG("conn=%p, xml=%s, flags=%x", conn, xml, flags);
-
-    virResetLastError();
-
-    virCheckConnectReturn(conn, NULL);
-    virCheckReadOnlyGoto(conn->flags, error);
-    virCheckNonNullArgGoto(xml, error);
-
-    if (conn->secretDriver != NULL && conn->secretDriver->secretDefineXML != NULL) {
-        virSecretPtr ret;
-
-        ret = conn->secretDriver->secretDefineXML(conn, xml, flags);
-        if (ret == NULL)
-            goto error;
-        return ret;
-    }
-
-    virReportUnsupportedError();
-
- error:
-    virDispatchError(conn);
-    return NULL;
-}
-
-
-/**
- * virSecretGetUUID:
- * @secret: A virSecret secret
- * @uuid: buffer of VIR_UUID_BUFLEN bytes in size
- *
- * Fetches the UUID of the secret.
- *
- * Returns 0 on success with the uuid buffer being filled, or
- * -1 upon failure.
- */
-int
-virSecretGetUUID(virSecretPtr secret, unsigned char *uuid)
-{
-    VIR_DEBUG("secret=%p", secret);
-
-    virResetLastError();
-
-    virCheckSecretReturn(secret, -1);
-    virCheckNonNullArgGoto(uuid, error);
-
-    memcpy(uuid, &secret->uuid[0], VIR_UUID_BUFLEN);
-
-    return 0;
-
- error:
-    virDispatchError(secret->conn);
-    return -1;
-}
-
-
-/**
- * virSecretGetUUIDString:
- * @secret: a secret object
- * @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
- *
- * Get the UUID for a secret as string. For more information about
- * UUID see RFC4122.
- *
- * Returns -1 in case of error, 0 in case of success
- */
-int
-virSecretGetUUIDString(virSecretPtr secret, char *buf)
-{
-    VIR_DEBUG("secret=%p, buf=%p", secret, buf);
-
-    virResetLastError();
-
-    virCheckSecretReturn(secret, -1);
-    virCheckNonNullArgGoto(buf, error);
-
-    virUUIDFormat(secret->uuid, buf);
-    return 0;
-
- error:
-    virDispatchError(secret->conn);
-    return -1;
-}
-
-
-/**
- * virSecretGetUsageType:
- * @secret: a secret object
- *
- * Get the type of object which uses this secret. The returned
- * value is one of the constants defined in the virSecretUsageType
- * enumeration. More values may be added to this enumeration in
- * the future, so callers should expect to see usage types they
- * do not explicitly know about.
- *
- * Returns a positive integer identifying the type of object,
- * or -1 upon error.
- */
-int
-virSecretGetUsageType(virSecretPtr secret)
-{
-    VIR_DEBUG("secret=%p", secret);
-
-    virResetLastError();
-
-    virCheckSecretReturn(secret, -1);
-
-    return secret->usageType;
-}
-
-
-/**
- * virSecretGetUsageID:
- * @secret: a secret object
- *
- * Get the unique identifier of the object with which this
- * secret is to be used. The format of the identifier is
- * dependant on the usage type of the secret. For a secret
- * with a usage type of VIR_SECRET_USAGE_TYPE_VOLUME the
- * identifier will be a fully qualfied path name. The
- * identifiers are intended to be unique within the set of
- * all secrets sharing the same usage type. ie, there shall
- * only ever be one secret for each volume path.
- *
- * Returns a string identifying the object using the secret,
- * or NULL upon error
- */
-const char *
-virSecretGetUsageID(virSecretPtr secret)
-{
-    VIR_DEBUG("secret=%p", secret);
-
-    virResetLastError();
-
-    virCheckSecretReturn(secret, NULL);
-
-    return secret->usageID;
-}
-
-
-/**
- * virSecretGetXMLDesc:
- * @secret: A virSecret secret
- * @flags: extra flags; not used yet, so callers should always pass 0
- *
- * Fetches an XML document describing attributes of the secret.
- *
- * Returns the XML document on success, NULL on failure.  The caller must
- * free() the XML.
- */
-char *
-virSecretGetXMLDesc(virSecretPtr secret, unsigned int flags)
-{
-    virConnectPtr conn;
-
-    VIR_DEBUG("secret=%p, flags=%x", secret, flags);
-
-    virResetLastError();
-
-    virCheckSecretReturn(secret, NULL);
-    conn = secret->conn;
-
-    if (conn->secretDriver != NULL && conn->secretDriver->secretGetXMLDesc != NULL) {
-        char *ret;
-
-        ret = conn->secretDriver->secretGetXMLDesc(secret, flags);
-        if (ret == NULL)
-            goto error;
-        return ret;
-    }
-
-    virReportUnsupportedError();
-
- error:
-    virDispatchError(conn);
-    return NULL;
-}
-
-
-/**
- * virSecretSetValue:
- * @secret: A virSecret secret
- * @value: Value of the secret
- * @value_size: Size of the value
- * @flags: extra flags; not used yet, so callers should always pass 0
- *
- * Sets the value of a secret.
- *
- * Returns 0 on success, -1 on failure.
- */
-int
-virSecretSetValue(virSecretPtr secret, const unsigned char *value,
-                  size_t value_size, unsigned int flags)
-{
-    virConnectPtr conn;
-
-    VIR_DEBUG("secret=%p, value=%p, value_size=%zu, flags=%x", secret, value,
-              value_size, flags);
-
-    virResetLastError();
-
-    virCheckSecretReturn(secret, -1);
-    conn = secret->conn;
-
-    virCheckReadOnlyGoto(conn->flags, error);
-    virCheckNonNullArgGoto(value, error);
-
-    if (conn->secretDriver != NULL && conn->secretDriver->secretSetValue != NULL) {
-        int ret;
-
-        ret = conn->secretDriver->secretSetValue(secret, value, value_size, flags);
-        if (ret < 0)
-            goto error;
-        return ret;
-    }
-
-    virReportUnsupportedError();
-
- error:
-    virDispatchError(conn);
-    return -1;
-}
-
-
-/**
- * virSecretGetValue:
- * @secret: A virSecret connection
- * @value_size: Place for storing size of the secret value
- * @flags: extra flags; not used yet, so callers should always pass 0
- *
- * Fetches the value of a secret.
- *
- * Returns the secret value on success, NULL on failure.  The caller must
- * free() the secret value.
- */
-unsigned char *
-virSecretGetValue(virSecretPtr secret, size_t *value_size, unsigned int flags)
-{
-    virConnectPtr conn;
-
-    VIR_DEBUG("secret=%p, value_size=%p, flags=%x", secret, value_size, flags);
-
-    virResetLastError();
-
-    virCheckSecretReturn(secret, NULL);
-    conn = secret->conn;
-
-    virCheckReadOnlyGoto(conn->flags, error);
-    virCheckNonNullArgGoto(value_size, error);
-
-    if (conn->secretDriver != NULL && conn->secretDriver->secretGetValue != NULL) {
-        unsigned char *ret;
-
-        ret = conn->secretDriver->secretGetValue(secret, value_size, flags, 0);
-        if (ret == NULL)
-            goto error;
-        return ret;
-    }
-
-    virReportUnsupportedError();
-
- error:
-    virDispatchError(conn);
-    return NULL;
-}
-
-
-/**
- * virSecretUndefine:
- * @secret: A virSecret secret
- *
- * Deletes the specified secret.  This does not free the associated
- * virSecretPtr object.
- *
- * Returns 0 on success, -1 on failure.
- */
-int
-virSecretUndefine(virSecretPtr secret)
-{
-    virConnectPtr conn;
-
-    VIR_DEBUG("secret=%p", secret);
-
-    virResetLastError();
-
-    virCheckSecretReturn(secret, -1);
-    conn = secret->conn;
-
-    virCheckReadOnlyGoto(conn->flags, error);
-
-    if (conn->secretDriver != NULL && conn->secretDriver->secretUndefine != NULL) {
-        int ret;
-
-        ret = conn->secretDriver->secretUndefine(secret);
-        if (ret < 0)
-            goto error;
-        return ret;
-    }
-
-    virReportUnsupportedError();
-
- error:
-    virDispatchError(conn);
-    return -1;
-}
-
-
-/**
- * virSecretRef:
- * @secret: the secret to hold a reference on
- *
- * Increment the reference count on the secret. For each additional call to
- * this method, there shall be a corresponding call to virSecretFree to release
- * the reference count, once the caller no longer needs the reference to this
- * object.
- *
- * This method is typically useful for applications where multiple threads are
- * using a connection, and it is required that the connection remain open until
- * all threads have finished using it. ie, each new thread using a secret would
- * increment the reference count.
- *
- * Returns 0 in case of success, -1 in case of failure.
- */
-int
-virSecretRef(virSecretPtr secret)
-{
-    VIR_DEBUG("secret=%p refs=%d", secret,
-              secret ? secret->object.u.s.refs : 0);
-
-    virResetLastError();
-
-    virCheckSecretReturn(secret, -1);
-
-    virObjectRef(secret);
-    return 0;
-}
-
-
-/**
- * virSecretFree:
- * @secret: pointer to a secret
- *
- * Release the secret handle. The underlying secret continues to exist.
- *
- * Returns 0 on success, or -1 on error
- */
-int
-virSecretFree(virSecretPtr secret)
-{
-    VIR_DEBUG("secret=%p", secret);
-
-    virResetLastError();
-
-    virCheckSecretReturn(secret, -1);
-
-    virObjectUnref(secret);
-    return 0;
-}
-
-
 /**
  * virStreamNew:
  * @conn: pointer to the connection