Keyrings: gnome-keyring Reference Manual

Keyrings

Keyrings — Listing and managing keyrings

Functions

void	(*GnomeKeyringOperationGetKeyringInfoCallback) ()
gpointer	gnome_keyring_set_default_keyring ()
GnomeKeyringResult	gnome_keyring_set_default_keyring_sync ()
gpointer	gnome_keyring_get_default_keyring ()
GnomeKeyringResult	gnome_keyring_get_default_keyring_sync ()
gpointer	gnome_keyring_list_keyring_names ()
GnomeKeyringResult	gnome_keyring_list_keyring_names_sync ()
gpointer	gnome_keyring_lock_all ()
GnomeKeyringResult	gnome_keyring_lock_all_sync ()
gpointer	gnome_keyring_create ()
GnomeKeyringResult	gnome_keyring_create_sync ()
gpointer	gnome_keyring_unlock ()
GnomeKeyringResult	gnome_keyring_unlock_sync ()
gpointer	gnome_keyring_lock ()
GnomeKeyringResult	gnome_keyring_lock_sync ()
gpointer	gnome_keyring_delete ()
GnomeKeyringResult	gnome_keyring_delete_sync ()
gpointer	gnome_keyring_get_info ()
GnomeKeyringResult	gnome_keyring_get_info_sync ()
gpointer	gnome_keyring_set_info ()
GnomeKeyringResult	gnome_keyring_set_info_sync ()
gpointer	gnome_keyring_change_password ()
GnomeKeyringResult	gnome_keyring_change_password_sync ()
gpointer	gnome_keyring_list_item_ids ()
GnomeKeyringResult	gnome_keyring_list_item_ids_sync ()

Description

All of these APIs are deprecated. Use libsecret instead.

gnome-keyring-daemon manages multiple keyrings. Each keyring can

store one or more items containing secrets.

One of the keyrings is the default keyring, which can in many cases be used by specifying NULL for a keyring name.

Each keyring can be in a locked or unlocked state. A password must be specified, either by the user or the calling application, to unlock the keyring.

Functions

GnomeKeyringOperationGetKeyringInfoCallback ()

void
(*GnomeKeyringOperationGetKeyringInfoCallback)
                               (GnomeKeyringResult result,
                                GnomeKeyringInfo *info,
                                gpointer user_data);

GnomeKeyringOperationGetKeyringInfoCallback is deprecated and should not be used in newly-written code.

gnome_keyring_set_default_keyring ()

gpointer
gnome_keyring_set_default_keyring (const char *keyring,
                                   GnomeKeyringOperationDoneCallback callback,
                                   gpointer data,
                                   GDestroyNotify destroy_data);

gnome_keyring_set_default_keyring is deprecated and should not be used in newly-written code.

Use secret_service_set_alias() instead.

Change the default keyring.

For a synchronous version of this function see gnome_keyring_set_default_keyring_sync().

[skip]

Parameters

keyring	The keyring to make default
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_set_default_keyring_sync ()

GnomeKeyringResult
gnome_keyring_set_default_keyring_sync
                               (const char *keyring);

gnome_keyring_set_default_keyring_sync is deprecated and should not be used in newly-written code.

Use secret_service_set_alias_sync() instead.

Change the default keyring.

For an asynchronous version of this function see gnome_keyring_set_default_keyring().

Parameters

keyring

The keyring to make default

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

gnome_keyring_get_default_keyring ()

gpointer
gnome_keyring_get_default_keyring (GnomeKeyringOperationGetStringCallback callback,
                                   gpointer data,
                                   GDestroyNotify destroy_data);

gnome_keyring_get_default_keyring is deprecated and should not be used in newly-written code.

Use secret_collection_for_alias() instead.

Get the default keyring name, which will be passed to the callback . If no default keyring exists, then NULL will be passed to the callback . The string will be freed after callback returns.

For a synchronous version of this function see gnome_keyring_get_default_keyring_sync().

[skip]

Parameters

callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_get_default_keyring_sync ()

GnomeKeyringResult
gnome_keyring_get_default_keyring_sync
                               (char **keyring);

gnome_keyring_get_default_keyring_sync is deprecated and should not be used in newly-written code.

Use secret_collection_for_alias_sync() instead.

Get the default keyring name.

The string returned in keyring must be freed with g_free().

