GNOME.org

Keyrings

Keyrings — Listing and managing keyrings

Synopsis

void                (*GnomeKeyringOperationGetKeyringInfoCallback)
                                                        (GnomeKeyringResult result,
                                                         GnomeKeyringInfo *info,
                                                         gpointer user_data);
gpointer            gnome_keyring_set_default_keyring   (const char *keyring,
                                                         GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_set_default_keyring_sync
                                                        (const char *keyring);
gpointer            gnome_keyring_get_default_keyring   (GnomeKeyringOperationGetStringCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_get_default_keyring_sync
                                                        (char **keyring);
gpointer            gnome_keyring_list_keyring_names    (GnomeKeyringOperationGetListCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_list_keyring_names_sync
                                                        (GList **keyrings);
gpointer            gnome_keyring_lock_all              (GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_lock_all_sync         (void);
gpointer            gnome_keyring_create                (const char *keyring_name,
                                                         const char *password,
                                                         GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_create_sync           (const char *keyring_name,
                                                         const char *password);
gpointer            gnome_keyring_unlock                (const char *keyring,
                                                         const char *password,
                                                         GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_unlock_sync           (const char *keyring,
                                                         const char *password);
gpointer            gnome_keyring_lock                  (const char *keyring,
                                                         GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_lock_sync             (const char *keyring);
gpointer            gnome_keyring_delete                (const char *keyring,
                                                         GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_delete_sync           (const char *keyring);
gpointer            gnome_keyring_get_info              (const char *keyring,
                                                         GnomeKeyringOperationGetKeyringInfoCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_get_info_sync         (const char *keyring,
                                                         GnomeKeyringInfo **info);
gpointer            gnome_keyring_set_info              (const char *keyring,
                                                         GnomeKeyringInfo *info,
                                                         GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_set_info_sync         (const char *keyring,
                                                         GnomeKeyringInfo *info);
gpointer            gnome_keyring_change_password       (const char *keyring,
                                                         const char *original,
                                                         const char *password,
                                                         GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_change_password_sync  (const char *keyring,
                                                         const char *original,
                                                         const char *password);
gpointer            gnome_keyring_list_item_ids         (const char *keyring,
                                                         GnomeKeyringOperationGetListCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_list_item_ids_sync    (const char *keyring,
                                                         GList **ids);

Description

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.

Details

GnomeKeyringOperationGetKeyringInfoCallback ()

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

gnome_keyring_set_default_keyring ()

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

Change the default keyring.

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

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);

Change the default keyring.

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

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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);

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().

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.
Generated by GTK-Doc V1.18