Password storage: Libsecret Library Reference Manual

Password storage

Password storage — Simple password storage and lookup

Functions

void	secret_password_store ()
void	secret_password_storev ()
gboolean	secret_password_store_finish ()
gboolean	secret_password_store_sync ()
gboolean	secret_password_storev_sync ()
void	secret_password_lookup ()
void	secret_password_lookupv ()
gchar *	secret_password_lookup_finish ()
gchar *	secret_password_lookup_nonpageable_finish ()
gchar *	secret_password_lookup_sync ()
gchar *	secret_password_lookup_nonpageable_sync ()
gchar *	secret_password_lookupv_sync ()
gchar *	secret_password_lookupv_nonpageable_sync ()
void	secret_password_clear ()
void	secret_password_clearv ()
gboolean	secret_password_clear_finish ()
gboolean	secret_password_clear_sync ()
gboolean	secret_password_clearv_sync ()
void	secret_password_wipe ()
void	secret_password_free ()

Types and Values

#define	SECRET_COLLECTION_DEFAULT
#define	SECRET_COLLECTION_SESSION

Includes

#include <libsecret/secret.h>

Description

This is a simple API for storing passwords and retrieving passwords in the Secret Service.

Each password is associated with a set of attributes. Attribute values can be either strings, integers or booleans.

The names and types of allowed attributes for a given password are defined with a schema. Certain schemas are predefined. Additional schemas can be defined via the SecretSchema structure.

Each of the functions accept a variable list of attributes names and their values. Include a NULL to terminate the list of attributes.

Functions

secret_password_store ()

void
secret_password_store (const SecretSchema *schema,
                       const gchar *collection,
                       const gchar *label,
                       const gchar *password,
                       GCancellable *cancellable,
                       GAsyncReadyCallback callback,
                       gpointer user_data,
                       ...);

Store a password in the secret service.

The variable argument list should contain pairs of a) The attribute name as a null-terminated string, followed by b) attribute value, either a character string, an int number, or a gboolean value, as defined in the schema . The list of attribtues should be terminated with a NULL.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If collection is NULL, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

This method will return immediately and complete asynchronously.

[skip]

Parameters

schema	the schema for attributes
collection	a collection alias, or D-Bus object path of the collection where to store the secret.	[allow-none]
label	label for the secret
password	the null-terminated password to store
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to be passed to the callback
...	the attribute keys and values, terminated with `NULL`

secret_password_storev ()

void
secret_password_storev (const SecretSchema *schema,
                        GHashTable *attributes,
                        const gchar *collection,
                        const gchar *label,
                        const gchar *password,
                        GCancellable *cancellable,
                        GAsyncReadyCallback callback,
                        gpointer user_data);

Store a password in the secret service.

The attributes should be a set of key and value string pairs.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If collection is NULL, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

This method will return immediately and complete asynchronously.

[rename-to secret_password_store]

Parameters

schema	the schema for attributes
attributes	the attribute keys and values.	[element-type utf8 utf8]
collection	a collection alias, or D-Bus object path of the collection where to store the secret.	[allow-none]
label	label for the secret
password	the null-terminated password to store
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to be passed to the callback

secret_password_store_finish ()

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

Finish asynchronous operation to store a password in the secret service.

Parameters

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

Returns

whether the storage was successful or not

secret_password_store_sync ()

gboolean
secret_password_store_sync (const SecretSchema *schema,
                            const gchar *collection,
                            const gchar *label,
                            const gchar *password,
                            GCancellable *cancellable,
                            GError **error,
                            ...);

Store a password in the secret service.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If collection is NULL, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

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

Parameters

schema	the schema for attributes
collection	a collection alias, or D-Bus object path of the collection where to store the secret.	[allow-none]
label	label for the secret
password	the null-terminated password to store
cancellable	optional cancellation object
error	location to place an error on failure
...	the attribute keys and values, terminated with `NULL`

Returns

whether the storage was successful or not

secret_password_storev_sync ()

gboolean
secret_password_storev_sync (const SecretSchema *schema,
                             GHashTable *attributes,
                             const gchar *collection,
                             const gchar *label,
                             const gchar *password,
                             GCancellable *cancellable,
                             GError **error);

Store a password in the secret service.