For an asynchronous version of this function see gnome_keyring_get_default_keyring().

Parameters

keyring

Location for the default keyring name to be returned.

[out]

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

gnome_keyring_list_keyring_names ()

gpointer
gnome_keyring_list_keyring_names (GnomeKeyringOperationGetListCallback callback,
                                  gpointer data,
                                  GDestroyNotify destroy_data);

gnome_keyring_list_keyring_names is deprecated and should not be used in newly-written code.

Use secret_service_get_collections() instead.

Get a list of keyring names.

A GList of null terminated strings will be passed to the callback . If no keyrings exist then an empty list will be passed to the callback . The list is freed after callback returns.

For a synchronous version of this function see gnome_keyring_list_keyring_names_sync().

[skip]

Parameters

callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_list_keyring_names_sync ()

GnomeKeyringResult
gnome_keyring_list_keyring_names_sync (GList **keyrings);

gnome_keyring_list_keyring_names_sync is deprecated and should not be used in newly-written code.

Use secret_service_get_collections() instead.

Get a list of keyring names.

The list returned in in keyrings must be freed using gnome_keyring_string_list_free().

For an asynchronous version of this function see gnome_keyring_list_keyring_names().

Parameters

keyrings

Location for a GList of keyring names to be returned.

[out][element-type utf8]

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

gnome_keyring_lock_all ()

gpointer
gnome_keyring_lock_all (GnomeKeyringOperationDoneCallback callback,
                        gpointer data,
                        GDestroyNotify destroy_data);

gnome_keyring_lock_all is deprecated and should not be used in newly-written code.

Use libsecret instead.

Lock all the keyrings, so that their contents may not be accessed without first unlocking them with a password.

For a synchronous version of this function see gnome_keyring_lock_all_sync().

[skip]

Parameters

callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_lock_all_sync ()

GnomeKeyringResult
gnome_keyring_lock_all_sync (void);

gnome_keyring_lock_all_sync is deprecated and should not be used in newly-written code.

Use libsecret instead.

Lock all the keyrings, so that their contents may not eb accessed without first unlocking them with a password.

For an asynchronous version of this function see gnome_keyring_lock_all().

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

gnome_keyring_create ()

gpointer
gnome_keyring_create (const char *keyring_name,
                      const char *password,
                      GnomeKeyringOperationDoneCallback callback,
                      gpointer data,
                      GDestroyNotify destroy_data);

gnome_keyring_create is deprecated and should not be used in newly-written code.

Use secret_collection_create() instead.

Create a new keyring with the specified name. In most cases NULL will be passed as the password , which will prompt the user to enter a password of their choice.

For a synchronous version of this function see gnome_keyring_create_sync().

[skip]

Parameters

keyring_name	The new keyring name. Must not be `NULL`.
password	The password for the new keyring. If `NULL` user will be prompted.	[allow-none]
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_create_sync ()

GnomeKeyringResult
gnome_keyring_create_sync (const char *keyring_name,
                           const char *password);

gnome_keyring_create_sync is deprecated and should not be used in newly-written code.

Use secret_collection_create_sync() instead.

Create a new keyring with the specified name. In most cases NULL will be passed in as the password , which will prompt the user to enter a password of their choice.

For an asynchronous version of this function see gnome_keyring_create().

Parameters

keyring_name	The new keyring name. Must not be `NULL`
password	The password for the new keyring. If `NULL` user will be prompted.	[allow-none]

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

gnome_keyring_unlock ()

gpointer
gnome_keyring_unlock (const char *keyring,
                      const char *password,
                      GnomeKeyringOperationDoneCallback callback,
                      gpointer data,
                      GDestroyNotify destroy_data);

gnome_keyring_unlock is deprecated and should not be used in newly-written code.

Use secret_service_unlock() instead.

Unlock a keyring , so that its contents may be accessed. In most cases NULL will be passed as the password , which will prompt the user to enter the correct password.

Most keyring operations involving items require that you first unlock the keyring. One exception is gnome_keyring_find_items() and related functions.

For a synchronous version of this function see gnome_keyring_unlock_sync().

[skip]

Parameters

keyring	The name of the keyring to unlock, or `NULL` for the default keyring.	[allow-none]
password	The password to unlock the keyring with, or `NULL` to prompt the user.	[allow-none]
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_unlock_sync ()

