SecretItem: Libsecret Library Reference Manual

SecretItem

SecretItem — A secret item

Functions

void	secret_item_create ()
SecretItem *	secret_item_create_finish ()
SecretItem *	secret_item_create_sync ()
void	secret_item_delete ()
gboolean	secret_item_delete_finish ()
gboolean	secret_item_delete_sync ()
gchar *	secret_item_get_schema_name ()
GHashTable *	secret_item_get_attributes ()
void	secret_item_set_attributes ()
gboolean	secret_item_set_attributes_finish ()
gboolean	secret_item_set_attributes_sync ()
guint64	secret_item_get_created ()
gchar *	secret_item_get_label ()
void	secret_item_set_label ()
gboolean	secret_item_set_label_finish ()
gboolean	secret_item_set_label_sync ()
SecretItemFlags	secret_item_get_flags ()
gboolean	secret_item_get_locked ()
guint64	secret_item_get_modified ()
SecretService *	secret_item_get_service ()
SecretValue *	secret_item_get_secret ()
void	secret_item_load_secret ()
gboolean	secret_item_load_secret_finish ()
gboolean	secret_item_load_secret_sync ()
void	secret_item_load_secrets ()
gboolean	secret_item_load_secrets_finish ()
gboolean	secret_item_load_secrets_sync ()
void	secret_item_set_secret ()
gboolean	secret_item_set_secret_finish ()
gboolean	secret_item_set_secret_sync ()
void	secret_item_refresh ()

Properties

GHashTable *	attributes	Read / Write
guint64	created	Read / Write
SecretItemFlags	flags	Read / Write / Construct Only
gchar *	label	Read / Write
gboolean	locked	Read
guint64	modified	Read / Write
SecretService *	service	Read / Write / Construct Only

Types and Values

	SecretItem
struct	SecretItemClass
enum	SecretItemFlags
enum	SecretItemCreateFlags

Object Hierarchy

    GFlags
    ╰── SecretItemFlags
    GObject
    ╰── GDBusProxy
        ╰── SecretItem

Implemented Interfaces

SecretItem implements GDBusInterface, GInitable and GAsyncInitable.

Includes

#include <libsecret/secret.h>

Description

SecretItem represents a secret item stored in the Secret Service.

Each item has a value, represented by a SecretValue, which can be retrieved by secret_item_get_secret() or set by secret_item_set_secret(). The item is only available when the item is not locked.

Items can be locked or unlocked using the secret_service_lock() or secret_service_unlock() functions. The Secret Service may not be able to unlock individual items, and may unlock an entire collection when a single item is unlocked.

Each item has a set of attributes, which are used to locate the item later. These are not stored or transferred in a secure manner. Each attribute has a string name and a string value. Use secret_service_search() to search for items based on their attributes, and secret_item_set_attributes() to change the attributes associated with an item.

Items can be created with secret_item_create() or secret_service_store().

Functions

secret_item_create ()

void
secret_item_create (SecretCollection *collection,
                    const SecretSchema *schema,
                    GHashTable *attributes,
                    const gchar *label,
                    SecretValue *value,
                    SecretItemCreateFlags flags,
                    GCancellable *cancellable,
                    GAsyncReadyCallback callback,
                    gpointer user_data);

Create a new item in the secret service.

If the flags contains SECRET_ITEM_CREATE_REPLACE, then the secret service will search for an item matching the attributes , and update that item instead of creating a new one.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. secret_service_prompt() will be used to handle any prompts that are required.

Parameters

collection	a secret collection to create this item in
schema	the schema for the attributes.	[allow-none]
attributes	attributes for the new item.	[element-type utf8 utf8]
label	label for the new item
value	secret value for the new item
flags	flags for the creation of the new item
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to pass to the callback

secret_item_create_finish ()

SecretItem *
secret_item_create_finish (GAsyncResult *result,
                           GError **error);

Finish operation to create a new item in the secret service.

Parameters

result	the asynchronous result passed to the callback
error	location to place an error on failure

Returns

the new item, which should be unreferenced with g_object_unref().

[transfer full]

secret_item_create_sync ()

