gnome-keyring Reference Manual: Keyrings

## Keyrings Keyrings — Listing and managing keyrings |

## Functions

void | (*GnomeKeyringOperationGetKeyringInfoCallback) ()
gpointer | gnome_keyring_set_default_keyring ()
GnomeKeyringResult | gnome_keyring_set_default_keyring_sync ()
gpointer | gnome_keyring_get_default_keyring ()
GnomeKeyringResult | gnome_keyring_get_default_keyring_sync ()
gpointer | gnome_keyring_list_keyring_names ()
GnomeKeyringResult | gnome_keyring_list_keyring_names_sync ()
gpointer | gnome_keyring_lock_all ()
GnomeKeyringResult | gnome_keyring_lock_all_sync ()
gpointer | gnome_keyring_create ()
GnomeKeyringResult | gnome_keyring_create_sync ()
gpointer | gnome_keyring_unlock ()
GnomeKeyringResult | gnome_keyring_unlock_sync ()
gpointer | gnome_keyring_lock ()
GnomeKeyringResult | gnome_keyring_lock_sync ()
gpointer | gnome_keyring_delete ()
GnomeKeyringResult | gnome_keyring_delete_sync ()
gpointer | gnome_keyring_get_info ()
GnomeKeyringResult | gnome_keyring_get_info_sync ()
gpointer | gnome_keyring_set_info ()
GnomeKeyringResult | gnome_keyring_set_info_sync ()
gpointer | gnome_keyring_change_password ()
GnomeKeyringResult | gnome_keyring_change_password_sync ()
gpointer | gnome_keyring_list_item_ids ()
GnomeKeyringResult | gnome_keyring_list_item_ids_sync ()

## Object Hierarchy

## Description

All of these APIs are deprecated. Use libsecret instead.
`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.

## Functions

### GnomeKeyringOperationGetKeyringInfoCallback ()

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

`GnomeKeyringOperationGetKeyringInfoCallback` is deprecated and should not be used in newly-written code.

### gnome_keyring_set_default_keyring ()

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

`gnome_keyring_set_default_keyring` is deprecated and should not be used in newly-written code.

Use `secret_service_set_alias()` instead.

Change the default keyring.

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

#### Parameters

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

`gnome_keyring_set_default_keyring_sync` is deprecated and should not be used in newly-written code.

Use `secret_service_set_alias_sync()` instead.

Change the default keyring.

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

#### Parameters

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

`gnome_keyring_get_default_keyring` is deprecated and should not be used in newly-written code.

Use `secret_collection_for_alias()` instead.

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

#### Parameters

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

`gnome_keyring_get_default_keyring_sync` is deprecated and should not be used in newly-written code.

Use `secret_collection_for_alias_sync()` instead.

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

#### Parameters

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

`gnome_keyring_list_keyring_names` is deprecated and should not be used in newly-written code.

Use `secret_service_get_collections()` instead.

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

#### Parameters

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

`gnome_keyring_list_keyring_names_sync` is deprecated and should not be used in newly-written code.

Use `secret_service_get_collections()` instead.

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

#### Parameters

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

`gnome_keyring_lock_all` is deprecated and should not be used in newly-written code.

Use libsecret instead.

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

#### Parameters

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

`gnome_keyring_lock_all_sync` is deprecated and should not be used in newly-written code.

Use libsecret instead.

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

`gnome_keyring_create` is deprecated and should not be used in newly-written code.

Use `secret_collection_create()` instead.

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

#### Parameters

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

`gnome_keyring_create_sync` is deprecated and should not be used in newly-written code.

Use `secret_collection_create_sync()` instead.

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

#### Parameters

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

`gnome_keyring_unlock` is deprecated and should not be used in newly-written code.

Use `secret_service_unlock()` instead.

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

#### Parameters

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

`gnome_keyring_unlock_sync` is deprecated and should not be used in newly-written code.

Use `secret_service_unlock_sync()` instead.

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

#### Parameters

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

`gnome_keyring_lock` is deprecated and should not be used in newly-written code.

Use `secret_service_lock()` instead.

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

#### Parameters

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

`gnome_keyring_lock_sync` is deprecated and should not be used in newly-written code.

Use `secret_service_lock_sync()` instead.

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

#### Parameters

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

`gnome_keyring_delete` is deprecated and should not be used in newly-written code.

Use `secret_collection_delete()` instead.

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

#### Parameters

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

`gnome_keyring_delete_sync` is deprecated and should not be used in newly-written code.

Use `secret_collection_delete_sync()` instead.

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

#### Parameters

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

`gnome_keyring_get_info` is deprecated and should not be used in newly-written code.

Use SecretCollection objects instead.

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

#### Parameters

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

`gnome_keyring_get_info_sync` is deprecated and should not be used in newly-written code.

Use SecretCollection objects instead.

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

#### Parameters

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

`gnome_keyring_set_info` is deprecated and should not be used in newly-written code.

Use SecretCollection objects instead.

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

#### Parameters

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

`gnome_keyring_set_info_sync` is deprecated and should not be used in newly-written code.

Use SecretCollection objects instead.

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

#### Parameters

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

`gnome_keyring_change_password` is deprecated and should not be used in newly-written code.

Not used with libsecret.

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

#### Parameters

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

`gnome_keyring_change_password_sync` is deprecated and should not be used in newly-written code.

Not used with libsecret.

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

#### Parameters

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

`gnome_keyring_list_item_ids` is deprecated and should not be used in newly-written code.

Use `secret_collection_get_items()` instead.

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

#### Parameters

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

`gnome_keyring_list_item_ids_sync` is deprecated and should not be used in newly-written code.

Use `secret_collection_get_items()` instead.

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

#### Parameters

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.

## Types and Values