The attributes should be a set of key and value string pairs.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If collection is NULL, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

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

[rename-to secret_password_store_sync]

Parameters

schema	the schema for attributes
attributes	the attribute keys and values.	[element-type utf8 utf8]
collection	a collection alias, or D-Bus object path of the collection where to store the secret.	[allow-none]
label	label for the secret
password	the null-terminated password to store
cancellable	optional cancellation object
error	location to place an error on failure

Returns

whether the storage was successful or not

secret_password_lookup ()

void
secret_password_lookup (const SecretSchema *schema,
                        GCancellable *cancellable,
                        GAsyncReadyCallback callback,
                        gpointer user_data,
                        ...);

Lookup a password in the secret service.

The variable argument list should contain pairs of a) The attribute name as a null-terminated string, followed by b) attribute value, either a character string, an int number, or a gboolean value, as defined in the password schema . The list of attribtues should be terminated with a NULL.

If no secret is found then NULL is returned.

This method will return immediately and complete asynchronously.

[skip]

Parameters

schema	the schema for the attributes
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to be passed to the callback
...	the attribute keys and values, terminated with `NULL`

secret_password_lookupv ()

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

Lookup a password in the secret service.

The attributes should be a set of key and value string pairs.

If no secret is found then NULL is returned.

This method will return immediately and complete asynchronously.

[rename-to secret_password_lookup]

Parameters

schema	the schema for attributes
attributes	the attribute keys and values.	[element-type utf8 utf8]
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to be passed to the callback

secret_password_lookup_finish ()

gchar *
secret_password_lookup_finish (GAsyncResult *result,
                               GError **error);

Finish an asynchronous operation to lookup a password in the secret service.

Parameters

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

Returns

a new password string which should be freed with secret_password_free() or may be freed with g_free() when done.

[transfer full]

secret_password_lookup_nonpageable_finish ()

gchar *
secret_password_lookup_nonpageable_finish
                               (GAsyncResult *result,
                                GError **error);

Finish an asynchronous operation to lookup a password in the secret service.

[skip]

Parameters

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

Returns

a new password string stored in nonpageable memory which must be freed with secret_password_free() when done.

[transfer full]

secret_password_lookup_sync ()

gchar *
secret_password_lookup_sync (const SecretSchema *schema,
                             GCancellable *cancellable,
                             GError **error,
                             ...);

Lookup a password in the secret service.

The variable argument list should contain pairs of a) The attribute name as a null-terminated string, followed by b) attribute value, either a character string, an int number, or a gboolean value, as defined in the password schema . The list of attributes should be terminated with a NULL.

If no secret is found then NULL is returned.

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

[skip]

Parameters

schema	the schema for the attributes
cancellable	optional cancellation object
error	location to place an error on failure
...	the attribute keys and values, terminated with `NULL`

Returns

a new password string which should be freed with secret_password_free() or may be freed with g_free() when done.

[transfer full]

secret_password_lookup_nonpageable_sync ()

gchar *
secret_password_lookup_nonpageable_sync
                               (const SecretSchema *schema,
                                GCancellable *cancellable,
                                GError **error,
                                ...);

Lookup a password in the secret service.

The variable argument list should contain pairs of a) The attribute name as a null-terminated string, followed by b) attribute value, either a character string, an int number, or a gboolean value, as defined in the password schema . The list of attribtues should be terminated with a NULL.

If no secret is found then NULL is returned.

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

[skip]

Parameters

schema	the schema for the attributes
cancellable	optional cancellation object
error	location to place an error on failure
...	the attribute keys and values, terminated with `NULL`

Returns

a new password string stored in nonpageable memory which must be freed with secret_password_free() when done.

[transfer full]

secret_password_lookupv_sync ()

gchar *
secret_password_lookupv_sync (const SecretSchema *schema,
                              GHashTable *attributes,
                              GCancellable *cancellable,
                              GError **error);

Lookup a password in the secret service.

The attributes should be a set of key and value string pairs.

If no secret is found then NULL is returned.

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

[rename-to secret_password_lookup_sync]

Parameters

schema	the schema for attributes
attributes	the attribute keys and values.	[element-type utf8 utf8]
cancellable	optional cancellation object
error	location to place an error on failure