GnomeKeyringResult
gnome_keyring_unlock_sync (const char *keyring,
                           const char *password);

gnome_keyring_unlock_sync is deprecated and should not be used in newly-written code.

Use secret_service_unlock_sync() instead.

Unlock a keyring , so that its contents may be accessed. In most cases NULL will be passed in as the password , which will prompt the user to enter the correct password.

Most keyring opretaions involving items require that yo ufirst unlock the keyring. One exception is gnome_keyring_find_items_sync() and related functions.

For an asynchronous version of this function see gnome_keyring_unlock().

Parameters

keyring	The name of the keyring to unlock, or `NULL` for the default keyring.	[allow-none]
password	The password to unlock the keyring with, or `NULL` to prompt the user.	[allow-none]

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

gnome_keyring_lock ()

gpointer
gnome_keyring_lock (const char *keyring,
                    GnomeKeyringOperationDoneCallback callback,
                    gpointer data,
                    GDestroyNotify destroy_data);

gnome_keyring_lock is deprecated and should not be used in newly-written code.

Use secret_service_lock() instead.

Lock a keyring , so that its contents may not be accessed without first supplying a password.

Most keyring operations involving items require that you first unlock the keyring. One exception is gnome_keyring_find_items() and related functions.

For a synchronous version of this function see gnome_keyring_lock_sync().

[skip]

Parameters

keyring	The name of the keyring to lock, or `NULL` for the default keyring.	[allow-none]
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_lock_sync ()

GnomeKeyringResult
gnome_keyring_lock_sync (const char *keyring);

gnome_keyring_lock_sync is deprecated and should not be used in newly-written code.

Use secret_service_lock_sync() instead.

Lock a keyring , so that its contents may not be accessed without first supplying a password.

Most keyring opretaions involving items require that you first unlock the keyring. One exception is gnome_keyring_find_items_sync() and related functions.

For an asynchronous version of this function see gnome_keyring_lock().

Parameters

keyring

The name of the keyring to lock, or NULL for the default keyring.

[allow-none]

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

gnome_keyring_delete ()

gpointer
gnome_keyring_delete (const char *keyring,
                      GnomeKeyringOperationDoneCallback callback,
                      gpointer data,
                      GDestroyNotify destroy_data);

gnome_keyring_delete is deprecated and should not be used in newly-written code.

Use secret_collection_delete() instead.

Delete keyring . Once a keyring is deleted there is no mechanism for recovery of its contents.

For a synchronous version of this function see gnome_keyring_delete_sync().

[skip]

Parameters

keyring	The name of the keyring to delete. Cannot be `NULL`.
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_delete_sync ()

GnomeKeyringResult
gnome_keyring_delete_sync (const char *keyring);

gnome_keyring_delete_sync is deprecated and should not be used in newly-written code.

Use secret_collection_delete_sync() instead.

Delete keyring . Once a keyring is deleted there is no mechanism for recovery of its contents.

For an asynchronous version of this function see gnome_keyring_delete().

Parameters

keyring

The name of the keyring to delete. Cannot be NULL

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

gnome_keyring_get_info ()

gpointer
gnome_keyring_get_info (const char *keyring,
                        GnomeKeyringOperationGetKeyringInfoCallback callback,
                        gpointer data,
                        GDestroyNotify destroy_data);

gnome_keyring_get_info is deprecated and should not be used in newly-written code.

Use SecretCollection objects instead.

Get information about the keyring . The resulting GnomeKeyringInfo structure will be passed to callback . The structure is freed after callback returns.

For a synchronous version of this function see gnome_keyring_get_info_sync().

[skip]

Parameters

keyring	The name of the keyring, or `NULL` for the default keyring.	[allow-none]
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_get_info_sync ()

GnomeKeyringResult
gnome_keyring_get_info_sync (const char *keyring,
                             GnomeKeyringInfo **info);

gnome_keyring_get_info_sync is deprecated and should not be used in newly-written code.

Use SecretCollection objects instead.

Get information about keyring .

The GnomeKeyringInfo structure returned in info must be freed with gnome_keyring_info_free().

For an asynchronous version of this function see gnome_keyring_get_info().

Parameters

keyring	The name of the keyring, or `NULL` for the default keyring.	[allow-none]
info	Location for the information about the keyring to be returned.	[out]

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

gnome_keyring_set_info ()

