Keyring Items: gnome-keyring Reference Manual

Keyring Items

Keyring Items — Keyring items each hold a secret and a number of attributes.

Functions

void	(*GnomeKeyringOperationGetItemInfoCallback) ()
void	(*GnomeKeyringOperationGetAttributesCallback) ()
gpointer	gnome_keyring_item_create ()
GnomeKeyringResult	gnome_keyring_item_create_sync ()
gpointer	gnome_keyring_item_delete ()
GnomeKeyringResult	gnome_keyring_item_delete_sync ()
gpointer	gnome_keyring_item_get_info ()
gpointer	gnome_keyring_item_get_info_full ()
GnomeKeyringResult	gnome_keyring_item_get_info_full_sync ()
GnomeKeyringResult	gnome_keyring_item_get_info_sync ()
gpointer	gnome_keyring_item_set_info ()
GnomeKeyringResult	gnome_keyring_item_set_info_sync ()
gpointer	gnome_keyring_item_get_attributes ()
GnomeKeyringResult	gnome_keyring_item_get_attributes_sync ()
gpointer	gnome_keyring_item_set_attributes ()
GnomeKeyringResult	gnome_keyring_item_set_attributes_sync ()
gpointer	gnome_keyring_item_get_acl ()
GnomeKeyringResult	gnome_keyring_item_get_acl_sync ()
gpointer	gnome_keyring_item_set_acl ()
GnomeKeyringResult	gnome_keyring_item_set_acl_sync ()
gpointer	gnome_keyring_item_grant_access_rights ()
GnomeKeyringResult	gnome_keyring_item_grant_access_rights_sync ()

Types and Values

enum	GnomeKeyringItemInfoFlags
#define	GNOME_KEYRING_ITEM_APPLICATION_SECRET
#define	GNOME_KEYRING_ITEM_INFO_ALL
#define	GNOME_KEYRING_ITEM_NO_TYPE
#define	GNOME_KEYRING_ITEM_TYPE_MASK

Description

All of these APIs are deprecated. Use libsecret instead.

A keyring contains multiple items. Each item has a secret, attributes and access information associated with it.

An item is identified by an unsigned integer unique to the keyring in which it exists. An item's name is for displaying to the user. Each item has a single secret, which is a null-terminated string. This secret is stored in non-pageable memory, and encrypted on disk. All of this information is exposed via GnomeKeyringItemInfo pointers.

Attributes allow various other pieces of information to be associated with an item. These can also be used to search for relevant items. Attributes are accessed with GnomeKeyringAttribute structures and built into lists using GnomeKeyringAttributeList.

Attributes are not stored in a secret or encrypted manner by gnome-keyring. Do not store sensitive information in attributes.

Functions

GnomeKeyringOperationGetItemInfoCallback ()

void
(*GnomeKeyringOperationGetItemInfoCallback)
                               (GnomeKeyringResult result,
                                GnomeKeyringItemInfo *info,
                                gpointer user_data);

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

GnomeKeyringOperationGetAttributesCallback ()

void
(*GnomeKeyringOperationGetAttributesCallback)
                               (GnomeKeyringResult result,
                                GnomeKeyringAttributeList *attributes,
                                gpointer user_data);

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

gnome_keyring_item_create ()

gpointer
gnome_keyring_item_create (const char *keyring,
                           GnomeKeyringItemType type,
                           const char *display_name,
                           GnomeKeyringAttributeList *attributes,
                           const char *secret,
                           gboolean update_if_exists,
                           GnomeKeyringOperationGetIntCallback callback,
                           gpointer data,
                           GDestroyNotify destroy_data);

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

Use secret_password_store() or secret_item_create() instead.

Create a new item in a keyring.

The secret must be a null terminated string. It should be allocated using secure memory whenever possible. See gnome_keyring_memory_strdup()

The user may have been prompted to unlock necessary keyrings. If NULL is specified as the keyring and no default keyring exists, the user will be prompted to create a new keyring.

When update_if_exists is set to TRUE, the user may be prompted for access to the previously existing item.

Whether a new item is created or not, id of the item will be passed to the callback .

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