Returns

a new password string which should be freed with secret_password_free() or may be freed with g_free() when done.

[transfer full]

secret_password_lookupv_nonpageable_sync ()

gchar *
secret_password_lookupv_nonpageable_sync
                               (const SecretSchema *schema,
                                GHashTable *attributes,
                                GCancellable *cancellable,
                                GError **error);

Lookup a password in the secret service.

The attributes should be a set of key and value string pairs.

If no secret is found then NULL is returned.

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

[skip]

Parameters

schema	the schema for attributes
attributes	the attribute keys and values.	[element-type utf8 utf8]
cancellable	optional cancellation object
error	location to place an error on failure

Returns

a new password string stored in non pageable memory which should be freed with secret_password_free() when done.

[transfer full]

secret_password_clear ()

void
secret_password_clear (const SecretSchema *schema,
                       GCancellable *cancellable,
                       GAsyncReadyCallback callback,
                       gpointer user_data,
                       ...);

Clear unlocked matching passwords from the secret service.

The variable argument list should contain pairs of a) The attribute name as a null-terminated string, followed by b) attribute value, either a character string, an int number, or a gboolean value, as defined in the password schema . The list of attribtues should be terminated with a NULL.

All unlocked items that match the attributes will be deleted.

This method will return immediately and complete asynchronously.

Parameters

schema	the schema for the attributes
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to be passed to the callback
...	the attribute keys and values, terminated with `NULL`

secret_password_clearv ()

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

Remove unlocked matching passwords from the secret service.

The attributes should be a set of key and value string pairs.

All unlocked items that match the attributes will be deleted.

This method will return immediately and complete asynchronously.

[rename-to secret_password_clear]

Parameters

schema	the schema for the attributes
attributes	the attribute keys and values.	[element-type utf8 utf8]
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to be passed to the callback

secret_password_clear_finish ()

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

Finish an asynchronous operation to remove passwords from the secret service.

Parameters

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

Returns

whether any passwords were removed

secret_password_clear_sync ()

gboolean
secret_password_clear_sync (const SecretSchema *schema,
                            GCancellable *cancellable,
                            GError **error,
                            ...);

Remove unlocked matching passwords from the secret service.

The variable argument list should contain pairs of a) The attribute name as a null-terminated string, followed by b) attribute value, either a character string, an int number, or a gboolean value, as defined in the password schema . The list of attribtues should be terminated with a NULL.

All unlocked items that match the attributes will be deleted.

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

Parameters

schema	the schema for the attributes
cancellable	optional cancellation object
error	location to place an error on failure
...	the attribute keys and values, terminated with `NULL`

Returns

whether the any passwords were removed

secret_password_clearv_sync ()

gboolean
secret_password_clearv_sync (const SecretSchema *schema,
                             GHashTable *attributes,
                             GCancellable *cancellable,
                             GError **error);

Remove unlocked matching passwords from the secret service.

The attributes should be a set of key and value string pairs.

All unlocked items that match the attributes will be deleted.

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

[rename-to secret_password_clear_sync]

Parameters

schema	the schema for the attributes
attributes	the attribute keys and values.	[element-type utf8 utf8]
cancellable	optional cancellation object
error	location to place an error on failure

Returns

whether any passwords were removed

secret_password_wipe ()

void
secret_password_wipe (gchar *password);

Clear the memory used by a password.

Parameters

password

password to clear.

[allow-none]

secret_password_free ()

void
secret_password_free (gchar *password);

Clear the memory used by a password, and then free it.

This function must be used to free nonpageable memory returned by secret_password_lookup_nonpageable_finish(), secret_password_lookup_nonpageable_sync() or secret_password_lookupv_nonpageable_sync().

[skip]

Parameters

password

password to free.

[allow-none]

Types and Values

SECRET_COLLECTION_DEFAULT

#define SECRET_COLLECTION_DEFAULT "default"

An alias to the default collection. This can be passed to secret_password_store() secret_collection_for_alias().

SECRET_COLLECTION_SESSION

#define SECRET_COLLECTION_SESSION "session"

An alias to the session collection, which will be cleared when the user ends the session. This can be passed to secret_password_store(), secret_collection_for_alias() or similar functions.