[libvirt] [PATCH 08/12] 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 | 1 + po/POTFILES.in | 1 + src/Makefile.am | 2 + src/libvirt-secret.c | 695 +++++++++++++++++++++++++++++++++++++++++++++++++++ src/libvirt.c | 668 ------------------------------------------------- 5 files changed, 699 insertions(+), 668 deletions(-) create mode 100644 src/libvirt-secret.c diff --git a/docs/apibuild.py b/docs/apibuild.py index cf329e2..90a816d 100755 --- a/docs/apibuild.py +++ b/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", diff --git a/po/POTFILES.in b/po/POTFILES.in index a628bb3..7d14790 100644 --- a/po/POTFILES.in +++ b/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 diff --git a/src/Makefile.am b/src/Makefile.am index dfc5920..62aca8a 100644 --- a/src/Makefile.am +++ b/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) diff --git a/src/libvirt-secret.c b/src/libvirt-secret.c new file mode 100644 index 0000000..bf6678c --- /dev/null +++ b/src/libvirt-secret.c @@ -0,0 +1,695 @@ +/* + * 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_NONE + +/** + * 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; +} diff --git a/src/libvirt.c b/src/libvirt.c index 79f9696..c40a132 100644 --- a/src/libvirt.c +++ b/src/libvirt.c @@ -12809,674 +12809,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 * @flags: bitwise-OR of virStreamFlags -- 2.1.0