[skip]

Parameters

keyring	The name of the keyring in which to create the item, or `NULL` for the default keyring.	[allow-none]
type	The item type.
display_name	The name of the item. This will be displayed to the user where necessary.
attributes	A (possibly empty) list of attributes to store with the item.
secret	The password or secret of the item.
update_if_exists	If true, then another item matching the type, and attributes will be updated instead of creating a new item.
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_item_create_sync ()

GnomeKeyringResult
gnome_keyring_item_create_sync (const char *keyring,
                                GnomeKeyringItemType type,
                                const char *display_name,
                                GnomeKeyringAttributeList *attributes,
                                const char *secret,
                                gboolean update_if_exists,
                                guint32 *item_id);

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

Use secret_password_store_sync() or secret_item_create_sync() instead.

Create a new item in a keyring.

The secret must be a null terminated string. It should be allocated using secure memory whenever possible. See gnome_keyring_memory_strdup()

The user may have been prompted to unlock necessary keyrings. If NULL is specified as the keyring and no default keyring exists, the user will be prompted to create a new keyring.

When update_if_exists is set to TRUE, the user may be prompted for access to the previously existing item.

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

Parameters

keyring	The name of the keyring in which to create the item, or `NULL` for the default keyring.	[allow-none]
type	The item type.
display_name	The name of the item. This will be displayed to the user where necessary.
attributes	A (possibly empty) list of attributes to store with the item.
secret	The password or secret of the item.
update_if_exists	If true, then another item matching the type, and attributes will be updated instead of creating a new item.
item_id	return location for the id of the created/updated keyring item.	[out]

Returns

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

gnome_keyring_item_delete ()

gpointer
gnome_keyring_item_delete (const char *keyring,
                           guint32 id,
                           GnomeKeyringOperationDoneCallback callback,
                           gpointer data,
                           GDestroyNotify destroy_data);

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

Use secret_password_clear() or secret_item_delete() instead.

Delete an item in a keyring.

The user may be prompted if the calling application doesn't have necessary access to delete the item.

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

[skip]

Parameters

keyring	The name of the keyring from which to delete the item, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
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_item_delete_sync ()

GnomeKeyringResult
gnome_keyring_item_delete_sync (const char *keyring,
                                guint32 id);

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

Use secret_password_clear_sync() or secret_item_delete_sync() instead.

Delete an item in a keyring.

The user may be prompted if the calling application doesn't have necessary access to delete the item.

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

Parameters

keyring	The name of the keyring from which to delete the item, or `NULL` for the default keyring.	[allow-none]
id	The id of the item

Returns

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

gnome_keyring_item_get_info ()

gpointer
gnome_keyring_item_get_info (const char *keyring,
                             guint32 id,
                             GnomeKeyringOperationGetItemInfoCallback callback,
                             gpointer data,
                             GDestroyNotify destroy_data);

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

Use SecretItem objects instead.

Get information about an item and its secret.

The user may be prompted if the calling application doesn't have necessary access to read the item with its secret.

A GnomeKeyringItemInfo structure will be passed to the callback . This structure will be freed after callback returns.

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

[skip]

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
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_item_get_info_full ()

gpointer
gnome_keyring_item_get_info_full (const char *keyring,
                                  guint32 id,
                                  guint32 flags,
                                  GnomeKeyringOperationGetItemInfoCallback callback,
                                  gpointer data,
                                  GDestroyNotify destroy_data);

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

Use SecretItem objects instead.

Get information about an item, optionally retrieving its secret.

If flags includes GNOME_KEYRING_ITEM_INFO_SECRET then the user may be prompted if the calling application doesn't have necessary access to read the item with its secret.

A GnomeKeyringItemInfo pointer will be passed to the callback . Certain fields of this structure may be NULL or zero if they were not specified in flags . This structure will be freed after callback returns.

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

[skip]

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
flags	The parts of the item to retrieve.
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_item_get_info_full_sync ()

GnomeKeyringResult
gnome_keyring_item_get_info_full_sync (const char *keyring,
                                       guint32 id,
                                       guint32 flags,
                                       GnomeKeyringItemInfo **info);

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

