Conceptually, libgnome-keyring and libsecret are fairly similar. Both have keyrings, items, and ways to store and retrieve passwords. In both cases items have attributes. The keys and values of attributes are used to lookup a password that was stored. There is a simple password API for storing and retrieving passwords which is the easiest and recommended way to store passwords. And then there is a more complicated API which models all the various collections and items, along with all the possible actions that can be performed on them. libsecret uses the Secret Service DBus API to communicate with gnome-keyring-daemon, and as such exposes features based on that DBus API. libsecret has been designed to be threadsafe, and uses the 'GDBus' code in gio to accomplish this. Keyrings are called 'collections' in libsecret. See the relevant section for specifics about how to port the libgnome-keyring functions or symbols in your project. Here are some clues on how to migrate various libgnome-keyring API functions and their logical equivalents in libsecret.

Remember that attributes are not, and never have been stored in an encrypted fashion. They are not part of the 'secret', but instead are a way to lookup a secret item. All attributes in libsecret are stored as strings. Sets of attributes are represented by #GHashTables and the keys and values of these hash tables are strings. libsecret is far more focused on schemas, and encourages users to define a #SecretSchema for their password storage. The schema defines which attributes are allowed an item. Each schema has a name which is usually a dotted string (eg: org.gnome.MyProject.Password). This schema name is stored internally in the item attributes. Schemas define whether an attribute should look like an integer, a boolean, or a free-form string. These types are used when validating the attribute values, even though the attribute values are stored and matched as strings. Since attribute values are used primarily for lookup of items it's important that the string representations of integers and booleans are always identical. Boolean values are stored as the strings true and false. Integer values are stored in decimal, with a preceding negative sign for negative integers. libsecret facilitates this using the secret_attributes_build() and secret_attributes_buildv() functions. Attributes are meant to be used for lookup of items; they're not designed to be used as a generic key/value database. Although you can force libsecret to do the latter, it's better to store your account information elsewhere if possible, and use libsecret to store the password or other secret. Replacements for related libgnome-keyring functions and types are described below: libgnome-keyringlibsecret #GnomeKeyringAttributeList a #GHashTable of string keys and values #GnomeKeyringAttribute a key/value pair in a #GHashTable of strings #GnomeKeyringAttributeType #SecretSchemaAttributeType %GNOME_KEYRING_ATTRIBUTE_TYPE_STRING %SECRET_SCHEMA_ATTRIBUTE_STRING %GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32 %SECRET_SCHEMA_ATTRIBUTE_INTEGER gnome_keyring_attribute_list_index() use g_hash_table_lookup() on the attributes hash table gnome_keyring_attribute_get_string() use g_hash_table_lookup() on the attributes hash table gnome_keyring_attribute_get_uint32() no equivalent, use g_hash_table_lookup() gnome_keyring_attribute_list_append_string() secret_attributes_build() gnome_keyring_attribute_list_append_uint32() secret_attributes_build() gnome_keyring_attribute_list_copy() g_hash_table_ref() gnome_keyring_attribute_list_free() g_hash_table_unref() gnome_keyring_attribute_list_index() no equivalent, use g_hash_table_lookup() gnome_keyring_attribute_list_new() secret_attributes_build()

libsecret is far more focused on schemas, and encourages users to define a #SecretSchema for their password storage. The schema defines which attributes are allowed an item. Each schema has a name which is usually a dotted string (eg: org.gnome.MyProject.Password). This name is stored in the item attributes. The schema name is also used when looking up an item, to make sure that the stored schema matches that used during the lookup. If you wish to lookup items that were stored by libgnome-keyring, you should specify the %SECRET_SCHEMA_DONT_MATCH_NAME flag in the schema so that the schema name is not matched, since it was not stored by libgnome-keyring. Schemas define whether an attribute should look like an integer, a boolean, or a free-form string. These types are used when validating the attribute values stored, even though the attribute values are stored and matched as strings. Replacements for related libgnome-keyring functions and types are described below: libgnome-keyringlibsecret #GnomeKeyringPasswordSchema #SecretSchema #GnomeKeyringPasswordSchemaAttribute #SecretSchemaAttribute %GNOME_KEYRING_ITEM_APPLICATION_SECRET no equivalent %GNOME_KEYRING_ITEM_CHAINED_KEYRING_PASSWORD no equivalent %GNOME_KEYRING_ITEM_ENCRYPTION_KEY_PASSWORD no equivalent %GNOME_KEYRING_ITEM_PK_STORAGE no equivalent %GNOME_KEYRING_ITEM_GENERIC_SECRET no equivalent, define a specific schema with an appropriate dotted name %GNOME_KEYRING_ITEM_NETWORK_PASSWORD the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses %GNOME_KEYRING_ITEM_NOTE the %SECRET_SCHEMA_NOTE schema %GNOME_KEYRING_NETWORK_PASSWORD the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses

