Keyring Items

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

Synopsis

enum                MateKeyringItemInfoFlags;
void                (*MateKeyringOperationGetItemInfoCallback)
                                                        (MateKeyringResult result,
                                                         MateKeyringItemInfo *info,
                                                         gpointer data);
void                (*MateKeyringOperationGetAttributesCallback)
                                                        (MateKeyringResult result,
                                                         MateKeyringAttributeList *attributes,
                                                         gpointer data);
gpointer            mate_keyring_item_create           (const char *keyring,
                                                         MateKeyringItemType type,
                                                         const char *display_name,
                                                         MateKeyringAttributeList *attributes,
                                                         const char *secret,
                                                         gboolean update_if_exists,
                                                         MateKeyringOperationGetIntCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
MateKeyringResult  mate_keyring_item_create_sync      (const char *keyring,
                                                         MateKeyringItemType type,
                                                         const char *display_name,
                                                         MateKeyringAttributeList *attributes,
                                                         const char *secret,
                                                         gboolean update_if_exists,
                                                         guint32 *item_id);
gpointer            mate_keyring_item_delete           (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
MateKeyringResult  mate_keyring_item_delete_sync      (const char *keyring,
                                                         guint32 id);
gpointer            mate_keyring_item_get_info         (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringOperationGetItemInfoCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
gpointer            mate_keyring_item_get_info_full    (const char *keyring,
                                                         guint32 id,
                                                         guint32 flags,
                                                         MateKeyringOperationGetItemInfoCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
MateKeyringResult  mate_keyring_item_get_info_full_sync
                                                        (const char *keyring,
                                                         guint32 id,
                                                         guint32 flags,
                                                         MateKeyringItemInfo **info);
MateKeyringResult  mate_keyring_item_get_info_sync    (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringItemInfo **info);
gpointer            mate_keyring_item_set_info         (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringItemInfo *info,
                                                         MateKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
MateKeyringResult  mate_keyring_item_set_info_sync    (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringItemInfo *info);
gpointer            mate_keyring_item_get_attributes   (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringOperationGetAttributesCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
MateKeyringResult  mate_keyring_item_get_attributes_sync
                                                        (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringAttributeList **attributes);
gpointer            mate_keyring_item_set_attributes   (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringAttributeList *attributes,
                                                         MateKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
MateKeyringResult  mate_keyring_item_set_attributes_sync
                                                        (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringAttributeList *attributes);
gpointer            mate_keyring_item_get_acl          (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringOperationGetListCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
MateKeyringResult  mate_keyring_item_get_acl_sync     (const char *keyring,
                                                         guint32 id,
                                                         GList **acl);
gpointer            mate_keyring_item_set_acl          (const char *keyring,
                                                         guint32 id,
                                                         GList *acl,
                                                         MateKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
MateKeyringResult  mate_keyring_item_set_acl_sync     (const char *keyring,
                                                         guint32 id,
                                                         GList *acl);
gpointer            mate_keyring_item_grant_access_rights
                                                        (const gchar *keyring,
                                                         const gchar *display_name,
                                                         const gchar *full_path,
                                                         const guint32 id,
                                                         const MateKeyringAccessType rights,
                                                         MateKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
MateKeyringResult  mate_keyring_item_grant_access_rights_sync
                                                        (const char *keyring,
                                                         const char *display_name,
                                                         const char *full_path,
                                                         const guint32 id,
                                                         const MateKeyringAccessType 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 MateKeyringItemInfo 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 MateKeyringAttribute structures and built into lists using MateKeyringAttributeList.

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 MateKeyringAccessControl pointers.

Details

enum MateKeyringItemInfoFlags

typedef enum {
	MATE_KEYRING_ITEM_INFO_BASICS = 0,
	MATE_KEYRING_ITEM_INFO_SECRET = 1<<0
} MateKeyringItemInfoFlags;


MateKeyringOperationGetItemInfoCallback ()

void                (*MateKeyringOperationGetItemInfoCallback)
                                                        (MateKeyringResult result,
                                                         MateKeyringItemInfo *info,
                                                         gpointer data);

result :

info :

data :


MateKeyringOperationGetAttributesCallback ()

void                (*MateKeyringOperationGetAttributesCallback)
                                                        (MateKeyringResult result,
                                                         MateKeyringAttributeList *attributes,
                                                         gpointer data);

result :

attributes :

data :


mate_keyring_item_create ()

gpointer            mate_keyring_item_create           (const char *keyring,
                                                         MateKeyringItemType type,
                                                         const char *display_name,
                                                         MateKeyringAttributeList *attributes,
                                                         const char *secret,
                                                         gboolean update_if_exists,
                                                         MateKeyringOperationGetIntCallback 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 mate_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 mate_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 mate_keyring_cancel_request().

mate_keyring_item_create_sync ()

MateKeyringResult  mate_keyring_item_create_sync      (const char *keyring,
                                                         MateKeyringItemType type,
                                                         const char *display_name,
                                                         MateKeyringAttributeList *attributes,
                                                         const char *secret,
                                                         gboolean update_if_exists,
                                                         guint32 *item_id);

keyring :

type :

display_name :

attributes :

secret :

update_if_exists :

item_id :

Returns :


mate_keyring_item_delete ()

gpointer            mate_keyring_item_delete           (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringOperationDoneCallback 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 mate_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 mate_keyring_cancel_request().

mate_keyring_item_delete_sync ()

MateKeyringResult  mate_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 mate_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 :

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

mate_keyring_item_get_info ()

gpointer            mate_keyring_item_get_info         (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringOperationGetItemInfoCallback 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 MateKeyringItemInfo structure will be passed to the callback. This structure will be freed after callback returns.

For a synchronous version of this function see mate_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 mate_keyring_cancel_request().

mate_keyring_item_get_info_full ()

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

Get information about an item, optionally retrieving its secret.

If flags includes MATE_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 MateKeyringItemInfo 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 mate_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 mate_keyring_cancel_request().

mate_keyring_item_get_info_full_sync ()

MateKeyringResult  mate_keyring_item_get_info_full_sync
                                                        (const char *keyring,
                                                         guint32 id,
                                                         guint32 flags,
                                                         MateKeyringItemInfo **info);

Get information about an item, optionally retrieving its secret.

If flags includes MATE_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 MateKeyringItemInfo 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 mate_keyring_item_info_free().

For an asynchronous version of this function see mate_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 MateKeyringItemInfo pointer.

Returns :

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

mate_keyring_item_get_info_sync ()

MateKeyringResult  mate_keyring_item_get_info_sync    (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringItemInfo **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 MateKeyringItemInfo structure will be returned in info. This must be freed using mate_keyring_item_info_free().

For an asynchronous version of this function see mate_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 MateKeyringItemInfo pointer.

Returns :

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

mate_keyring_item_set_info ()

gpointer            mate_keyring_item_set_info         (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringItemInfo *info,
                                                         MateKeyringOperationDoneCallback 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 mate_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 mate_keyring_cancel_request().

mate_keyring_item_set_info_sync ()

MateKeyringResult  mate_keyring_item_set_info_sync    (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringItemInfo *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 mate_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 :

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

mate_keyring_item_get_attributes ()

gpointer            mate_keyring_item_get_attributes   (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringOperationGetAttributesCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);

Get all the attributes for an item.

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

For a synchronous version of this function see mate_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 mate_keyring_cancel_request().

mate_keyring_item_get_attributes_sync ()

MateKeyringResult  mate_keyring_item_get_attributes_sync
                                                        (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringAttributeList **attributes);

Get all attributes for an item.

A MateKeyringAttributeList will be returned in attributes. This should be freed using mate_keyring_attribute_list_free().

For an asynchronous version of this function see mate_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 :

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

mate_keyring_item_set_attributes ()

gpointer            mate_keyring_item_set_attributes   (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringAttributeList *attributes,
                                                         MateKeyringOperationDoneCallback 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 mate_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 mate_keyring_cancel_request().

mate_keyring_item_set_attributes_sync ()

MateKeyringResult  mate_keyring_item_set_attributes_sync
                                                        (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringAttributeList *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 mate_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 :

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

mate_keyring_item_get_acl ()

gpointer            mate_keyring_item_get_acl          (const char *keyring,
                                                         guint32 id,
                                                         MateKeyringOperationGetListCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);

Warning

mate_keyring_item_get_acl is deprecated and should not be used in newly-written code. Never returns any ACL values.

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

mate_keyring_item_get_acl_sync ()

MateKeyringResult  mate_keyring_item_get_acl_sync     (const char *keyring,
                                                         guint32 id,
                                                         GList **acl);

Warning

mate_keyring_item_get_acl_sync is deprecated and should not be used in newly-written code. Never returns any acls.

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 :

Always MATE_KEYRING_RESULT_OK.

mate_keyring_item_set_acl ()

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

Warning

mate_keyring_item_set_acl is deprecated and should not be used in newly-written code. This function no longer has any effect.

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

mate_keyring_item_set_acl_sync ()

MateKeyringResult  mate_keyring_item_set_acl_sync     (const char *keyring,
                                                         guint32 id,
                                                         GList *acl);

Warning

mate_keyring_item_set_acl_sync is deprecated and should not be used in newly-written code. This function no longer has any effect.

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 :

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

mate_keyring_item_grant_access_rights ()

gpointer            mate_keyring_item_grant_access_rights
                                                        (const gchar *keyring,
                                                         const gchar *display_name,
                                                         const gchar *full_path,
                                                         const guint32 id,
                                                         const MateKeyringAccessType rights,
                                                         MateKeyringOperationDoneCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);

Warning

mate_keyring_item_grant_access_rights is deprecated and should not be used in newly-written code. This function no longer has any effect.

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

Since 2.20


mate_keyring_item_grant_access_rights_sync ()

MateKeyringResult  mate_keyring_item_grant_access_rights_sync
                                                        (const char *keyring,
                                                         const char *display_name,
                                                         const char *full_path,
                                                         const guint32 id,
                                                         const MateKeyringAccessType rights);

Warning

mate_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.

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 :

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