Use SecretItem objects instead.

Get information about an item, optionally retrieving its secret.

If flags includes GNOME_KEYRING_ITEM_INFO_SECRET then the user may be prompted if the calling application doesn't have necessary access to read the item with its secret.

A GnomeKeyringItemInfo structure will be returned in info . Certain fields of this structure may be NULL or zero if they were not specified in flags . This must be freed using gnome_keyring_item_info_free().

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

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
flags	The parts of the item to retrieve.
info	The location to return a GnomeKeyringItemInfo pointer.	[out]

Returns

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

gnome_keyring_item_get_info_sync ()

GnomeKeyringResult
gnome_keyring_item_get_info_sync (const char *keyring,
                                  guint32 id,
                                  GnomeKeyringItemInfo **info);

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

Use SecretItem objects instead.

Get information about an item and its secret.

The user may be prompted if the calling application doesn't have necessary access to read the item with its secret.

A GnomeKeyringItemInfo structure will be returned in info . This must be freed using gnome_keyring_item_info_free().

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

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
info	The location to return a GnomeKeyringItemInfo pointer.	[out]

Returns

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

gnome_keyring_item_set_info ()

gpointer
gnome_keyring_item_set_info (const char *keyring,
                             guint32 id,
                             GnomeKeyringItemInfo *info,
                             GnomeKeyringOperationDoneCallback callback,
                             gpointer data,
                             GDestroyNotify destroy_data);

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

Use SecretItem objects instead.

Set information on an item, like its display name, secret etc...

Only the fields in the info pointer that are non-null or non-zero will be set on the item.

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

[skip]

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
info	The item info to save into the item.
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_item_set_info_sync ()

GnomeKeyringResult
gnome_keyring_item_set_info_sync (const char *keyring,
                                  guint32 id,
                                  GnomeKeyringItemInfo *info);

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

Use SecretItem objects instead.

Set information on an item, like its display name, secret etc...

Only the fields in the info pointer that are non-null or non-zero will be set on the item.

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

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
info	The item info to save into the item.

Returns

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

gnome_keyring_item_get_attributes ()

gpointer
gnome_keyring_item_get_attributes (const char *keyring,
                                   guint32 id,
                                   GnomeKeyringOperationGetAttributesCallback callback,
                                   gpointer data,
                                   GDestroyNotify destroy_data);

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

Use secret_item_get_attributes() instead.

Get all the attributes for an item.

A GnomeKeyringAttributeList will be passed to the callback . This list will be freed after callback returns.

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

[skip]

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
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_item_get_attributes_sync ()

GnomeKeyringResult
gnome_keyring_item_get_attributes_sync
                               (const char *keyring,
                                guint32 id,
                                GnomeKeyringAttributeList **attributes);

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

Use secret_item_get_attributes() instead.

Get all attributes for an item.

A GnomeKeyringAttributeList will be returned in attributes . This should be freed using gnome_keyring_attribute_list_free().

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

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
attributes	The location to return a pointer to the attribute list.

Returns

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

gnome_keyring_item_set_attributes ()

gpointer
gnome_keyring_item_set_attributes (const char *keyring,
                                   guint32 id,
                                   GnomeKeyringAttributeList *attributes,
                                   GnomeKeyringOperationDoneCallback callback,
                                   gpointer data,
                                   GDestroyNotify destroy_data);

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

Use secret_item_set_attributes() instead.

Set all the attributes for an item. This will replace any previous attributes set on the item.

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

[skip]

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
attributes	The full list of attributes to set on the item.
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_item_set_attributes_sync ()

GnomeKeyringResult
gnome_keyring_item_set_attributes_sync
                               (const char *keyring,
                                guint32 id,
                                GnomeKeyringAttributeList *attributes);

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

Use secret_item_set_attributes_sync() instead.

Set all the attributes for an item. This will replace any previous attributes set on the item.

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

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
attributes	The full list of attributes to set on the item.

Returns

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

gnome_keyring_item_get_acl ()

