gnome-keyring-items

gnome-keyring-items — Keyring Items

Synopsis

enum                GnomeKeyringItemInfoFlags;
void                (*GnomeKeyringOperationGetItemInfoCallback)
                                                        (GnomeKeyringResult result,
                                                         GnomeKeyringItemInfo *info,
                                                         gpointer data);
void                (*GnomeKeyringOperationGetAttributesCallback)
                                                        (GnomeKeyringResult result,
                                                         GnomeKeyringAttributeList *attributes,
                                                         gpointer data);
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);
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);
gpointer            gnome_keyring_item_delete           (const char *keyring,
                                                         guint32 id,
                                                         GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_item_delete_sync      (const char *keyring,
                                                         guint32 id);
gpointer            gnome_keyring_item_get_info         (const char *keyring,
                                                         guint32 id,
                                                         GnomeKeyringOperationGetItemInfoCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
gpointer            gnome_keyring_item_get_info_full    (const char *keyring,
                                                         guint32 id,
                                                         guint32 flags,
                                                         GnomeKeyringOperationGetItemInfoCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_item_get_info_full_sync
                                                        (const char *keyring,
                                                         guint32 id,
                                                         guint32 flags,
                                                         GnomeKeyringItemInfo **info);
GnomeKeyringResult  gnome_keyring_item_get_info_sync    (const char *keyring,
                                                         guint32 id,
                                                         GnomeKeyringItemInfo **info);
gpointer            gnome_keyring_item_set_info         (const char *keyring,
                                                         guint32 id,
                                                         GnomeKeyringItemInfo *info,
                                                         GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_item_set_info_sync    (const char *keyring,
                                                         guint32 id,
                                                         GnomeKeyringItemInfo *info);
gpointer            gnome_keyring_item_get_attributes   (const char *keyring,
                                                         guint32 id,
                                                         GnomeKeyringOperationGetAttributesCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_item_get_attributes_sync
                                                        (const char *keyring,
                                                         guint32 id,
                                                         GnomeKeyringAttributeList **attributes);
gpointer            gnome_keyring_item_set_attributes   (const char *keyring,
                                                         guint32 id,
                                                         GnomeKeyringAttributeList *attributes,
                                                         GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_item_set_attributes_sync
                                                        (const char *keyring,
                                                         guint32 id,
                                                         GnomeKeyringAttributeList *attributes);
gpointer            gnome_keyring_item_get_acl          (const char *keyring,
                                                         guint32 id,
                                                         GnomeKeyringOperationGetListCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_item_get_acl_sync     (const char *keyring,
                                                         guint32 id,
                                                         GList **acl);
gpointer            gnome_keyring_item_set_acl          (const char *keyring,
                                                         guint32 id,
                                                         GList *acl,
                                                         GnomeKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
GnomeKeyringResult  gnome_keyring_item_set_acl_sync     (const char *keyring,
                                                         guint32 id,
                                                         GList *acl);
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);
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);

Description

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.

Each item has an access control list, which specifies the applications that can read, write or delete an item. The read access applies only to reading the secret. All applications can read other parts of the item. ACLs are accessed and changed through GnomeKeyringAccessControl pointers.

Details

enum GnomeKeyringItemInfoFlags

typedef enum {
	GNOME_KEYRING_ITEM_INFO_BASICS = 0,
	GNOME_KEYRING_ITEM_INFO_SECRET = 1<<0
} GnomeKeyringItemInfoFlags;


GnomeKeyringOperationGetItemInfoCallback ()

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

result :

info :

data :


GnomeKeyringOperationGetAttributesCallback ()

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

result :

attributes :

data :


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

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

keyring :

The name of the keyring in which to create the item, or NULL for the default keyring.

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.

destroy_data :

A function to free data when it's no longer needed.

Returns :

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

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

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

keyring :

The name of the keyring in which to create the item, or NULL for the default keyring.

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.

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

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

keyring :

The name of the keyring from which to delete the item, or NULL for the default keyring.

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.

destroy_data :

A function to free data when it's no longer needed.

Returns :

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

gnome_keyring_item_delete_sync ()

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

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

keyring :

The name of the keyring from which to delete the item, or NULL for the default keyring.

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

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

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.

destroy_data :

A function to free data when it's no longer needed.

Returns :

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

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

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

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.

destroy_data :

A function to free data when it's no longer needed.

Returns :

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

gnome_keyring_item_get_info_full_sync ()

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

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

id :

The id of the item

flags :

The parts of the item to retrieve.

info :

The location to return a GnomeKeyringItemInfo pointer.

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

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

id :

The id of the item

info :

The location to return a GnomeKeyringItemInfo pointer.

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

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

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.

destroy_data :

A function to free data when it's no longer needed.

Returns :

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

gnome_keyring_item_set_info_sync ()

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

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

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

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

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.

destroy_data :

A function to free data when it's no longer needed.

Returns :

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

gnome_keyring_item_get_attributes_sync ()

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

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

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

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

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.

destroy_data :

A function to free data when it's no longer needed.

Returns :

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

gnome_keyring_item_set_attributes_sync ()

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

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

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

Get the access control list for an item.

A GList of GnomeKeyringAccessControl pointers will be passed to the callback. This list and its contents will be freed after callback returns.

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

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.

destroy_data :

A function to free data when it's no longer needed.

Returns :

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

gnome_keyring_item_get_acl_sync ()

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

Get the access control list for an item.

A GList of GnomeKeyringAccessControl pointers will be passed to the callback. This list should be freed using gnome_keyring_access_control_list_free(). For an asynchronous version of this function see gnome_keyring_item_get_acl().

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

id :

The id of the item

acl :

The location to return a pointer to the access control list.

Returns :

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

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

Set the full access control list on an item. This replaces any previous ACL setup on the item.

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

id :

The id of the item

acl :

The access control list 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.

destroy_data :

A function to free data when it's no longer needed.

Returns :

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

gnome_keyring_item_set_acl_sync ()

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

Set the full access control list on an item. This replaces any previous ACL setup on the item.

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

keyring :

The name of the keyring in which the item exists, or NULL for the default keyring.

id :

The id of the item

acl :

The access control list to set on the item.

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

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

This is similar to calling gnome_keyring_item_get_acl() and gnome_keyring_item_set_acl() with appropriate parameters.

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

keyring :

The keyring name, or NULL for the default keyring.

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

destroy_data :

Function to be called when data is no longer needed.

Returns :

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

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

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

keyring :

The keyring name, or NULL for the default keyring.

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.