API conversion: Libsecret Library Reference Manual

## API conversion

Here are some clues on how to migrate various libgnome-keyring API functions and their logical equivalents in libsecret.

## Item attributes

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:

Table 1.

libgnome-keyring | libsecret
--- | ---
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()`