mirror of
https://gitlab.gnome.org/GNOME/libsecret.git
synced 2024-12-22 12:48:51 +00:00
Add documentation for how to migrate from libgnome-keyring
This commit is contained in:
Stef Walter
parent
a646cd2b33
commit
35022289da
@ -69,12 +69,15 @@ HTML_IMAGES=
|
||||
|
||||
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
|
||||
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
|
||||
content_files=libsecret-examples.sgml
|
||||
content_files = \
|
||||
libsecret-examples.sgml \
|
||||
migrating-libgnome-keyring.xml
|
||||
|
||||
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
|
||||
# These files must be listed here *and* in content_files
|
||||
# e.g. expand_content_files=running.sgml
|
||||
expand_content_files=
|
||||
expand_content_files = \
|
||||
migrating-libgnome-keyring.xml
|
||||
|
||||
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
|
||||
# Only needed if you are using gtkdoc-scangobj to dynamically query widget
|
||||
@ -90,7 +93,9 @@ include $(top_srcdir)/gtk-doc.make
|
||||
|
||||
# Other files to distribute
|
||||
# e.g. EXTRA_DIST += version.xml.in
|
||||
# EXTRA_DIST +=
|
||||
EXTRA_DIST += \
|
||||
version.xml.in \
|
||||
migrating-libgnome-keyring.xml
|
||||
|
||||
# Files not to distribute
|
||||
# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
|
||||
|
||||
@ -33,6 +33,8 @@
|
||||
<xi:include href="xml/secret-paths.xml"/>
|
||||
</part>
|
||||
|
||||
<xi:include href="xml/migrating-libgnome-keyring.xml"/>
|
||||
|
||||
<xi:include href="xml/annotation-glossary.xml">
|
||||
<xi:fallback />
|
||||
</xi:include>
|
||||
|
||||
@ -131,6 +131,7 @@ secret_password_free
|
||||
<FILE>secret-schema</FILE>
|
||||
<INCLUDE>secret/secret.h</INCLUDE>
|
||||
SECRET_SCHEMA_NOTE
|
||||
SECRET_SCHEMA_COMPAT_NETWORK
|
||||
SecretSchema
|
||||
SecretSchemaFlags
|
||||
SecretSchemaAttribute
|
||||
@ -146,7 +147,6 @@ secret_schema_attribute_type_get_type
|
||||
secret_schema_flags_get_type
|
||||
SECRET_TYPE_SCHEMA_FLAGS
|
||||
SECRET_TYPE_SCHEMA_ATTRIBUTE_TYPE
|
||||
SECRET_SCHEMA_COMPAT_NETWORK
|
||||
</SECTION>
|
||||
|
||||
<SECTION>
|
||||
|
||||
839
docs/reference/libsecret/migrating-libgnome-keyring.xml
Normal file
839
docs/reference/libsecret/migrating-libgnome-keyring.xml
Normal file
@ -0,0 +1,839 @@
|
||||
<part id="migrating">
|
||||
<title>Migrating from libgnome-keyring</title>
|
||||
|
||||
<chapter id="migrating-introduction">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>There is a
|
||||
<link linkend="libsecret-Password-storage">simple password API for storing and retrieving passwords</link>
|
||||
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.</para>
|
||||
|
||||
<para>libsecret uses the
|
||||
<ulink url="http://standards.freedesktop.org/secret-service/">Secret Service DBus API</ulink>
|
||||
to communicate with gnome-keyring-daemon, and as such exposes features
|
||||
based on that DBus API.</para>
|
||||
|
||||
<para>libsecret has been designed to be threadsafe, and uses the 'GDBus'
|
||||
code in gio to accomplish this.</para>
|
||||
|
||||
<para>Keyrings are called 'collections' in libsecret.</para>
|
||||
|
||||
<para>See the relevant section for specifics about how to port the
|
||||
libgnome-keyring functions or symbols in your project.</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="migrating-api">
|
||||
<title>API conversion</title>
|
||||
<para>Here are some clues on how to migrate various libgnome-keyring
|
||||
API functions and their logical equivalents in libsecret.</para>
|
||||
|
||||
<section id="migrating-attributes">
|
||||
<title>Item attributes</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>All attributes in libsecret are stored as strings. Sets of attributes
|
||||
are represented by #GHashTable<!-- -->s and the keys and values of
|
||||
these hash tables are strings.</para>
|
||||
|
||||
<para>libsecret is far more <link linkend="migrating-schemas">focused on schemas</link>,
|
||||
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: <literal>org.gnome.MyProject.Password</literal>).
|
||||
This schema name is stored internally in the item attributes.</para>
|
||||
|
||||
<para>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 <literal>true</literal> and <literal>false</literal>.
|
||||
Integer values are stored in decimal, with a preceeding negative sign
|
||||
for negative integers. libsecret facilitates this using the
|
||||
secret_attributes_build() and secret_attributes_buildv() functions.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>Replacements for related libgnome-keyring functions and types
|
||||
are described below:
|
||||
<table><tgroup cols="2">
|
||||
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>#GnomeKeyringAttributeList</entry>
|
||||
<entry>a #GHashTable of string keys and values</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>#GnomeKeyringAttribute</entry>
|
||||
<entry>a key/value pair in a #GHashTable of strings</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>#GnomeKeyringAttributeType</entry>
|
||||
<entry>#SecretSchemaAttributeType</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_ATTRIBUTE_TYPE_STRING</entry>
|
||||
<entry>%SECRET_SCHEMA_ATTRIBUTE_STRING</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32</entry>
|
||||
<entry>%SECRET_SCHEMA_ATTRIBUTE_INTEGER</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_attribute_list_index()</entry>
|
||||
<entry>use g_hash_table_lookup() on the attributes hash table</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_attribute_get_string()</entry>
|
||||
<entry>use g_hash_table_lookup() on the attributes hash table</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_attribute_get_uint32()</entry>
|
||||
<entry>no equivalent, use g_hash_table_lookup()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_attribute_list_append_string()</entry>
|
||||
<entry>secret_attributes_build()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_attribute_list_append_uint32()</entry>
|
||||
<entry>secret_attributes_build()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_attribute_list_copy()</entry>
|
||||
<entry>g_hash_table_ref()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_attribute_list_free()</entry>
|
||||
<entry>g_hash_table_unref()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_attribute_list_index()</entry>
|
||||
<entry>no equivalent, use g_hash_table_lookup()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_attribute_list_new()</entry>
|
||||
<entry>secret_attributes_build()</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup></table></para>
|
||||
</section>
|
||||
|
||||
<section id="migrating-schemas">
|
||||
<title>Working with schemas</title>
|
||||
|
||||
<para>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: <literal>org.gnome.MyProject.Password</literal>).
|
||||
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.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>Replacements for related libgnome-keyring functions and types
|
||||
are described below:
|
||||
<table><tgroup cols="2">
|
||||
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>#GnomeKeyringPasswordSchema</entry>
|
||||
<entry>#SecretSchema</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>#GnomeKeyringPasswordSchemaAttribute</entry>
|
||||
<entry>#SecretSchemaAttribute</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_ITEM_APPLICATION_SECRET</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_ITEM_CHAINED_KEYRING_PASSWORD</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_ITEM_ENCRYPTION_KEY_PASSWORD</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_ITEM_PK_STORAGE</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_ITEM_GENERIC_SECRET</entry>
|
||||
<entry>no equivalent, define a specific schema with an appropriate dotted name</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_ITEM_NETWORK_PASSWORD</entry>
|
||||
<entry>the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_ITEM_NOTE</entry>
|
||||
<entry>the %SECRET_SCHEMA_NOTE schema</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_NETWORK_PASSWORD</entry>
|
||||
<entry>the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup></table></para>
|
||||
</section>
|
||||
|
||||
|
||||
<section id="migrating-storing">
|
||||
<title>Storing passwords and items</title>
|
||||
|
||||
<para>It's encouraged to use a #SecretSchema when storing items and
|
||||
passwords.</para>
|
||||
|
||||
<para>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().</para>
|
||||
|
||||
<para>Replacements for related libgnome-keyring functions and types
|
||||
are described below:
|
||||
<table><tgroup cols="2">
|
||||
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_DEFAULT</entry>
|
||||
<entry>%SECRET_COLLECTION_DEFAULT</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_SESSION</entry>
|
||||
<entry>%SECRET_COLLECTION_SESSION</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_store_password()</entry>
|
||||
<entry>secret_password_store()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_store_password_sync()</entry>
|
||||
<entry>secret_password_store_sync()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_set_network_password()</entry>
|
||||
<entry>secret_password_store() with %SECRET_SCHEMA_COMPAT_NETWORK
|
||||
although this is not recommended for new uses.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_set_network_password_sync()</entry>
|
||||
<entry>secret_password_store_sync() with %SECRET_SCHEMA_COMPAT_NETWORK
|
||||
although this is not recommended for new uses.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_create()</entry>
|
||||
<entry>secret_item_create(), although using secret_password_store()
|
||||
is simpler.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_create_sync()</entry>
|
||||
<entry>secret_item_create(), although using secret_password_store_sync()
|
||||
is simpler.</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup></table></para>
|
||||
</section>
|
||||
|
||||
<section id="migrating-searching">
|
||||
<title>Searching for passwords and items</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>Replacements for related libgnome-keyring functions and types
|
||||
are described below:
|
||||
<table><tgroup cols="2">
|
||||
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>gnome_keyring_find_password()</entry>
|
||||
<entry>secret_password_lookup()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_find_password_sync()</entry>
|
||||
<entry>secret_password_lookup_sync()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_find_items()</entry>
|
||||
<entry>secret_service_search(), with flags to fine tune behavior</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_find_itemsv()</entry>
|
||||
<entry>secret_service_search(), with flags to fine tune behavior</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_find_items_sync()</entry>
|
||||
<entry>secret_service_search_sync(), with flags to fine tune behavior</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_find_itemsv_sync()</entry>
|
||||
<entry>secret_service_search(), with flags to fine tune behavior</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>GnomeKeyringFound</entry>
|
||||
<entry>no equivalent, secret_service_search() returns a #GList of
|
||||
#SecretItem<!-- -->s, and other methods return passwords directly.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_found_copy()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_found_free()</entry>
|
||||
<entry>g_object_unref() on the each of the items returned from
|
||||
secret_service_search()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_found_list_free()</entry>
|
||||
<entry>g_list_free_full() used with g_object_unref() on the items returned from
|
||||
secret_service_search()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_find_network_password()</entry>
|
||||
<entry>secret_password_lookup() with %SECRET_SCHEMA_COMPAT_NETWORK,
|
||||
although this only returns one password and no attributes</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_find_network_password_sync()</entry>
|
||||
<entry>secret_password_lookup_sync() with %SECRET_SCHEMA_COMPAT_NETWORK,
|
||||
although this only returns one password and no attributes</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>#GnomeKeyringNetworkPasswordData</entry>
|
||||
<entry>no equivalent, secret_password_lookup() gets the password directly
|
||||
and no attributes</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_network_password_free()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_network_password_list_free()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup></table></para>
|
||||
</section>
|
||||
|
||||
<section id="migrating-removing">
|
||||
<title>Removing passwords and icons</title>
|
||||
|
||||
<para>Neither libgnome-keyring or libsecret allow deletion of locked
|
||||
items. libsecret tries to make it easier to delete all unlocked items
|
||||
matching certain attributes.</para>
|
||||
|
||||
<para>Replacements for related libgnome-keyring functions and types
|
||||
are described below:
|
||||
<table><tgroup cols="2">
|
||||
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>gnome_keyring_delete_password()</entry>
|
||||
<entry>secret_password_remove(), although we now try to delete
|
||||
all unlocked matching items</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_delete_password_sync()</entry>
|
||||
<entry>secret_password_remove_sync(), although we now try to delete
|
||||
all unlocked matching items</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_delete()</entry>
|
||||
<entry>secret_item_delete()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_delete_sync()</entry>
|
||||
<entry>secret_item_delete_sync()</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup></table></para>
|
||||
</section>
|
||||
|
||||
<section id="migrating-items">
|
||||
<title>Item management</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>Replacements for related libgnome-keyring functions and types
|
||||
are described below:
|
||||
<table><tgroup cols="2">
|
||||
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_create()</entry>
|
||||
<entry>secret_item_create(), although secret_password_store() may be simpler</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_create_sync()</entry>
|
||||
<entry>secret_item_create_sync(), although secret_password_store_sync() may be simpler</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_delete()</entry>
|
||||
<entry>secret_item_delete(), although secret_password_remove() may be simpler</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_delete_sync()</entry>
|
||||
<entry>secret_item_delete_sync(), although secret_password_remove_sync() may be simpler</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_get_info()</entry>
|
||||
<entry>properties are loaded on a #SecretItem automatically, use
|
||||
secret_item_load_secret() to load the secret</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_get_info_sync()</entry>
|
||||
<entry>properties are loaded on a #SecretItem automatically, use
|
||||
secret_item_load_secret_sync() to load the secret</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_get_info_full()</entry>
|
||||
<entry>properties are loaded on a #SecretItem automatically, use
|
||||
secret_item_load_secret() to load the secret</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_get_info_full_sync()</entry>
|
||||
<entry>properties are loaded on a #SecretItem automatically, use
|
||||
secret_item_load_secret_sync() to load the secret</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_set_info()</entry>
|
||||
<entry>use the appropriate setter methods on #SecretItem</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_set_info_sync()</entry>
|
||||
<entry>use the appropriate setter methods on #SecretItem</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_get_attributes()</entry>
|
||||
<entry>secret_item_get_attributes()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_get_attributes_sync()</entry>
|
||||
<entry>secret_item_get_attributes()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_set_attributes()</entry>
|
||||
<entry>secret_item_set_attributes()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_set_attributes_sync()</entry>
|
||||
<entry>secret_item_set_attributes_sync()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>#GnomeKeyringItemType</entry>
|
||||
<entry>replaced by the name of a #SecretSchema</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>#GnomeKeyringItemInfo</entry>
|
||||
<entry>#SecretItem</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_new()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_copy()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_free()</entry>
|
||||
<entry>g_object_unref() on the #SecretItem</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_get_display_name()</entry>
|
||||
<entry>secret_item_get_label()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_set_display_name()</entry>
|
||||
<entry>secret_item_set_label()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_get_ctime()</entry>
|
||||
<entry>secret_item_get_created()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_get_mtime()</entry>
|
||||
<entry>secret_item_get_modified()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_get_type()</entry>
|
||||
<entry>secret_item_get_schema_name()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_set_type()</entry>
|
||||
<entry>secret_item_set_attributes() with appropriate schema</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_get_secret()</entry>
|
||||
<entry>secret_item_get_secret()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_set_secret()</entry>
|
||||
<entry>secret_item_set_secret() and secret_item_set_secret_sync()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_ITEM_INFO_BASICS</entry>
|
||||
<entry>no equivalent, all basic item properties are loaded on #SecretItem
|
||||
automatically</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_ITEM_INFO_SECRET</entry>
|
||||
<entry>use secret_item_load_secret() and secret_item_load_secret_sync() to load
|
||||
the secret for an item.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_item_info_set_display_name()</entry>
|
||||
<entry></entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup></table></para>
|
||||
</section>
|
||||
|
||||
<section id="migrating-keyrings">
|
||||
<title>Keyring management</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>Replacements for related libgnome-keyring functions and types
|
||||
are described below:
|
||||
<table><tgroup cols="2">
|
||||
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>gnome_keyring_create()</entry>
|
||||
<entry>secret_collection_create()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_create_sync()</entry>
|
||||
<entry>secret_collection_create_sync()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_delete()</entry>
|
||||
<entry>secret_collection_delete()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_delete_sync()</entry>
|
||||
<entry>secret_collection_delete_sync()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_change_password()</entry>
|
||||
<entry>no equivalent, use platform specific DBus APIs</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_change_password_sync()</entry>
|
||||
<entry>no equivalent, use platform specific DBus APIs</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_list_keyring_names()</entry>
|
||||
<entry>secret_service_load_collections() and secret_service_get_collections()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_list_keyring_names_sync()</entry>
|
||||
<entry>secret_service_load_collections_sync() and secret_service_get_collections()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_set_default_keyring()</entry>
|
||||
<entry>secret_service_set_alias()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_set_default_keyring_sync()</entry>
|
||||
<entry>secret_service_set_alias_sync()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_get_default_keyring()</entry>
|
||||
<entry>secret_collection_for_alias() with %SECRET_COLLECTION_DEFAULT</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_get_default_keyring_sync()</entry>
|
||||
<entry>secret_collection_for_alias_sync() with %SECRET_COLLECTION_DEFAULT</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_list_item_ids()</entry>
|
||||
<entry>secret_collection_load_items() and secret_collection_get_items()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_list_item_ids_sync()</entry>
|
||||
<entry>secret_collection_load_items_sync() and secret_collection_get_items()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>#GnomeKeyringInfo</entry>
|
||||
<entry>#SecretCollection and properties</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_get_info()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_get_info_sync()</entry>
|
||||
<entry>no equivalent()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_set_info()</entry>
|
||||
<entry>no equivalent, use property setters on #SecretCollection</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_set_info_sync()</entry>
|
||||
<entry>no equivalent, use property setters on #SecretCollection</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_info_free()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_info_copy()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_info_set_lock_on_idle()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_info_get_lock_on_idle()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_info_set_lock_timeout()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_info_get_lock_timeout()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_info_get_mtime()</entry>
|
||||
<entry>secret_collection_get_modified()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_info_get_ctime()</entry>
|
||||
<entry>secret_collection_get_created()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_info_get_is_locked()</entry>
|
||||
<entry>secret_collection_get_locked()</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup></table></para>
|
||||
</section>
|
||||
|
||||
<section id="migrating-locking">
|
||||
<title>Locking and unlocking</title>
|
||||
|
||||
<para>In libsecret you can unlock items directly, and the result is
|
||||
(with gnome-keyring daemon) that the enclosing collection will be unlocked.</para>
|
||||
|
||||
<para>It is no longer possible to pass a password to unlock keyrings.
|
||||
These are automatically prompted for.</para>
|
||||
|
||||
<para>Replacements for related libgnome-keyring functions and types
|
||||
are described below:
|
||||
<table><tgroup cols="2">
|
||||
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>gnome_keyring_unlock()</entry>
|
||||
<entry>secret_service_unlock()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_unlock_sync()</entry>
|
||||
<entry>secret_service_unlock_sync()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_lock()</entry>
|
||||
<entry>secret_service_lock()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_lock_sync()</entry>
|
||||
<entry>secret_service_lock_sync()</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_lock_all()</entry>
|
||||
<entry>no equivalent, use platform specific DBus APIs</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_lock_all_sync()</entry>
|
||||
<entry>no equivalent, use platform specific DBus APIs</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup></table></para>
|
||||
</section>
|
||||
|
||||
<section id="migrating-memory">
|
||||
<title>Non-pageable memory</title>
|
||||
|
||||
<para>libsecret no longer provides a full API for using non-pageable
|
||||
memory. Use the <ulink url="http://developer.gnome.org/gcr/stable/gcr-Non-pageable-Memory.html">equivalent API in the Gcr library</ulink>.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>Replacements for related libgnome-keyring functions and types
|
||||
are described below:
|
||||
<table><tgroup cols="2">
|
||||
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>gnome_keyring_memory_alloc()</entry>
|
||||
<entry>no equivalent, use Gcr</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_memory_free()</entry>
|
||||
<entry>secret_password_free(), although this only works on strings</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_memory_is_secure()</entry>
|
||||
<entry>no equivalent, use Gcr</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_memory_new()</entry>
|
||||
<entry>no equivalent, use Gcr</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_memory_realloc()</entry>
|
||||
<entry>no equivalent, use Gcr</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_memory_strdup()</entry>
|
||||
<entry>no equivalent, use #SecretValue which is ref-counted, or use Gcr</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_memory_try_alloc()</entry>
|
||||
<entry>no equivalent, use Gcr</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_memory_try_realloc()</entry>
|
||||
<entry>no equivalent, use Gcr</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_free_password()</entry>
|
||||
<entry>secret_password_free()</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup></table></para>
|
||||
</section>
|
||||
|
||||
<section id="migrating-misc">
|
||||
<title>Errors and cancellation</title>
|
||||
|
||||
<para>libsecret uses standard the standard #GCancellable idiom
|
||||
to cancel operations.</para>
|
||||
|
||||
<para>It is not necessary to check whether the keyring daemon is
|
||||
available before using it. It is started automatically.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>Replacements for related libgnome-keyring functions and types
|
||||
are described below:
|
||||
<table><tgroup cols="2">
|
||||
<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>gnome_keyring_cancel_request()</entry>
|
||||
<entry>g_cancellable_cancel() on a #GCancellable passed to the relevant operation</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_is_available()</entry>
|
||||
<entry>no equivalent, the secret service is autostarted as necessary</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_result_to_message()</entry>
|
||||
<entry>use the message in the #GError, although most failures are not appropriate for display to the user</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_RESULT_OK</entry>
|
||||
<entry>no #GError returned</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_RESULT_DENIED</entry>
|
||||
<entry>no longer used, item or collection is simply not unlocked</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_RESULT_NO_KEYRING_DAEMON</entry>
|
||||
<entry>%G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_RESULT_ALREADY_UNLOCKED</entry>
|
||||
<entry>no error, success returned</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_RESULT_NO_SUCH_KEYRING</entry>
|
||||
<entry>keyrings no longer have names, accessing an missing DBus object has usual failure</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_RESULT_BAD_ARGUMENTS</entry>
|
||||
<entry>%G_DBUS_ERROR_INVALID_ARGS or precondition failure in libsecret, this is always
|
||||
a programmer error</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_RESULT_IO_ERROR</entry>
|
||||
<entry>relevant DBus errors, or %SECRET_ERROR_PROTOCOL</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_RESULT_CANCELLED</entry>
|
||||
<entry>%G_IO_ERROR_CANCELLED</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_RESULT_KEYRING_ALREADY_EXISTS</entry>
|
||||
<entry>no error, simply returns already existing keyring</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>%GNOME_KEYRING_RESULT_NO_MATCH</entry>
|
||||
<entry>on error, an empty list is returned</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>gnome_keyring_string_list_free()</entry>
|
||||
<entry>no equivalent</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup></table></para>
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
|
||||
</part>
|
||||
@ -78,6 +78,11 @@
|
||||
*
|
||||
* Attributes are stored as strings in the Secret Service, and the attribute
|
||||
* types simply define standard ways to store integer and boolean values as strings.
|
||||
* Attributes are represented in libsecret via a #GHashTable with string keys and
|
||||
* values. Even for values that defined as an integer or boolean in the schema,
|
||||
* the attribute values in the #GHashTable are strings. Boolean values are stored
|
||||
* as the strings 'true' and 'false'. Integer values are stored in decimal, with
|
||||
* a preceeding negative sign for negative integers.
|
||||
*
|
||||
* Schemas are handled entirely on the client side by this library. The name of the
|
||||
* schema is automatically stored as an attribute on the item.
|
||||
|
||||
@ -16,6 +16,14 @@
|
||||
|
||||
#include "secret-schema.h"
|
||||
|
||||
/**
|
||||
* SECRET_SCHEMA_NOTE:
|
||||
*
|
||||
* A predefined schema for personal passwords stored by the user in the
|
||||
* password manager. This schema has no attributes, and the items are not
|
||||
* meant to be used automatically by applications.
|
||||
*/
|
||||
|
||||
static const SecretSchema note_schema = {
|
||||
"org.gnome.keyring.Note",
|
||||
SECRET_SCHEMA_DONT_MATCH_NAME,
|
||||
@ -26,6 +34,32 @@ static const SecretSchema note_schema = {
|
||||
|
||||
const SecretSchema * SECRET_SCHEMA_NOTE = ¬e_schema;
|
||||
|
||||
/**
|
||||
* SECRET_SCHEMA_COMPAT_NETWORK:
|
||||
*
|
||||
* A predefined schema that is compatible with items stored via the
|
||||
* libgnome-keyring 'network password' functions. This is meant to be used by
|
||||
* applications migrating from libgnome-keyring which stored their secrets as
|
||||
* 'network passwords'. It is not recommended that new code use this schema.
|
||||
*
|
||||
* The following attributes exist in the schema:
|
||||
* <variablelist><title>Attributes:</title>
|
||||
* <varlistentry><term><literal>user</literal>:</term>
|
||||
* <listitem><para>The user name (string).</para></listitem></varlistentry>
|
||||
* <varlistentry><term><literal>domain</literal>:</term>
|
||||
* <listitem><para>The login domain or realm (string).</para></listitem></varlistentry>
|
||||
* <varlistentry><term><literal>object</literal>:</term>
|
||||
* <listitem><para>The object or path (string).</para></listitem></varlistentry>
|
||||
* <varlistentry><term><literal>protocol</literal>:</term>
|
||||
* <listitem><para>The protocol (a string like 'http').</para></listitem></varlistentry>
|
||||
* <varlistentry><term><literal>port</literal>:</term>
|
||||
* <listitem><para>The network port (integer).</para></listitem></varlistentry>
|
||||
* <varlistentry><term><literal>server</literal>:</term>
|
||||
* <listitem><para>The hostname or server (string).</para></listitem></varlistentry>
|
||||
* <varlistentry><term><literal>authtype</literal>:</term>
|
||||
* <listitem><para>The authentication type (string).</para></listitem></varlistentry>
|
||||
* </variablelist>
|
||||
*/
|
||||
|
||||
static const SecretSchema network_schema = {
|
||||
"org.gnome.keyring.NetworkPassword",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user