gpointer
gnome_keyring_set_info (const char *keyring,
                        GnomeKeyringInfo *info,
                        GnomeKeyringOperationDoneCallback callback,
                        gpointer data,
                        GDestroyNotify destroy_data);

gnome_keyring_set_info is deprecated and should not be used in newly-written code.

Use SecretCollection objects instead.

Set flags and info for the keyring . The only fields in info that are used are lock_on_idle and lock_timeout.

For a synchronous version of this function see gnome_keyring_set_info_sync().

[skip]

Parameters

keyring	The name of the keyring, or `NULL` for the default keyring.	[allow-none]
info	A structure containing flags and info for the keyring.
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_set_info_sync ()

GnomeKeyringResult
gnome_keyring_set_info_sync (const char *keyring,
                             GnomeKeyringInfo *info);

gnome_keyring_set_info_sync is deprecated and should not be used in newly-written code.

Use SecretCollection objects instead.

Set flags and info for keyring . The only fields in info that are used are lock_on_idle and lock_timeout.

For an asynchronous version of this function see gnome_keyring_set_info().

Parameters

keyring	The name of the keyring, or `NULL` for the default keyring.	[allow-none]
info	A structure containing flags and info for the keyring.

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

gnome_keyring_change_password ()

gpointer
gnome_keyring_change_password (const char *keyring,
                               const char *original,
                               const char *password,
                               GnomeKeyringOperationDoneCallback callback,
                               gpointer data,
                               GDestroyNotify destroy_data);

gnome_keyring_change_password is deprecated and should not be used in newly-written code.

Not used with libsecret.

Change the password for a keyring . In most cases you would specify NULL for both the original and password arguments and allow the user to type the correct passwords.

For a synchronous version of this function see gnome_keyring_change_password_sync().

[skip]

Parameters

keyring	The name of the keyring to change the password for. Cannot be `NULL`.
original	The old keyring password, or `NULL` to prompt the user for it.	[allow-none]
password	The new keyring password, or `NULL` to prompt the user for it.	[allow-none]
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_change_password_sync ()

GnomeKeyringResult
gnome_keyring_change_password_sync (const char *keyring,
                                    const char *original,
                                    const char *password);

gnome_keyring_change_password_sync is deprecated and should not be used in newly-written code.

Not used with libsecret.

Change the password for keyring . In most cases you would specify NULL for both the original and password arguments and allow the user to type the correct passwords.

For an asynchronous version of this function see gnome_keyring_change_password().

Parameters

keyring	The name of the keyring to change the password for. Cannot be `NULL`
original	The old keyring password, or `NULL` to prompt the user for it.	[allow-none]
password	The new keyring password, or `NULL` to prompt the user for it.	[allow-none]

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

gnome_keyring_list_item_ids ()

gpointer
gnome_keyring_list_item_ids (const char *keyring,
                             GnomeKeyringOperationGetListCallback callback,
                             gpointer data,
                             GDestroyNotify destroy_data);

gnome_keyring_list_item_ids is deprecated and should not be used in newly-written code.

Use secret_collection_get_items() instead.

Get a list of all the ids for items in keyring . These are passed in a GList to the callback . Use GPOINTER_TO_UINT() on the list to access the integer ids. The list is freed after callback returns.

All items that are not flagged as GNOME_KEYRING_ITEM_APPLICATION_SECRET are included in the list. This includes items that the calling application may not (yet) have access to.

For a synchronous version of this function see gnome_keyring_list_item_ids_sync().

[skip]

Parameters

keyring	The name of the keyring, or `NULL` for the default keyring.	[allow-none]
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

gnome_keyring_list_item_ids_sync ()

GnomeKeyringResult
gnome_keyring_list_item_ids_sync (const char *keyring,
                                  GList **ids);

gnome_keyring_list_item_ids_sync is deprecated and should not be used in newly-written code.

Use secret_collection_get_items() instead.

Get a list of all the ids for items in keyring .

Use GPOINTER_TO_UINT() on the list to access the integer ids. The list should be freed with g_list_free().

For an asynchronous version of this function see gnome_keyring_list_item_ids().

Parameters

keyring	The name of the keyring, or `NULL` for the default keyring.	[allow-none]
ids	The location to store a `GList` of item ids (ie: unsigned integers).	[out][element-type guint]

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.