Keyrings

## Keyrings Keyrings — Listing and managing keyrings |

## Synopsis

    void                (*GnomeKeyringOperationGetKeyringInfoCallback)
                                                            (GnomeKeyringResult result,
                                                             GnomeKeyringInfo *info,
                                                             gpointer data);
    gpointer            gnome_keyring_set_default_keyring   (const char *keyring,
                                                             GnomeKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_set_default_keyring_sync
                                                            (const char *keyring);
    gpointer            gnome_keyring_get_default_keyring   (GnomeKeyringOperationGetStringCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_get_default_keyring_sync
                                                            (char **keyring);
    gpointer            gnome_keyring_list_keyring_names    (GnomeKeyringOperationGetListCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_list_keyring_names_sync
                                                            (GList **keyrings);
    gpointer            gnome_keyring_lock_all              (GnomeKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_lock_all_sync         (void);
    gpointer            gnome_keyring_create                (const char *keyring_name,
                                                             const char *password,
                                                             GnomeKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_create_sync           (const char *keyring_name,
                                                             const char *password);
    gpointer            gnome_keyring_unlock                (const char *keyring,
                                                             const char *password,
                                                             GnomeKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_unlock_sync           (const char *keyring,
                                                             const char *password);
    gpointer            gnome_keyring_lock                  (const char *keyring,
                                                             GnomeKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_lock_sync             (const char *keyring);
    gpointer            gnome_keyring_delete                (const char *keyring,
                                                             GnomeKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_delete_sync           (const char *keyring);
    gpointer            gnome_keyring_get_info              (const char *keyring,
                                                             GnomeKeyringOperationGetKeyringInfoCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_get_info_sync         (const char *keyring,
                                                             GnomeKeyringInfo **info);
    gpointer            gnome_keyring_set_info              (const char *keyring,
                                                             GnomeKeyringInfo *info,
                                                             GnomeKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_set_info_sync         (const char *keyring,
                                                             GnomeKeyringInfo *info);
    gpointer            gnome_keyring_change_password       (const char *keyring,
                                                             const char *original,
                                                             const char *password,
                                                             GnomeKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_change_password_sync  (const char *keyring,
                                                             const char *original,
                                                             const char *password);
    gpointer            gnome_keyring_list_item_ids         (const char *keyring,
                                                             GnomeKeyringOperationGetListCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    GnomeKeyringResult  gnome_keyring_list_item_ids_sync    (const char *keyring,
                                                             GList **ids);

## Description

`gnome-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

### GnomeKeyringOperationGetKeyringInfoCallback ()

    void                (*GnomeKeyringOperationGetKeyringInfoCallback)
                                                            (GnomeKeyringResult result,
                                                             GnomeKeyringInfo *info,
                                                             gpointer data);

### gnome_keyring_set_default_keyring ()

    gpointer            gnome_keyring_set_default_keyring   (const char *keyring,
                                                             GnomeKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Change the default keyring.

For a synchronous version of this function see `gnome_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`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_set_default_keyring_sync ()

    GnomeKeyringResult  gnome_keyring_set_default_keyring_sync
                                                            (const char *keyring);

Change the default keyring.

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

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

### gnome_keyring_get_default_keyring ()

    gpointer            gnome_keyring_get_default_keyring   (GnomeKeyringOperationGetStringCallback 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 `gnome_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`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_get_default_keyring_sync ()

    GnomeKeyringResult  gnome_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 `gnome_keyring_get_default_keyring()`.

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

### gnome_keyring_list_keyring_names ()

    gpointer            gnome_keyring_list_keyring_names    (GnomeKeyringOperationGetListCallback 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 `gnome_keyring_list_keyring_names_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`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_list_keyring_names_sync ()

    GnomeKeyringResult  gnome_keyring_list_keyring_names_sync
                                                            (GList **keyrings);

Get a list of keyring names.

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

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

`keyrings` : | Location for a `GList` of keyring names to be returned. [out][element-type utf8]
Returns : | `GNOME_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### gnome_keyring_lock_all ()

    gpointer            gnome_keyring_lock_all              (GnomeKeyringOperationDoneCallback 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 `gnome_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`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_lock_all_sync ()

    GnomeKeyringResult  gnome_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 `gnome_keyring_lock_all()`.

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

### gnome_keyring_create ()

    gpointer            gnome_keyring_create                (const char *keyring_name,
                                                             const char *password,
                                                             GnomeKeyringOperationDoneCallback 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 `gnome_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. [allow-none]
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_create_sync ()

    GnomeKeyringResult  gnome_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 `gnome_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. [allow-none]
Returns : | `GNOME_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### gnome_keyring_unlock ()

    gpointer            gnome_keyring_unlock                (const char *keyring,
                                                             const char *password,
                                                             GnomeKeyringOperationDoneCallback 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 `gnome_keyring_find_items()` and related functions.

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

`keyring` : | The name of the keyring to unlock, or `NULL` for the default keyring. [allow-none]
`password` : | The password to unlock the keyring with, or `NULL` to prompt the user. [allow-none]
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_unlock_sync ()

    GnomeKeyringResult  gnome_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 `gnome_keyring_find_items_sync()` and related functions.

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

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

### gnome_keyring_lock ()

    gpointer            gnome_keyring_lock                  (const char *keyring,
                                                             GnomeKeyringOperationDoneCallback 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 `gnome_keyring_find_items()` and related functions.

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

`keyring` : | The name of the keyring to lock, or `NULL` for the default keyring. [allow-none]
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_lock_sync ()

    GnomeKeyringResult  gnome_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 `gnome_keyring_find_items_sync()` and related functions.

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

`keyring` : | The name of the keyring to lock, or `NULL` for the default keyring. [allow-none]
Returns : | `GNOME_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### gnome_keyring_delete ()

    gpointer            gnome_keyring_delete                (const char *keyring,
                                                             GnomeKeyringOperationDoneCallback 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 `gnome_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`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_delete_sync ()

    GnomeKeyringResult  gnome_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 `gnome_keyring_delete()`.

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

### gnome_keyring_get_info ()

    gpointer            gnome_keyring_get_info              (const char *keyring,
                                                             GnomeKeyringOperationGetKeyringInfoCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

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

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

`keyring` : | The name of the keyring, or `NULL` for the default keyring. [allow-none]
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_get_info_sync ()

    GnomeKeyringResult  gnome_keyring_get_info_sync         (const char *keyring,
                                                             GnomeKeyringInfo **info);

Get information about `keyring`.

The GnomeKeyringInfo structure returned in `info` must be freed with `gnome_keyring_info_free()`.

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

`keyring` : | The name of the keyring, or `NULL` for the default keyring. [allow-none]
`info` : | Location for the information about the keyring to be returned. [out]
Returns : | `GNOME_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### gnome_keyring_set_info ()

    gpointer            gnome_keyring_set_info              (const char *keyring,
                                                             GnomeKeyringInfo *info,
                                                             GnomeKeyringOperationDoneCallback 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 `gnome_keyring_set_info_sync()`.

`keyring` : | The name of the keyring, or `NULL` for the default keyring. [allow-none]
`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`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_set_info_sync ()

    GnomeKeyringResult  gnome_keyring_set_info_sync         (const char *keyring,
                                                             GnomeKeyringInfo *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 `gnome_keyring_set_info()`.

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

### gnome_keyring_change_password ()

    gpointer            gnome_keyring_change_password       (const char *keyring,
                                                             const char *original,
                                                             const char *password,
                                                             GnomeKeyringOperationDoneCallback 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 `gnome_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. [allow-none]
`password` : | The new keyring password, or `NULL` to prompt the user for it. [allow-none]
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_change_password_sync ()

    GnomeKeyringResult  gnome_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 `gnome_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. [allow-none]
`password` : | The new keyring password, or `NULL` to prompt the user for it. [allow-none]
Returns : | `GNOME_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### gnome_keyring_list_item_ids ()

    gpointer            gnome_keyring_list_item_ids         (const char *keyring,
                                                             GnomeKeyringOperationGetListCallback 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 `GNOME_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 `gnome_keyring_list_item_ids_sync()`.

`keyring` : | The name of the keyring, or `NULL` for the default keyring. [allow-none]
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`. [allow-none]
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`. [transfer none]

### gnome_keyring_list_item_ids_sync ()

    GnomeKeyringResult  gnome_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 `gnome_keyring_list_item_ids()`.

`keyring` : | The name of the keyring, or `NULL` for the default keyring. [allow-none]
`ids` : | The location to store a `GList` of item ids (ie: unsigned integers). [out][element-type guint]
Returns : | `GNOME_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.