It's encouraged to use a #SecretSchema when storing items and passwords. By default most ways of storing an item will now overwrite another item with the same attributes in the same keyring. To manually control this behavior use the secret_item_create(). Replacements for related libgnome-keyring functions and types are described below: libgnome-keyringlibsecret %GNOME_KEYRING_DEFAULT %SECRET_COLLECTION_DEFAULT %GNOME_KEYRING_SESSION %SECRET_COLLECTION_SESSION gnome_keyring_store_password() secret_password_store() gnome_keyring_store_password_sync() secret_password_store_sync() gnome_keyring_set_network_password() secret_password_store() with %SECRET_SCHEMA_COMPAT_NETWORK although this is not recommended for new uses. gnome_keyring_set_network_password_sync() secret_password_store_sync() with %SECRET_SCHEMA_COMPAT_NETWORK although this is not recommended for new uses. gnome_keyring_item_create() secret_item_create(), although using secret_password_store() is simpler. gnome_keyring_item_create_sync() secret_item_create(), although using secret_password_store_sync() is simpler.

In general libsecret tries not to unlocking keyrings where not necessary. Many search methods only return one item or password that matches, preferring already unlocked items, and recently stored items. Attributes are meant to be used for lookup of items; they're not designed to be used as a generic key/value database. Although you can force libsecret to do the latter, it's better to store your account information elsewhere if possible, and use libsecret to store the password or other secret. Because of this many search methods return just the password or secret. Replacements for related libgnome-keyring functions and types are described below: libgnome-keyringlibsecret gnome_keyring_find_password() secret_password_lookup() gnome_keyring_find_password_sync() secret_password_lookup_sync() gnome_keyring_find_items() secret_service_search(), with flags to fine tune behavior gnome_keyring_find_itemsv() secret_service_search(), with flags to fine tune behavior gnome_keyring_find_items_sync() secret_service_search_sync(), with flags to fine tune behavior gnome_keyring_find_itemsv_sync() secret_service_search(), with flags to fine tune behavior GnomeKeyringFound no equivalent, secret_service_search() returns a #GList of #SecretItems, and other methods return passwords directly. gnome_keyring_found_copy() no equivalent gnome_keyring_found_free() g_object_unref() on the each of the items returned from secret_service_search() gnome_keyring_found_list_free() g_list_free_full() used with g_object_unref() on the items returned from secret_service_search() gnome_keyring_find_network_password() secret_password_lookup() with %SECRET_SCHEMA_COMPAT_NETWORK, although this only returns one password and no attributes gnome_keyring_find_network_password_sync() secret_password_lookup_sync() with %SECRET_SCHEMA_COMPAT_NETWORK, although this only returns one password and no attributes #GnomeKeyringNetworkPasswordData no equivalent, secret_password_lookup() gets the password directly and no attributes gnome_keyring_network_password_free() no equivalent gnome_keyring_network_password_list_free() no equivalent

Neither libgnome-keyring or libsecret allow deletion of locked items. libsecret tries to make it easier to delete all unlocked items matching certain attributes. Replacements for related libgnome-keyring functions and types are described below: libgnome-keyringlibsecret gnome_keyring_delete_password() secret_password_clear(), although we now try to delete all unlocked matching items gnome_keyring_delete_password_sync() secret_password_clear_sync(), although we now try to delete all unlocked matching items gnome_keyring_item_delete() secret_item_delete() gnome_keyring_item_delete_sync() secret_item_delete_sync()