gpointer
gnome_keyring_item_get_acl (const char *keyring,
                            guint32 id,
                            GnomeKeyringOperationGetListCallback callback,
                            gpointer data,
                            GDestroyNotify destroy_data);

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

Never returns any ACL values.

[skip]

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
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_item_get_acl_sync ()

GnomeKeyringResult
gnome_keyring_item_get_acl_sync (const char *keyring,
                                 guint32 id,
                                 GList **acl);

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

Never returns any acls.

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
acl	The location to return a pointer to the access control list.	[out][element-type GnomeKeyringAccessControl]

Returns

Always GNOME_KEYRING_RESULT_OK.

gnome_keyring_item_set_acl ()

gpointer
gnome_keyring_item_set_acl (const char *keyring,
                            guint32 id,
                            GList *acl,
                            GnomeKeyringOperationDoneCallback callback,
                            gpointer data,
                            GDestroyNotify destroy_data);

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

This function no longer has any effect.

[skip]

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
acl	The access control list to set on the item.	[element-type GnomeKeyringAccessControl]
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_item_set_acl_sync ()

GnomeKeyringResult
gnome_keyring_item_set_acl_sync (const char *keyring,
                                 guint32 id,
                                 GList *acl);

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

This function no longer has any effect.

Parameters

keyring	The name of the keyring in which the item exists, or `NULL` for the default keyring.	[allow-none]
id	The id of the item
acl	The access control list to set on the item.	[element-type GnomeKeyringAccessControl]

Returns

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

gnome_keyring_item_grant_access_rights ()

gpointer
gnome_keyring_item_grant_access_rights
                               (const gchar *keyring,
                                const gchar *display_name,
                                const gchar *full_path,
                                const guint32 id,
                                const GnomeKeyringAccessType rights,
                                GnomeKeyringOperationDoneCallback callback,
                                gpointer data,
                                GDestroyNotify destroy_data);

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

This function no longer has any effect.

[skip]

Parameters

keyring	The keyring name, or `NULL` for the default keyring.	[allow-none]
display_name	The display name for the application, as returned by `g_get_application_name()`.
full_path	The full filepath to the application.
id	The id of the item to grant access to.
rights	The type of rights to grant.
callback	Callback which is called when the operation completes
data	Data to be passed to callback.	[allow-none]
destroy_data	Function to be called when data is no longer needed.

Returns

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

[transfer none]

Since: 2.20

gnome_keyring_item_grant_access_rights_sync ()

GnomeKeyringResult
gnome_keyring_item_grant_access_rights_sync
                               (const char *keyring,
                                const char *display_name,
                                const char *full_path,
                                const guint32 id,
                                const GnomeKeyringAccessType rights);

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

This function no longer has any effect.

Will grant the application access rights to the item, provided callee has write access to said item.

Parameters

keyring	The keyring name, or `NULL` for the default keyring.	[allow-none]
display_name	The display name for the application, as returned by `g_get_application_name()`.
full_path	The full filepath to the application.
id	The id of the item to grant access to.
rights	The type of rights to grant.

Returns

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

Types and Values

enum GnomeKeyringItemInfoFlags

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

The type of item info to retrieve with gnome_keyring_item_get_info_full().

Members

GNOME_KEYRING_ITEM_INFO_BASICS	Retrieve just the basic info about the item.
GNOME_KEYRING_ITEM_INFO_SECRET	Retrieve the item secret.

GNOME_KEYRING_ITEM_APPLICATION_SECRET

#define GNOME_KEYRING_ITEM_APPLICATION_SECRET 0x01000000

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

GNOME_KEYRING_ITEM_INFO_ALL

#define GNOME_KEYRING_ITEM_INFO_ALL (GNOME_KEYRING_ITEM_INFO_BASICS | GNOME_KEYRING_ITEM_INFO_SECRET)

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

GNOME_KEYRING_ITEM_NO_TYPE

#define GNOME_KEYRING_ITEM_NO_TYPE GNOME_KEYRING_ITEM_TYPE_MASK

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

GNOME_KEYRING_ITEM_TYPE_MASK

#define GNOME_KEYRING_ITEM_TYPE_MASK 0x0000ffff

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