SecretItem *
secret_item_create_sync (SecretCollection *collection,
                         const SecretSchema *schema,
                         GHashTable *attributes,
                         const gchar *label,
                         SecretValue *value,
                         SecretItemCreateFlags flags,
                         GCancellable *cancellable,
                         GError **error);

Create a new item in the secret service.

If the flags contains SECRET_ITEM_CREATE_REPLACE, then the secret service will search for an item matching the attributes , and update that item instead of creating a new one.

Parameters

collection	a secret collection to create this item in
schema	the schema for the attributes.	[allow-none]
attributes	attributes for the new item.	[element-type utf8 utf8]
label	label for the new item
value	secret value for the new item
flags	flags for the creation of the new item
cancellable	optional cancellation object
error	location to place an error on failure

Returns

the new item, which should be unreferenced with g_object_unref().

[transfer full]

secret_item_delete ()

void
secret_item_delete (SecretItem *self,
                    GCancellable *cancellable,
                    GAsyncReadyCallback callback,
                    gpointer user_data);

Delete this item.

This method returns immediately and completes asynchronously. The secret service may prompt the user. secret_service_prompt() will be used to handle any prompts that show up.

Parameters

self	an item
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to pass to the callback

secret_item_delete_finish ()

gboolean
secret_item_delete_finish (SecretItem *self,
                           GAsyncResult *result,
                           GError **error);

Complete asynchronous operation to delete the secret item.

Parameters

self	an item
result	asynchronous result passed to the callback
error	location to place an error on failure

Returns

whether the item was successfully deleted or not

secret_item_delete_sync ()

gboolean
secret_item_delete_sync (SecretItem *self,
                         GCancellable *cancellable,
                         GError **error);

Delete this secret item.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. secret_service_prompt() will be used to handle any prompts that show up.

Parameters

self	an item
cancellable	optional cancellation object
error	location to place an error on failure

Returns

whether the item was successfully deleted or not

secret_item_get_schema_name ()

gchar *
secret_item_get_schema_name (SecretItem *self);

Gets the name of the schema that this item was stored with. This is also available at the xdg:schema attribute.

Parameters

self

an item

Returns

the schema name.

[transfer full]

secret_item_get_attributes ()

GHashTable *
secret_item_get_attributes (SecretItem *self);

Set the attributes of this item.

The attributes are a mapping of string keys to string values. Attributes are used to search for items. Attributes are not stored or transferred securely by the secret service.

Do not modify the attributes returned by this method. Use secret_item_set_attributes() instead.

Parameters

self

an item

Returns

a new reference to the attributes, which should not be modified, and released with g_hash_table_unref().

[transfer full][element-type utf8 utf8]

secret_item_set_attributes ()