In libsecret items are no longer identified by an unsigned integer. Applications should retrieve items based on their attributes. It is also possible to identify an item by its DBus object path. Replacements for related libgnome-keyring functions and types are described below: libgnome-keyringlibsecret gnome_keyring_item_create() secret_item_create(), although secret_password_store() may be simpler gnome_keyring_item_create_sync() secret_item_create_sync(), although secret_password_store_sync() may be simpler gnome_keyring_item_delete() secret_item_delete(), although secret_password_clear() may be simpler gnome_keyring_item_delete_sync() secret_item_delete_sync(), although secret_password_clear_sync() may be simpler gnome_keyring_item_get_info() properties are loaded on a #SecretItem automatically, use secret_item_load_secret() to load the secret gnome_keyring_item_get_info_sync() properties are loaded on a #SecretItem automatically, use secret_item_load_secret_sync() to load the secret gnome_keyring_item_get_info_full() properties are loaded on a #SecretItem automatically, use secret_item_load_secret() to load the secret gnome_keyring_item_get_info_full_sync() properties are loaded on a #SecretItem automatically, use secret_item_load_secret_sync() to load the secret gnome_keyring_item_set_info() use the appropriate setter methods on #SecretItem gnome_keyring_item_set_info_sync() use the appropriate setter methods on #SecretItem gnome_keyring_item_get_attributes() secret_item_get_attributes() gnome_keyring_item_get_attributes_sync() secret_item_get_attributes() gnome_keyring_item_set_attributes() secret_item_set_attributes() gnome_keyring_item_set_attributes_sync() secret_item_set_attributes_sync() #GnomeKeyringItemType replaced by the name of a #SecretSchema #GnomeKeyringItemInfo #SecretItem gnome_keyring_item_info_new() no equivalent gnome_keyring_item_info_copy() no equivalent gnome_keyring_item_info_free() g_object_unref() on the #SecretItem gnome_keyring_item_info_get_display_name() secret_item_get_label() gnome_keyring_item_info_set_display_name() secret_item_set_label() gnome_keyring_item_info_get_ctime() secret_item_get_created() gnome_keyring_item_info_get_mtime() secret_item_get_modified() gnome_keyring_item_info_get_type() secret_item_get_schema_name() gnome_keyring_item_info_set_type() secret_item_set_attributes() with appropriate schema gnome_keyring_item_info_get_secret() secret_item_get_secret() gnome_keyring_item_info_set_secret() secret_item_set_secret() and secret_item_set_secret_sync() %GNOME_KEYRING_ITEM_INFO_BASICS no equivalent, all basic item properties are loaded on #SecretItem automatically %GNOME_KEYRING_ITEM_INFO_SECRET use secret_item_load_secret() and secret_item_load_secret_sync() to load the secret for an item. gnome_keyring_item_info_set_display_name()

In libsecret keyrings are called 'collections'. This is the same lingo as the underlying Secret Service DBus API. Keyrings are no longer identified by simple keyring names. Normally applications just use the default keyrings and these are identified by the aliases %SECRET_COLLECTION_DEFAULT and %SECRET_COLLECTION_SESSION. It is also possible to identify collections by their DBus object paths. Replacements for related libgnome-keyring functions and types are described below: libgnome-keyringlibsecret gnome_keyring_create() secret_collection_create() gnome_keyring_create_sync() secret_collection_create_sync() gnome_keyring_delete() secret_collection_delete() gnome_keyring_delete_sync() secret_collection_delete_sync() gnome_keyring_change_password() no equivalent, use platform specific DBus APIs gnome_keyring_change_password_sync() no equivalent, use platform specific DBus APIs gnome_keyring_list_keyring_names() secret_service_load_collections() and secret_service_get_collections() gnome_keyring_list_keyring_names_sync() secret_service_load_collections_sync() and secret_service_get_collections() gnome_keyring_set_default_keyring() secret_service_set_alias() gnome_keyring_set_default_keyring_sync() secret_service_set_alias_sync() gnome_keyring_get_default_keyring() secret_collection_for_alias() with %SECRET_COLLECTION_DEFAULT gnome_keyring_get_default_keyring_sync() secret_collection_for_alias_sync() with %SECRET_COLLECTION_DEFAULT gnome_keyring_list_item_ids() secret_collection_load_items() and secret_collection_get_items() gnome_keyring_list_item_ids_sync() secret_collection_load_items_sync() and secret_collection_get_items() #GnomeKeyringInfo #SecretCollection and properties gnome_keyring_get_info() no equivalent gnome_keyring_get_info_sync() no equivalent gnome_keyring_set_info() no equivalent, use property setters on #SecretCollection gnome_keyring_set_info_sync() no equivalent, use property setters on #SecretCollection gnome_keyring_info_free() no equivalent gnome_keyring_info_copy() no equivalent gnome_keyring_info_set_lock_on_idle() no equivalent gnome_keyring_info_get_lock_on_idle() no equivalent gnome_keyring_info_set_lock_timeout() no equivalent gnome_keyring_info_get_lock_timeout() no equivalent gnome_keyring_info_get_mtime() secret_collection_get_modified() gnome_keyring_info_get_ctime() secret_collection_get_created() gnome_keyring_info_get_is_locked() secret_collection_get_locked()

