## Keyring Items

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

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