void
secret_item_set_attributes (SecretItem *self,
                            const SecretSchema *schema,
                            GHashTable *attributes,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Set the attributes of this item.

The attributes are a mapping of string keys to string values. Attributes are used to search for items. Attributes are not stored or transferred securely by the secret service.

This function returns immediately and completes asynchronously.

Parameters

self	an item
schema	the schema for the attributes.	[allow-none]
attributes	a new set of attributes.	[element-type utf8 utf8]
cancellable	optional cancellation object
callback	called when the asynchronous operation completes
user_data	data to pass to the callback

secret_item_set_attributes_finish ()

gboolean
secret_item_set_attributes_finish (SecretItem *self,
                                   GAsyncResult *result,
                                   GError **error);

Complete operation to set the attributes of this item.

Parameters

self	an item
result	asynchronous result passed to the callback
error	location to place error on failure

Returns

whether the change was successful or not

secret_item_set_attributes_sync ()

gboolean
secret_item_set_attributes_sync (SecretItem *self,
                                 const SecretSchema *schema,
                                 GHashTable *attributes,
                                 GCancellable *cancellable,
                                 GError **error);

Set the attributes of this item.

The attributes are a mapping of string keys to string values. Attributes are used to search for items. Attributes are not stored or transferred securely by the secret service.

This function may block indefinitely. Use the asynchronous version in user interface threads.

Parameters

self	an item
schema	the schema for the attributes.	[allow-none]
attributes	a new set of attributes.	[element-type utf8 utf8]
cancellable	optional cancellation object
error	location to place error on failure

Returns

whether the change was successful or not

secret_item_get_created ()

guint64
secret_item_get_created (SecretItem *self);

Get the created date and time of the item. The return value is the number of seconds since the unix epoch, January 1st 1970.

Parameters

self

an item

Returns

the created date and time

secret_item_get_label ()

gchar *
secret_item_get_label (SecretItem *self);

Get the label of this item.

Parameters

self

an item

Returns

the label, which should be freed with g_free().

[transfer full]

secret_item_set_label ()

void
secret_item_set_label (SecretItem *self,
                       const gchar *label,
                       GCancellable *cancellable,
                       GAsyncReadyCallback callback,
                       gpointer user_data);

Set the label of this item.

This function returns immediately and completes asynchronously.

Parameters

self	an item
label	a new label
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to pass to the callback

secret_item_set_label_finish ()

gboolean
secret_item_set_label_finish (SecretItem *self,
                              GAsyncResult *result,
                              GError **error);

Complete asynchronous operation to set the label of this collection.

Parameters

self	an item
result	asynchronous result passed to callback
error	location to place error on failure

Returns

whether the change was successful or not

secret_item_set_label_sync ()

gboolean
secret_item_set_label_sync (SecretItem *self,
                            const gchar *label,
                            GCancellable *cancellable,
                            GError **error);

Set the label of this item.

This function may block indefinitely. Use the asynchronous version in user interface threads.

Parameters

self	an item
label	a new label
cancellable	optional cancellation object
error	location to place error on failure

Returns

whether the change was successful or not

secret_item_get_flags ()

SecretItemFlags
secret_item_get_flags (SecretItem *self);

Get the flags representing what features of the SecretItem proxy have been initialized.

Use secret_item_load_secret() to initialize further features and change the flags.

Parameters

self

the secret item proxy

Returns

the flags for features initialized

secret_item_get_locked ()

gboolean
secret_item_get_locked (SecretItem *self);

Get whether the item is locked or not.

Depending on the secret service an item may not be able to be locked independently from the collection that it is in.

Parameters

self

an item

Returns

whether the item is locked or not

secret_item_get_modified ()

guint64
secret_item_get_modified (SecretItem *self);

Get the modified date and time of the item. The return value is the number of seconds since the unix epoch, January 1st 1970.

Parameters

self

an item

Returns

the modified date and time

secret_item_get_service ()

SecretService *
secret_item_get_service (SecretItem *self);

Get the Secret Service object that this item was created with.

Parameters

self

an item

Returns

the Secret Service object.

[transfer none]

secret_item_get_secret ()

SecretValue *
secret_item_get_secret (SecretItem *self);

Get the secret value of this item. If this item is locked or the secret has not yet been loaded then this will return NULL.

To load the secret call the secret_item_load_secret() method.

Parameters

self

an item

Returns

the secret value which should be released with secret_value_unref(), or NULL.

[transfer full][allow-none]

secret_item_load_secret ()

void
secret_item_load_secret (SecretItem *self,
                         GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data);

Load the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

This function will fail if the secret item is locked.

This function returns immediately and completes asynchronously.

Parameters

self	an item proxy
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to pass to the callback

secret_item_load_secret_finish ()

gboolean
secret_item_load_secret_finish (SecretItem *self,
                                GAsyncResult *result,
                                GError **error);

Complete asynchronous operation to load the secret value of this item.

The newly loaded secret value can be accessed by calling secret_item_get_secret().

Parameters

self	an item proxy
result	asynchronous result passed to callback
error	location to place error on failure

Returns

whether the secret item successfully loaded or not

secret_item_load_secret_sync ()

gboolean
secret_item_load_secret_sync (SecretItem *self,
                              GCancellable *cancellable,
                              GError **error);

Load the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

This function may block indefinitely. Use the asynchronous version in user interface threads.

Parameters

self	an item
cancellable	optional cancellation object
error	location to place error on failure

Returns

whether the secret item successfully loaded or not

secret_item_load_secrets ()

void
secret_item_load_secrets (GList *items,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Load the secret values for a secret item stored in the service.

The items must all have the same SecretItem::service property.

This function returns immediately and completes asynchronously.

Parameters

items	the items to retrieve secrets for.	[element-type Secret.Item]
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to pass to the callback

secret_item_load_secrets_finish ()

gboolean
secret_item_load_secrets_finish (GAsyncResult *result,
                                 GError **error);

Complete asynchronous operation to load the secret values for secret items stored in the service.

Items that are locked will not have their secrets loaded.

Parameters

result	asynchronous result passed to callback
error	location to place an error on failure

Returns

whether the operation succeeded or not

secret_item_load_secrets_sync ()

gboolean
secret_item_load_secrets_sync (GList *items,
                               GCancellable *cancellable,
                               GError **error);

Load the secret values for a secret item stored in the service.

The items must all have the same SecretItem::service property.

This method may block indefinitely and should not be used in user interface threads.

Items that are locked will not have their secrets loaded.

Parameters

items	the items to retrieve secrets for.	[element-type Secret.Item]
cancellable	optional cancellation object
error	location to place an error on failure

Returns

whether the operation succeeded or not

secret_item_set_secret ()

void
secret_item_set_secret (SecretItem *self,
                        SecretValue *value,
                        GCancellable *cancellable,
                        GAsyncReadyCallback callback,
                        gpointer user_data);

Set the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

This function returns immediately and completes asynchronously.

Parameters

self	an item
value	a new secret value
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to pass to the callback

secret_item_set_secret_finish ()

gboolean
secret_item_set_secret_finish (SecretItem *self,
                               GAsyncResult *result,
                               GError **error);

Complete asynchronous operation to set the secret value of this item.

Parameters

self	an item
result	asynchronous result passed to callback
error	location to place error on failure

Returns

whether the change was successful or not

secret_item_set_secret_sync ()

gboolean
secret_item_set_secret_sync (SecretItem *self,
                             SecretValue *value,
                             GCancellable *cancellable,
                             GError **error);

Set the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

This function may block indefinitely. Use the asynchronous version in user interface threads.

Parameters

self	an item
value	a new secret value
cancellable	optional cancellation object
error	location to place error on failure

Returns

whether the change was successful or not

secret_item_refresh ()

void
secret_item_refresh (SecretItem *self);

Refresh the properties on this item. This fires off a request to refresh, and the properties will be updated later.

Calling this method is not normally necessary, as the secret service will notify the client when properties change.

Parameters

self

the collection

Types and Values

SecretItem

typedef struct _SecretItem SecretItem;

A proxy object representing a secret item in the Secret Service.

struct SecretItemClass

struct SecretItemClass {
	GDBusProxyClass parent_class;
};

The class for SecretItem.

Members

enum SecretItemFlags

Flags which determine which parts of the SecretItem proxy are initialized.

Members

SECRET_ITEM_NONE	no flags
SECRET_ITEM_LOAD_SECRET	a secret has been (or should be) loaded for SecretItem

enum SecretItemCreateFlags

Flags for secret_item_create().

Members

SECRET_ITEM_CREATE_NONE	no flags
SECRET_ITEM_CREATE_REPLACE	replace an item with the same attributes.

Property Details

The `“attributes”` property

  “attributes”               GHashTable *

The attributes set on this item. Attributes are used to locate an item. They are not guaranteed to be stored or transferred securely.

[transfer full]

Flags: Read / Write

The `“created”` property

  “created”                  guint64

The date and time (in seconds since the UNIX epoch) that this item was created.

Flags: Read / Write

Default value: 0

The `“flags”` property

  “flags”                    SecretItemFlags

A set of flags describing which parts of the secret item have been initialized.

Flags: Read / Write / Construct Only

The `“label”` property

  “label”                    gchar *

The human readable label for the item.

Setting this property will result in the label of the item being set asynchronously. To properly track the changing of the label use the secret_item_set_label() function.

Flags: Read / Write

Default value: NULL

The `“locked”` property

  “locked”                   gboolean

Whether the item is locked or not. An item may not be independently lockable separate from other items in its collection.

To lock or unlock a item use the secret_service_lock() or secret_service_unlock() functions.

Flags: Read

Default value: TRUE

The `“modified”` property

  “modified”                 guint64

The date and time (in seconds since the UNIX epoch) that this item was last modified.

Flags: Read / Write

Default value: 0

The `“service”` property

  “service”                  SecretService *

The SecretService object that this item is associated with and uses to interact with the actual D-Bus Secret Service.

Flags: Read / Write / Construct Only