+
+ | libgnome-keyring | libsecret |
+
+
+ | GnomeKeyringAttributeList |
+ a [struct@GLib.HashTable] of string keys and values |
+
+
+ | GnomeKeyringAttribute |
+ a key/value pair in a [struct@GLib.HashTable] of strings |
+
+
+ | GnomeKeyringAttributeType |
+ [struct@Schema]AttributeType |
+
+
+ GNOME_KEYRING_ATTRIBUTE_TYPE_STRING |
+ SECRET_SCHEMA_ATTRIBUTE_STRING |
+
+
+ GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32 |
+ SECRET_SCHEMA_ATTRIBUTE_INTEGER |
+
+
+ gnome_keyring_attribute_list_index() |
+ use [func@GLib.HashTable.lookup] on the attributes hash table |
+
+
+ gnome_keyring_attribute_get_string() |
+ use [func@GLib.HashTable.lookup] on the attributes hash table |
+
+
+ gnome_keyring_attribute_get_uint32() |
+ no equivalent, use [func@GLib.HashTable.lookup] |
+
+
+ gnome_keyring_attribute_list_append_string() |
+ [func@attributes_build] |
+
+
+ gnome_keyring_attribute_list_append_uint32() |
+ [func@attributes_build] |
+
+
+ gnome_keyring_attribute_list_copy() |
+ [func@GLib.HashTable.ref] |
+
+
+ gnome_keyring_attribute_list_free() |
+ [func@GLib.HashTable.unref] |
+
+
+ gnome_keyring_attribute_list_index() |
+ no equivalent, use [func@GLib.HashTable.lookup] |
+
+
+ gnome_keyring_attribute_list_new() |
+ [func@attributes_build] |
+
+
+
+## Working with schemas
+
+libsecret is far more focused on schemas, and encourages users to
+define a [struct@Schema] 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-keyring | libsecret |
+
+
+ | GnomeKeyringPasswordSchema |
+ [struct@Schema] |
+
+
+ | GnomeKeyringPasswordSchemaAttribute |
+ [struct@Schema]Attribute |
+
+
+ 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 |
+
+
+
+## Storing passwords and items
+
+It's encouraged to use a [struct@Schema] 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 [func@Item.create].
+
+Replacements for related libgnome-keyring functions and types
+are described below:
+
+
+
+ | libgnome-keyring | libsecret |
+
+
+ GNOME_KEYRING_DEFAULT |
+ [const@COLLECTION_DEFAULT] |
+
+
+ GNOME_KEYRING_SESSION |
+ [const@COLLECTION_SESSION] |
+
+
+ gnome_keyring_store_password() |
+ [func@password_store] |
+
+
+ gnome_keyring_store_password_sync() |
+ [func@password_store_sync] |
+
+
+ gnome_keyring_set_network_password() |
+ [func@password_store] with SECRET_SCHEMA_COMPAT_NETWORK
+ although this is not recommended for new uses. |
+
+
+ gnome_keyring_set_network_password_sync() |
+ [func@password_store_sync] with SECRET_SCHEMA_COMPAT_NETWORK
+ although this is not recommended for new uses. |
+
+
+ gnome_keyring_item_create() |
+ [func@Item.create], although using [func@password_store]
+ is simpler. |
+
+
+ gnome_keyring_item_create_sync() |
+ [func@Item.create], although using [func@password_store_sync]
+ is simpler. |
+
+
+
+## Searching for passwords and items
+
+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-keyring | libsecret |
+
+
+ gnome_keyring_find_password() |
+ [func@password_lookup] |
+
+
+ gnome_keyring_find_password_sync() |
+ [func@password_lookup_sync] |
+
+
+ gnome_keyring_find_items() |
+ [method@Service.search], with flags to fine tune behavior |
+
+
+ gnome_keyring_find_itemsv() |
+ [method@Service.search], with flags to fine tune behavior |
+
+
+ gnome_keyring_find_items_sync() |
+ [method@Service.search_sync], with flags to fine tune behavior |
+
+
+ gnome_keyring_find_itemsv_sync() |
+ [method@Service.search], with flags to fine tune behavior |
+
+
+ | GnomeKeyringFound |
+ no equivalent, [method@Service.search] returns a [struct@GLib.List] of
+ [class@Item]s, and other methods return passwords directly. |
+
+
+ gnome_keyring_found_copy() |
+ no equivalent |
+
+
+ gnome_keyring_found_free() |
+ [method@GObject.Object.unref] on the each of the items returned from
+ [method@Service.search] |
+
+
+ gnome_keyring_found_list_free() |
+ [func@GLib.List.free_full] used with [method@GObject.Object.unref] on the items returned from
+ [method@Service.search] |
+
+
+ gnome_keyring_find_network_password() |
+ [func@password_lookup] with SECRET_SCHEMA_COMPAT_NETWORK,
+ although this only returns one password and no attributes |
+
+
+ gnome_keyring_find_network_password_sync() |
+ [func@password_lookup_sync] with SECRET_SCHEMA_COMPAT_NETWORK,
+ although this only returns one password and no attributes |
+
+
+ | GnomeKeyringNetworkPasswordData |
+ no equivalent, [func@password_lookup] gets the password directly
+ and no attributes |
+
+
+ gnome_keyring_network_password_free() |
+ no equivalent |
+
+
+ gnome_keyring_network_password_list_free() |
+ no equivalent |
+
+
+
+## Removing passwords and icons
+
+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-keyring | libsecret |
+
+
+ gnome_keyring_item_create() |
+ [func@Item.create], although [func@password_store] may be simpler |
+
+
+ gnome_keyring_item_create_sync() |
+ [func@Item.create_sync], although [func@password_store_sync] may be simpler |
+
+
+ gnome_keyring_item_delete() |
+ [method@Item.delete], although [func@password_clear] may be simpler |
+
+
+ gnome_keyring_item_delete_sync() |
+ [method@Item.delete_sync], although [func@password_clear_sync] may be simpler |
+
+
+ gnome_keyring_item_get_info() |
+ properties are loaded on a [class@Item] automatically, use
+ [method@Item.load_secret] to load the secret |
+
+
+ gnome_keyring_item_get_info_sync() |
+ properties are loaded on a [class@Item] automatically, use
+ [method@Item.load_secret_sync] to load the secret |
+
+
+ gnome_keyring_item_get_info_full() |
+ properties are loaded on a [class@Item] automatically, use
+ [method@Item.load_secret] to load the secret |
+
+
+ gnome_keyring_item_get_info_full_sync() |
+ properties are loaded on a [class@Item] automatically, use
+ [method@Item.load_secret_sync] to load the secret |
+
+
+ gnome_keyring_item_set_info() |
+ use the appropriate setter methods on [class@Item] |
+
+
+ gnome_keyring_item_set_info_sync() |
+ use the appropriate setter methods on [class@Item] |
+
+
+ gnome_keyring_item_get_attributes() |
+ [method@Item.get_attributes] |
+
+
+ gnome_keyring_item_get_attributes_sync() |
+ [method@Item.get_attributes] |
+
+
+ gnome_keyring_item_set_attributes() |
+ [method@Item.set_attributes] |
+
+
+ gnome_keyring_item_set_attributes_sync() |
+ [method@Item.set_attributes_sync] |
+
+
+ | GnomeKeyringItemType |
+ replaced by the name of a [struct@Schema] |
+
+
+ | GnomeKeyringItemInfo |
+ [class@Item] |
+
+
+ gnome_keyring_item_info_new() |
+ no equivalent |
+
+
+ gnome_keyring_item_info_copy() |
+ no equivalent |
+
+
+ gnome_keyring_item_info_free() |
+ [method@GObject.Object.unref] on the [class@Item] |
+
+
+ gnome_keyring_item_info_get_display_name() |
+ [method@Item.get_label] |
+
+
+ gnome_keyring_item_info_set_display_name() |
+ [method@Item.set_label] |
+
+
+ gnome_keyring_item_info_get_ctime() |
+ [method@Item.get_created] |
+
+
+ gnome_keyring_item_info_get_mtime() |
+ [method@Item.get_modified] |
+
+
+ gnome_keyring_item_info_get_type() |
+ [method@Item.get_schema_name] |
+
+
+ gnome_keyring_item_info_set_type() |
+ [method@Item.set_attributes] with appropriate schema |
+
+
+ gnome_keyring_item_info_get_secret() |
+ [method@Item.get_secret] |
+
+
+ gnome_keyring_item_info_set_secret() |
+ [method@Item.set_secret] and [method@Item.set_secret_sync] |
+
+
+ GNOME_KEYRING_ITEM_INFO_BASICS |
+ no equivalent, all basic item properties are loaded on [class@Item]
+ automatically |
+
+
+ GNOME_KEYRING_ITEM_INFO_SECRET |
+ use [method@Item.load_secret] and [method@Item.load_secret_sync] to load
+ the secret for an item. |
+
+
+ gnome_keyring_item_info_set_display_name() |
+ |
+
+
+
+## Keyring management
+
+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
+[const@COLLECTION_DEFAULT] and [const@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-keyring | libsecret |
+
+
+ gnome_keyring_create() |
+ [func@Collection.create] |
+
+
+ gnome_keyring_create_sync() |
+ [func@Collection.create_sync] |
+
+
+ gnome_keyring_delete() |
+ [method@Collection.delete] |
+
+
+ gnome_keyring_delete_sync() |
+ [method@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() |
+ [method@Service.load_collections] and [method@Service.get_collections] |
+
+
+ gnome_keyring_list_keyring_names_sync() |
+ [method@Service.load_collections_sync] and [method@Service.get_collections] |
+
+
+ gnome_keyring_set_default_keyring() |
+ [method@Service.set_alias] |
+
+
+ gnome_keyring_set_default_keyring_sync() |
+ [method@Service.set_alias_sync] |
+
+
+ gnome_keyring_get_default_keyring() |
+ [func@Collection.for_alias] with [const@COLLECTION_DEFAULT] |
+
+
+ gnome_keyring_get_default_keyring_sync() |
+ [func@Collection.for_alias_sync] with [const@COLLECTION_DEFAULT] |
+
+
+ gnome_keyring_list_item_ids() |
+ [method@Collection.load_items] and [method@Collection.get_items] |
+
+
+ gnome_keyring_list_item_ids_sync() |
+ [method@Collection.load_items_sync] and [method@Collection.get_items] |
+
+
+ | GnomeKeyringInfo |
+ [class@Collection] 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 [class@Collection] |
+
+
+ gnome_keyring_set_info_sync() |
+ no equivalent, use property setters on [class@Collection] |
+
+
+ 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() |
+ [method@Collection.get_modified] |
+
+
+ gnome_keyring_info_get_ctime() |
+ [method@Collection.get_created] |
+
+
+ gnome_keyring_info_get_is_locked() |
+ [method@Collection.get_locked] |
+
+
+
+## Locking and unlocking
+
+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-keyring | libsecret |
+
+
+ gnome_keyring_memory_alloc() |
+ no equivalent, use Gcr |
+
+
+ gnome_keyring_memory_free() |
+ [func@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 [struct@Value] 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() |
+ [func@password_free] |
+
+
+
+## Errors and cancellation
+
+libsecret uses standard the standard [class@Gio.Cancellable] 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 [struct@GLib.Error] 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 [struct@GLib.Error] 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-keyring | libsecret |
+
+
+ gnome_keyring_cancel_request() |
+ [method@Gio.Cancellable.cancel] on a [class@Gio.Cancellable] 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 [struct@GLib.Error], although most failures are not appropriate for display to the user |
+
+
+ GNOME_KEYRING_RESULT_OK |
+ no [struct@GLib.Error] 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 |
+
+
diff --git a/docs/reference/libsecret/migrating-libgnome-keyring.xml b/docs/reference/libsecret/migrating-libgnome-keyring.xml
deleted file mode 100644
index 7f727ec..0000000
--- a/docs/reference/libsecret/migrating-libgnome-keyring.xml
+++ /dev/null
@@ -1,839 +0,0 @@
-