In libsecret you can unlock items directly, and the result is (with gnome-keyring daemon) that the enclosing collection will be unlocked. It is no longer possible to pass a password to unlock keyrings. These are automatically prompted for. Replacements for related libgnome-keyring functions and types are described below: libgnome-keyringlibsecret gnome_keyring_unlock() secret_service_unlock() gnome_keyring_unlock_sync() secret_service_unlock_sync() gnome_keyring_lock() secret_service_lock() gnome_keyring_lock_sync() secret_service_lock_sync() gnome_keyring_lock_all() no equivalent, use platform specific DBus APIs gnome_keyring_lock_all_sync() no equivalent, use platform specific DBus APIs

libsecret no longer provides a full API for using non-pageable memory. Use the equivalent API in the Gcr library. You can request that passwords are returned in non-pageable memory by using the secret_password_lookup_nonpageable_sync() and secret_password_lookup_nonpageable_finish() functions. In addition the contents of #SecretValue items is stored in non-pageable memory, unless the system doesn't support this. Replacements for related libgnome-keyring functions and types are described below: libgnome-keyringlibsecret gnome_keyring_memory_alloc() no equivalent, use Gcr gnome_keyring_memory_free() secret_password_free(), although this only works on strings gnome_keyring_memory_is_secure() no equivalent, use Gcr gnome_keyring_memory_new() no equivalent, use Gcr gnome_keyring_memory_realloc() no equivalent, use Gcr gnome_keyring_memory_strdup() no equivalent, use #SecretValue which is ref-counted, or use Gcr gnome_keyring_memory_try_alloc() no equivalent, use Gcr gnome_keyring_memory_try_realloc() no equivalent, use Gcr gnome_keyring_free_password() secret_password_free()

libsecret uses standard the standard #GCancellable idiom to cancel operations. It is not necessary to check whether the keyring daemon is available before using it. It is started automatically. Errors are returned as standard #GError in the usual way. There are fewer errors that are worth handling in an intelligent way, exceptions are in the #SecretError enumeration. It is not recommended to display any #GError message returned by libsecret to the user. Most of the possible errors are DBus communication problems or similar. Replacements for related libgnome-keyring functions and types are described below: libgnome-keyringlibsecret gnome_keyring_cancel_request() g_cancellable_cancel() on a #GCancellable passed to the relevant operation gnome_keyring_is_available() no equivalent, the secret service is autostarted as necessary gnome_keyring_result_to_message() use the message in the #GError, although most failures are not appropriate for display to the user %GNOME_KEYRING_RESULT_OK no #GError returned %GNOME_KEYRING_RESULT_DENIED no longer used, item or collection is simply not unlocked %GNOME_KEYRING_RESULT_NO_KEYRING_DAEMON %G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND %GNOME_KEYRING_RESULT_ALREADY_UNLOCKED no error, success returned %GNOME_KEYRING_RESULT_NO_SUCH_KEYRING keyrings no longer have names, accessing an missing DBus object has usual failure %GNOME_KEYRING_RESULT_BAD_ARGUMENTS %G_DBUS_ERROR_INVALID_ARGS or precondition failure in libsecret, this is always a programmer error %GNOME_KEYRING_RESULT_IO_ERROR relevant DBus errors, or %SECRET_ERROR_PROTOCOL %GNOME_KEYRING_RESULT_CANCELLED %G_IO_ERROR_CANCELLED %GNOME_KEYRING_RESULT_KEYRING_ALREADY_EXISTS no error, simply returns already existing keyring %GNOME_KEYRING_RESULT_NO_MATCH on error, an empty list is returned gnome_keyring_string_list_free() no equivalent