## Keyrings

Keyrings — Listing and managing keyrings

## Synopsis

    void                (*MateKeyringOperationGetKeyringInfoCallback)
                                                            (MateKeyringResult result,
                                                             MateKeyringInfo *info,
                                                             gpointer data);
    gpointer            mate_keyring_set_default_keyring   (const char *keyring,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_set_default_keyring_sync
                                                            (const char *keyring);
    gpointer            mate_keyring_get_default_keyring   (MateKeyringOperationGetStringCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_get_default_keyring_sync
                                                            (char **keyring);
    gpointer            mate_keyring_list_keyring_names    (MateKeyringOperationGetListCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_list_keyring_names_sync
                                                            (GList **keyrings);
    gpointer            mate_keyring_lock_all              (MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_lock_all_sync         (void);
    gpointer            mate_keyring_create                (const char *keyring_name,
                                                             const char *password,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_create_sync           (const char *keyring_name,
                                                             const char *password);
    gpointer            mate_keyring_unlock                (const char *keyring,
                                                             const char *password,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_unlock_sync           (const char *keyring,
                                                             const char *password);
    gpointer            mate_keyring_lock                  (const char *keyring,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_lock_sync             (const char *keyring);
    gpointer            mate_keyring_delete                (const char *keyring,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_delete_sync           (const char *keyring);
    gpointer            mate_keyring_get_info              (const char *keyring,
                                                             MateKeyringOperationGetKeyringInfoCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_get_info_sync         (const char *keyring,
                                                             MateKeyringInfo **info);
    gpointer            mate_keyring_set_info              (const char *keyring,
                                                             MateKeyringInfo *info,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_set_info_sync         (const char *keyring,
                                                             MateKeyringInfo *info);
    gpointer            mate_keyring_change_password       (const char *keyring,
                                                             const char *original,
                                                             const char *password,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_change_password_sync  (const char *keyring,
                                                             const char *original,
                                                             const char *password);
    gpointer            mate_keyring_list_item_ids         (const char *keyring,
                                                             MateKeyringOperationGetListCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    MateKeyringResult  mate_keyring_list_item_ids_sync    (const char *keyring,
                                                             GList **ids);

## Description

`mate`-keyring-daemon manages multiple keyrings. Each keyring can store one or more items containing secrets.

One of the keyrings is the default keyring, which can in many cases be used by specifying `NULL` for a keyring name.

Each keyring can be in a locked or unlocked state. A password must be specified, either by the user or the calling application, to unlock the keyring.

## Details

### MateKeyringOperationGetKeyringInfoCallback ()

    void                (*MateKeyringOperationGetKeyringInfoCallback)
                                                            (MateKeyringResult result,
                                                             MateKeyringInfo *info,
                                                             gpointer data);

`result` : |
`info` : |
`data` : |

### mate_keyring_set_default_keyring ()

    gpointer            mate_keyring_set_default_keyring   (const char *keyring,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Change the default keyring.

For a synchronous version of this function see `mate_keyring_set_default_keyring_sync()`.

`keyring` : | The keyring to make default
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`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_set_default_keyring_sync ()

    MateKeyringResult  mate_keyring_set_default_keyring_sync
                                                            (const char *keyring);

Change the default keyring.

For an asynchronous version of this function see `mate_keyring_set_default_keyring()`.

`keyring` : | The keyring to make default
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_get_default_keyring ()

    gpointer            mate_keyring_get_default_keyring   (MateKeyringOperationGetStringCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Get the default keyring name, which will be passed to the `callback`. If no default keyring exists, then `NULL` will be passed to the `callback`. The string will be freed after `callback` returns.

For a synchronous version of this function see `mate_keyring_get_default_keyring_sync()`.

`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`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_get_default_keyring_sync ()

    MateKeyringResult  mate_keyring_get_default_keyring_sync
                                                            (char **keyring);

Get the default keyring name.

The string returned in `keyring` must be freed with `g_free()`.

For an asynchronous version of this function see `mate_keyring_get_default_keyring()`.

`keyring` : | Location for the default keyring name to be returned.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_list_keyring_names ()

    gpointer            mate_keyring_list_keyring_names    (MateKeyringOperationGetListCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Get a list of keyring names.

A `GList` of null terminated strings will be passed to the `callback`. If no keyrings exist then an empty list will be passed to the `callback`. The list is freed after `callback` returns.

For a synchronous version of this function see `mate_keyring_list_keyrings_sync()`.

`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`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_list_keyring_names_sync ()

    MateKeyringResult  mate_keyring_list_keyring_names_sync
                                                            (GList **keyrings);

Get a list of keyring names.

The list returned in in `keyrings` must be freed using `mate_keyring_string_list_free()`.

For an asynchronous version of this function see `mate_keyring_list_keyring_names()`.

`keyrings` : | Location for a `GList` of keyring names to be returned.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_lock_all ()

    gpointer            mate_keyring_lock_all              (MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Lock all the keyrings, so that their contents may not be accessed without first unlocking them with a password.

For a synchronous version of this function see `mate_keyring_lock_all_sync()`.

`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`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_lock_all_sync ()

    MateKeyringResult  mate_keyring_lock_all_sync         (void);

Lock all the keyrings, so that their contents may not eb accessed without first unlocking them with a password.

For an asynchronous version of this function see `mate_keyring_lock_all()`.

Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_create ()

    gpointer            mate_keyring_create                (const char *keyring_name,
                                                             const char *password,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Create a new keyring with the specified name. In most cases `NULL` will be passed as the `password`, which will prompt the user to enter a password of their choice.

For a synchronous version of this function see `mate_keyring_create_sync()`.

`keyring_name` : | The new keyring name. Must not be `NULL`.
`password` : | The password for the new keyring. If `NULL` user will be prompted.
`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_create_sync ()

    MateKeyringResult  mate_keyring_create_sync           (const char *keyring_name,
                                                             const char *password);

Create a new keyring with the specified name. In most cases `NULL` will be passed in as the `password`, which will prompt the user to enter a password of their choice.

For an asynchronous version of this function see `mate_keyring_create()`.

`keyring_name` : | The new keyring name. Must not be `NULL`
`password` : | The password for the new keyring. If `NULL` user will be prompted.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_unlock ()

    gpointer            mate_keyring_unlock                (const char *keyring,
                                                             const char *password,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Unlock a `keyring`, so that its contents may be accessed. In most cases `NULL` will be passed as the `password`, which will prompt the user to enter the correct password.

Most keyring operations involving items require that you first unlock the keyring. One exception is `mate_keyring_find_items()` and related functions.

For a synchronous version of this function see `mate_keyring_unlock_sync()`.

`keyring` : | The name of the keyring to unlock, or `NULL` for the default keyring.
`password` : | The password to unlock the keyring with, or `NULL` to prompt the user.
`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_unlock_sync ()

    MateKeyringResult  mate_keyring_unlock_sync           (const char *keyring,
                                                             const char *password);

Unlock a `keyring`, so that its contents may be accessed. In most cases `NULL` will be passed in as the `password`, which will prompt the user to enter the correct password.

Most keyring opretaions involving items require that yo ufirst unlock the keyring. One exception is `mate_keyring_find_items_sync()` and related functions.

For an asynchronous version of this function see `mate_keyring_unlock()`.

`keyring` : | The name of the keyring to unlock, or `NULL` for the default keyring.
`password` : | The password to unlock the keyring with, or `NULL` to prompt the user.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_lock ()

    gpointer            mate_keyring_lock                  (const char *keyring,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Lock a `keyring`, so that its contents may not be accessed without first supplying a password.

Most keyring operations involving items require that you first unlock the keyring. One exception is `mate_keyring_find_items()` and related functions.

For a synchronous version of this function see `mate_keyring_lock_sync()`.

`keyring` : | The name of the keyring to lock, or `NULL` for the default keyring.
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`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_lock_sync ()

    MateKeyringResult  mate_keyring_lock_sync             (const char *keyring);

Lock a `keyring`, so that its contents may not be accessed without first supplying a password.

Most keyring opretaions involving items require that you first unlock the keyring. One exception is `mate_keyring_find_items_sync()` and related functions.

For an asynchronous version of this function see `mate_keyring_lock()`.

`keyring` : | The name of the keyring to lock, or `NULL` for the default keyring.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_delete ()

    gpointer            mate_keyring_delete                (const char *keyring,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Delete `keyring`. Once a keyring is deleted there is no mechanism for recovery of its contents.

For a synchronous version of this function see `mate_keyring_delete_sync()`.

`keyring` : | The name of the keyring to delete. Cannot be `NULL`.
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`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_delete_sync ()

    MateKeyringResult  mate_keyring_delete_sync           (const char *keyring);

Delete `keyring`. Once a keyring is deleted there is no mechanism for recovery of its contents.

For an asynchronous version of this function see `mate_keyring_delete()`.

`keyring` : | The name of the keyring to delete. Cannot be `NULL`
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_get_info ()

    gpointer            mate_keyring_get_info              (const char *keyring,
                                                             MateKeyringOperationGetKeyringInfoCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Get information about the `keyring`. The resulting MateKeyringInfo structure will be passed to `callback`. The structure is freed after `callback` returns.

For a synchronous version of this function see `mate_keyring_get_info_sync()`.

`keyring` : | The name of the keyring, or `NULL` for the default keyring.
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`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_get_info_sync ()

    MateKeyringResult  mate_keyring_get_info_sync         (const char *keyring,
                                                             MateKeyringInfo **info);

Get information about `keyring`.

The MateKeyringInfo structure returned in `info` must be freed with `mate_keyring_info_free()`.

For an asynchronous version of this function see `mate_keyring_get_info()`.

`keyring` : | The name of the keyring, or `NULL` for the default keyring.
`info` : | Location for the information about the keyring to be returned.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_set_info ()

    gpointer            mate_keyring_set_info              (const char *keyring,
                                                             MateKeyringInfo *info,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Set flags and info for the `keyring`. The only fields in `info` that are used are `lock_on_idle` and `lock_timeout`.

For a synchronous version of this function see `mate_keyring_set_info_sync()`.

`keyring` : | The name of the keyring, or `NULL` for the default keyring.
`info` : | A structure containing flags and info for the keyring.
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`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_set_info_sync ()

    MateKeyringResult  mate_keyring_set_info_sync         (const char *keyring,
                                                             MateKeyringInfo *info);

Set flags and info for `keyring`. The only fields in `info` that are used are `lock_on_idle` and `lock_timeout`.

For an asynchronous version of this function see `mate_keyring_set_info()`.

`keyring` : | The name of the keyring, or `NULL` for the default keyring.
`info` : | A structure containing flags and info for the keyring.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_change_password ()

    gpointer            mate_keyring_change_password       (const char *keyring,
                                                             const char *original,
                                                             const char *password,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Change the password for a `keyring`. In most cases you would specify `NULL` for both the `original` and `password` arguments and allow the user to type the correct passwords.

For a synchronous version of this function see `mate_keyring_change_password_sync()`.

`keyring` : | The name of the keyring to change the password for. Cannot be `NULL`.
`original` : | The old keyring password, or `NULL` to prompt the user for it.
`password` : | The new keyring password, or `NULL` to prompt the user for it.
`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_change_password_sync ()

    MateKeyringResult  mate_keyring_change_password_sync  (const char *keyring,
                                                             const char *original,
                                                             const char *password);

Change the password for `keyring`. In most cases you would specify `NULL` for both the `original` and `password` arguments and allow the user to type the correct passwords.

For an asynchronous version of this function see `mate_keyring_change_password()`.

`keyring` : | The name of the keyring to change the password for. Cannot be `NULL`
`original` : | The old keyring password, or `NULL` to prompt the user for it.
`password` : | The new keyring password, or `NULL` to prompt the user for it.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_list_item_ids ()

    gpointer            mate_keyring_list_item_ids         (const char *keyring,
                                                             MateKeyringOperationGetListCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Get a list of all the ids for items in `keyring`. These are passed in a `GList` to the `callback`. Use `GPOINTER_TO_UINT()` on the list to access the integer ids. The list is freed after `callback` returns.

All items that are not flagged as `MATE_KEYRING_ITEM_APPLICATION_SECRET` are included in the list. This includes items that the calling application may not (yet) have access to.

For a synchronous version of this function see `mate_keyring_list_item_ids_sync()`.

`keyring` : | The name of the keyring, or `NULL` for the default keyring.
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`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_list_item_ids_sync ()

    MateKeyringResult  mate_keyring_list_item_ids_sync    (const char *keyring,
                                                             GList **ids);

Get a list of all the ids for items in `keyring`.

Use `GPOINTER_TO_UINT()` on the list to access the integer ids. The list should be freed with `g_list_free()`.

For an asynchronous version of this function see `mate_keyring_list_item_ids()`.

`keyring` : | The name of the keyring, or `NULL` for the default keyring.
`ids` : | The location to store a `GList` of item ids (ie: unsigned integers).
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.