diff options
28 files changed, 870 insertions, 18 deletions
@@ -1,12 +1,13 @@ *~ -*.o -*.la -*.lo -*.pyc +*.bak *.gcov *.gcno *.gcda *.gir +*.la +*.lo +*.o +*.pyc *.pc *.tar.gz *.typelib @@ -22,6 +23,7 @@ config.* depcomp install-sh INSTALL +gtk-doc.make libtool ltmain.sh Makefile @@ -29,6 +31,7 @@ Makefile.in Makefile.in.in missing stamp* +*.stamp .settings .project .cproject @@ -37,6 +40,21 @@ stamp* /build/m4 /build/valgrind-suppressions +/docs/reference/libsecret/version.xml +/docs/reference/libsecret/libsecret-decl-list.txt +/docs/reference/libsecret/libsecret-decl.txt +/docs/reference/libsecret/libsecret-scan.c +/docs/reference/libsecret/html +/docs/reference/libsecret/libsecret-undeclared.txt +/docs/reference/libsecret/libsecret-undocumented.txt +/docs/reference/libsecret/libsecret-unused.txt +/docs/reference/libsecret/libsecret.args +/docs/reference/libsecret/libsecret.hierarchy +/docs/reference/libsecret/libsecret.prerequisites +/docs/reference/libsecret/libsecret.signals +/docs/reference/libsecret/tmpl +/docs/reference/libsecret/xml + /po/POTFILES /po/libsecret.pot diff --git a/Makefile.am b/Makefile.am index bc3c3ab..92d5f00 100644 --- a/Makefile.am +++ b/Makefile.am @@ -3,7 +3,7 @@ include $(top_srcdir)/Makefile.decl ACLOCAL_AMFLAGS = -I build/m4 ${ACLOCAL_FLAGS} -SUBDIRS = build po egg library +SUBDIRS = build egg library po docs DISTCHECK_CONFIGURE_FLAGS = \ --enable-debug=yes \ @@ -91,6 +91,8 @@ $ACLOCAL $ACLOCAL_FLAGS || exit $? libtoolize --force || exit $? intltoolize --force --copy || exit $? +gtkdocize || exit $? + autoheader || exit $? $AUTOMAKE --add-missing || exit $? diff --git a/configure.ac b/configure.ac index e09b8ab..b4fec56 100644 --- a/configure.ac +++ b/configure.ac @@ -66,6 +66,8 @@ PKG_CHECK_MODULES(GLIB, LIBS="$LIBS $GLIB_LIBS" CFLAGS="$CFLAGS $GLIB_CFLAGS" +GTK_DOC_CHECK(1.9) + GOBJECT_INTROSPECTION_CHECK([1.29]) AC_PATH_PROG(GLIB_MKENUMS, glib-mkenums) @@ -225,6 +227,10 @@ AC_SUBST(SECRET_MINOR) AC_CONFIG_FILES([ Makefile build/Makefile + docs/Makefile + docs/reference/Makefile + docs/reference/libsecret/Makefile + docs/reference/libsecret/version.xml egg/Makefile egg/tests/Makefile po/Makefile.in diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 0000000..cac25f2 --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,2 @@ + +SUBDIRS = reference diff --git a/docs/reference/COPYING b/docs/reference/COPYING new file mode 100644 index 0000000..d5c1293 --- /dev/null +++ b/docs/reference/COPYING @@ -0,0 +1,30 @@ +This work may be reproduced and distributed in whole or in part, in +any medium, physical or electronic, so as long as this copyright +notice remains intact and unchanged on all copies. Commercial +redistribution is permitted and encouraged, but you may not +redistribute, in whole or in part, under terms more restrictive than +those under which you received it. If you redistribute a modified or +translated version of this work, you must also make the source code to +the modified or translated version available in electronic form +without charge. However, mere aggregation as part of a larger work +shall not count as a modification for this purpose. + +All code examples in this work are placed into the public domain, +and may be used, modified and redistributed without restriction. + +BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY REPAIR OR CORRECTION. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am new file mode 100644 index 0000000..3173a7f --- /dev/null +++ b/docs/reference/Makefile.am @@ -0,0 +1,2 @@ + +SUBDIRS = libsecret diff --git a/docs/reference/libsecret/Makefile.am b/docs/reference/libsecret/Makefile.am new file mode 100644 index 0000000..33bc1ce --- /dev/null +++ b/docs/reference/libsecret/Makefile.am @@ -0,0 +1,102 @@ +## Process this file with automake to produce Makefile.in + +# We require automake 1.6 at least. +AUTOMAKE_OPTIONS = 1.6 + +# This is a blank Makefile.am for using gtk-doc. +# Copy this to your project's API docs directory and modify the variables to +# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples +# of using the various options. + +# The name the module, e.g. 'glib'. +DOC_MODULE=libsecret + +# Uncomment for versioned docs and specify the version of the module, e.g. '2'. +DOC_MODULE_VERSION=@SECRET_MAJOR@ + +# The top-level SGML file. You can change this if you want to. +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml + +# The directory containing the source code. Relative to $(srcdir). +# gtk-doc will search all .c & .h files beneath here for inline comments +# documenting the functions and macros. +# e.g. DOC_SOURCE_DIR=../../../gtk +DOC_SOURCE_DIR=$(top_srcdir)/library + +# Extra options to pass to gtkdoc-scangobj. Not normally needed. +SCANGOBJ_OPTIONS= + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS=--deprecated-guards="SECRET_DISABLE_DEPRECATED" + +# Extra options to supply to gtkdoc-mkdb. +# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml +MKDB_OPTIONS=--sgml-mode --output-format=xml + +# Extra options to supply to gtkdoc-mktmpl +# e.g. MKTMPL_OPTIONS=--only-section-tmpl +MKTMPL_OPTIONS= + +# Extra options to supply to gtkdoc-mkhtml +MKHTML_OPTIONS= + +# Extra options to supply to gtkdoc-fixref. Not normally needed. +# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +FIXXREF_OPTIONS= + +# Used for dependencies. The docs will be rebuilt if any of these change. +# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h +# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c +HFILE_GLOB=$(top_srcdir)/library/*.h +CFILE_GLOB=$(top_srcdir)/library/*.c + +# Extra header to include when scanning, which are not under DOC_SOURCE_DIR +# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h +EXTRA_HFILES= + +# Header files to ignore when scanning. Use base file name, no paths +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h +IGNORE_HFILES= \ + mock-service.h \ + secret-dbus-generated.h \ + secret-private.h \ + $(NULL) + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +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= + +# 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= + +# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. +# Only needed if you are using gtkdoc-scangobj to dynamically query widget +# signals and properties. +# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +GTKDOC_CFLAGS= -I$(top_srcdir) -I$(top_builddir) $(GLIB_CFLAGS) -Wno-error +GTKDOC_LIBS= $(GLIB_LIBS) $(GOBJECT_LIBS) \ + $(top_builddir)/library/libsecret-@SECRET_MAJOR@.la + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/gtk-doc.make + +# Other files to distribute +# e.g. EXTRA_DIST += version.xml.in +# EXTRA_DIST += + +# Files not to distribute +# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types +# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt +DISTCLEANFILES = tmpl/secret-unused.sgml + +# Comment this out if you want your docs-status tested during 'make check' +#TESTS_ENVIRONMENT = cd $(srcsrc) +#TESTS = $(GTKDOC_CHECK) diff --git a/docs/reference/libsecret/libsecret-docs.sgml b/docs/reference/libsecret/libsecret-docs.sgml new file mode 100644 index 0000000..cd8a762 --- /dev/null +++ b/docs/reference/libsecret/libsecret-docs.sgml @@ -0,0 +1,34 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +<!ENTITY version SYSTEM "version.xml"> +]> +<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> + <bookinfo> + <title>Libsecret Library Reference Manual</title> + <releaseinfo> + for libsecret &version;. + An online version of this documentation can be found at + <ulink role="online-location" url="http://developer.gnome.org/libsecret/stable/">http://developer.gnome.org/libsecret/stable/</ulink>. + </releaseinfo> + </bookinfo> + + <part id="simple"> + <title>Simple API</title> + <xi:include href="xml/secret-password.xml"/> + </part> + + <part id="complete"> + <title>Complete API</title> + <xi:include href="xml/secret-service.xml"/> + <xi:include href="xml/secret-collection.xml"/> + <xi:include href="xml/secret-item.xml"/> + <xi:include href="xml/secret-value.xml"/> + <xi:include href="xml/secret-prompt.xml"/> + <xi:include href="xml/secret-error.xml"/> + </part> + + <xi:include href="xml/annotation-glossary.xml"> + <xi:fallback /> + </xi:include> +</book> diff --git a/docs/reference/libsecret/libsecret-overrides.txt b/docs/reference/libsecret/libsecret-overrides.txt new file mode 100644 index 0000000..13f485f --- /dev/null +++ b/docs/reference/libsecret/libsecret-overrides.txt @@ -0,0 +1,2 @@ +# These are manually-edited to override or add declarations to those scanned +# from the header files. diff --git a/docs/reference/libsecret/libsecret-sections.txt b/docs/reference/libsecret/libsecret-sections.txt new file mode 100644 index 0000000..ee86fcd --- /dev/null +++ b/docs/reference/libsecret/libsecret-sections.txt @@ -0,0 +1,252 @@ +<SECTION> +<FILE>secret-collection</FILE> +SecretCollection +SecretCollectionClass +secret_collection_new +secret_collection_new_finish +secret_collection_new_sync +secret_collection_create +secret_collection_create_finish +secret_collection_create_sync +secret_collection_delete +secret_collection_delete_finish +secret_collection_delete_sync +secret_collection_get_created +secret_collection_get_items +secret_collection_get_label +secret_collection_set_label +secret_collection_set_label_finish +secret_collection_set_label_sync +secret_collection_get_locked +secret_collection_get_modified +secret_collection_refresh +<SUBSECTION Standard> +SECRET_COLLECTION +SECRET_COLLECTION_CLASS +SECRET_COLLECTION_GET_CLASS +SECRET_IS_COLLECTION +SECRET_IS_COLLECTION_CLASS +SECRET_TYPE_COLLECTION +SecretCollectionPrivate +secret_collection_get_type +</SECTION> + +<SECTION> +<FILE>secret-item</FILE> +SecretItem +SecretItemClass +secret_item_new +secret_item_new_finish +secret_item_new_sync +secret_item_create +secret_item_create_finish +secret_item_create_sync +secret_item_delete +secret_item_delete_finish +secret_item_delete_sync +secret_item_get_attributes +secret_item_set_attributes +secret_item_set_attributes_finish +secret_item_set_attributes_sync +secret_item_get_created +secret_item_get_label +secret_item_set_label +secret_item_set_label_finish +secret_item_set_label_sync +secret_item_get_locked +secret_item_get_modified +secret_item_get_schema +secret_item_get_secret +secret_item_get_secret_finish +secret_item_get_secret_sync +secret_item_set_secret +secret_item_set_secret_finish +secret_item_set_secret_sync +secret_item_refresh +<SUBSECTION Standard> +SECRET_IS_ITEM +SECRET_IS_ITEM_CLASS +SECRET_ITEM +SECRET_ITEM_CLASS +SECRET_ITEM_GET_CLASS +SECRET_TYPE_ITEM +SecretItemPrivate +secret_item_get_type +</SECTION> + +<SECTION> +<FILE>secret-error</FILE> +SECRET_ERROR +SecretError +<SUBSECTION Standard> +SECRET_TYPE_ERROR +secret_error_get_quark +secret_error_get_type +</SECTION> + +<SECTION> +<FILE>secret-password</FILE> +SecretSchema +SecretSchemaType +secret_password_store +secret_password_storev +secret_password_store_finish +secret_password_store_sync +secret_password_storev_sync +secret_password_lookup +secret_password_lookupv +secret_password_lookup_finish +secret_password_lookup_sync +secret_password_lookupv_sync +secret_password_remove +secret_password_removev +secret_password_remove_finish +secret_password_remove_sync +secret_password_removev_sync +secret_password_free +<SUBSECTION Standard> +SECRET_TYPE_SCHEMA_TYPE +secret_schema_type_get_type +</SECTION> + +<SECTION> +<FILE>secret-prompt</FILE> +SecretPrompt +SecretPromptClass +secret_prompt_get_result_value +secret_prompt_perform +secret_prompt_perform_finish +secret_prompt_perform_sync +secret_prompt_run +<SUBSECTION Standard> +SECRET_IS_PROMPT +SECRET_IS_PROMPT_CLASS +SECRET_PROMPT +SECRET_PROMPT_CLASS +SECRET_PROMPT_GET_CLASS +SECRET_TYPE_PROMPT +SecretPromptPrivate +secret_prompt_get_type +</SECTION> + +<SECTION> +<FILE>secret-service</FILE> +SecretService +SecretServiceClass +SecretServiceFlags +secret_service_get +secret_service_get_sync +secret_service_get_finish +secret_service_new +secret_service_new_finish +secret_service_new_sync +secret_service_get_collections +secret_service_get_flags +secret_service_get_session_algorithms +secret_service_get_session_path +secret_service_ensure_session +secret_service_ensure_session_finish +secret_service_ensure_session_sync +secret_service_ensure_collections +secret_service_ensure_collections_finish +secret_service_ensure_collections_sync +secret_service_search +secret_service_search_finish +secret_service_search_sync +secret_service_search_for_paths +secret_service_search_for_paths_finish +secret_service_search_for_paths_sync +secret_service_get_secrets +secret_service_get_secrets_finish +secret_service_get_secrets_sync +secret_service_get_secrets_for_paths +secret_service_get_secrets_for_paths_finish +secret_service_get_secrets_for_paths_sync +secret_service_get_secret_for_path +secret_service_get_secret_for_path_finish +secret_service_get_secret_for_path_sync +secret_service_lock +secret_service_lock_finish +secret_service_lock_sync +secret_service_lock_paths +secret_service_lock_paths_finish +secret_service_lock_paths_sync +secret_service_unlock +secret_service_unlock_finish +secret_service_unlock_sync +secret_service_unlock_paths +secret_service_unlock_paths_finish +secret_service_unlock_paths_sync +secret_service_store +secret_service_storev +secret_service_store_finish +secret_service_store_sync +secret_service_storev_sync +secret_service_lookup +secret_service_lookupv +secret_service_lookup_finish +secret_service_lookup_sync +secret_service_lookupv_sync +secret_service_remove +secret_service_removev +secret_service_remove_finish +secret_service_remove_sync +secret_service_removev_sync +secret_service_prompt +secret_service_prompt_finish +secret_service_prompt_sync +secret_service_create_collection_path +secret_service_create_collection_path_finish +secret_service_create_collection_path_sync +secret_service_create_item_path +secret_service_create_item_path_finish +secret_service_create_item_path_sync +secret_service_delete_path +secret_service_delete_path_finish +secret_service_delete_path_sync +<SUBSECTION Standard> +SECRET_IS_SERVICE +SECRET_IS_SERVICE_CLASS +SECRET_SERVICE +SECRET_SERVICE_CLASS +SECRET_SERVICE_GET_CLASS +SECRET_TYPE_SERVICE +SECRET_TYPE_SERVICE_FLAGS +SecretServicePrivate +secret_service_flags_get_type +secret_service_get_type +</SECTION> + +<SECTION> +<FILE>secret-value</FILE> +SecretValue +secret_value_new +secret_value_new_full +secret_value_get +secret_value_get_content_type +secret_value_ref +secret_value_unref +<SUBSECTION Standard> +SECRET_TYPE_VALUE +secret_value_get_type +</SECTION> + +<SECTION> +<FILE>SecretGenService</FILE> +</SECTION> + +<SECTION> +<FILE>SecretGenCollection</FILE> +</SECTION> + +<SECTION> +<FILE>SecretGenItem</FILE> +</SECTION> + +<SECTION> +<FILE>SecretGenSession</FILE> +</SECTION> + +<SECTION> +<FILE>SecretGenPrompt</FILE> +</SECTION> diff --git a/docs/reference/libsecret/libsecret.interfaces b/docs/reference/libsecret/libsecret.interfaces new file mode 100644 index 0000000..ac03c45 --- /dev/null +++ b/docs/reference/libsecret/libsecret.interfaces @@ -0,0 +1,6 @@ +GDBusProxy GDBusInterface GInitable GAsyncInitable +SecretCollection GDBusInterface GInitable GAsyncInitable +SecretItem GDBusInterface GInitable GAsyncInitable +SecretPrompt GDBusInterface GInitable GAsyncInitable +SecretService GDBusInterface GInitable GAsyncInitable +GDBusConnection GInitable GAsyncInitable diff --git a/docs/reference/libsecret/libsecret.types b/docs/reference/libsecret/libsecret.types new file mode 100644 index 0000000..f9bfa7a --- /dev/null +++ b/docs/reference/libsecret/libsecret.types @@ -0,0 +1,7 @@ +secret_collection_get_type +secret_error_get_type +secret_item_get_type +secret_prompt_get_type +secret_value_get_type +secret_service_flags_get_type +secret_service_get_type
\ No newline at end of file diff --git a/docs/reference/libsecret/version.xml.in b/docs/reference/libsecret/version.xml.in new file mode 100644 index 0000000..27323da --- /dev/null +++ b/docs/reference/libsecret/version.xml.in @@ -0,0 +1 @@ +@VERSION@
\ No newline at end of file diff --git a/library/Makefile.am b/library/Makefile.am index 3bccea6..952daa5 100644 --- a/library/Makefile.am +++ b/library/Makefile.am @@ -79,7 +79,7 @@ secret-dbus-generated.c: $(DBUS_XML_DEFINITIONS) Makefile.am $(AM_V_GEN) gdbus-codegen --interface-prefix org.freedesktop.Secret. \ --generate-c-code secret-dbus-generated --c-namespace SecretGen \ $(DBUS_XML_DEFINITIONS) - $(AM_V_GEN) sed -i -e 's/secret_gen_/_secret_gen_/g' secret-dbus-generated.[ch] + $(AM_V_GEN) sed -i -e 's/secret_gen_/_secret_gen_/g' -e 's/type-/type/g' secret-dbus-generated.[ch] $(AM_V_GEN) sed -i -e '1i #define GLIB_DISABLE_DEPRECATION_WARNINGS' secret-dbus-generated.c secret-dbus-generated.h: secret-dbus-generated.c diff --git a/library/secret-collection.c b/library/secret-collection.c index ee7ac74..dbebc25 100644 --- a/library/secret-collection.c +++ b/library/secret-collection.c @@ -21,6 +21,35 @@ #include <glib/gi18n-lib.h> +/** + * SECTION:secret-collection + * @title: SecretCollection + * @short_description: A collection of secret items + * + * #SecretCollection represents a collection of secret items stored in the + * Secret Service. + * + * A collection can be in a locked or unlocked state. Use secret_service_lock() + * or secret_service_unlock() to lock or unlock the collection. + * + * Use the SecretCollection::items property or secret_service_get_items() to + * lookup the items in the collection. There may not be any items exposed when + * the collection is locked. + */ + +/** + * SecretCollection: + * + * A proxy object representing a collection of secrets in the Secret Service. + */ + +/** + * SecretCollectionClass: + * @parent_class: the parent class + * + * The class for #SecretCollection. + */ + enum { PROP_0, PROP_SERVICE, @@ -412,26 +441,67 @@ secret_collection_class_init (SecretCollectionClass *klass) proxy_class->g_properties_changed = secret_collection_properties_changed; + /** + * SecretCollection:service: + * + * The #SecretService object that this collection is associated with and + * uses to interact with the actual DBus Secret Service. + */ g_object_class_install_property (gobject_class, PROP_SERVICE, g_param_spec_object ("service", "Service", "Secret Service", SECRET_TYPE_SERVICE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + /** + * SecretCollection:items: + * + * A list of #SecretItem objects representing the items that are in + * this collection. This list will be empty if the collection is locked. + */ g_object_class_install_property (gobject_class, PROP_ITEMS, g_param_spec_boxed ("items", "Items", "Items in collection", _secret_list_get_type (), G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); + /** + * SecretCollection:label: + * + * The human readable label for the collection. + * + * Setting this property will result in the label of the collection being + * set asynchronously. To properly track the changing of the label use the + * secret_collection_set_label() function. + */ g_object_class_install_property (gobject_class, PROP_LABEL, g_param_spec_string ("label", "Label", "Item label", NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * SecretCollection:locked: + * + * Whether the collection is locked or not. + * + * To lock or unlock a collection use the secret_service_lock() or + * secret_service_unlock() functions. + */ g_object_class_install_property (gobject_class, PROP_LOCKED, g_param_spec_boolean ("locked", "Locked", "Item locked", TRUE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); + /** + * SecretCollection:created: + * + * The date and time (in seconds since the UNIX epoch) that this + * collection was created. + */ g_object_class_install_property (gobject_class, PROP_CREATED, g_param_spec_uint64 ("created", "Created", "Item creation date", 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * SecretCollection:modified: + * + * The date and time (in seconds since the UNIX epoch) that this + * collection was last modified. + */ g_object_class_install_property (gobject_class, PROP_MODIFIED, g_param_spec_uint64 ("modified", "Modified", "Item modified date", 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); @@ -1152,6 +1222,9 @@ secret_collection_set_label_sync (SecretCollection *self, * * Get whether the collection is locked or not. * + * Use secret_service_lock() or secret_service_unlock() to lock or unlock the + * collection. + * * Returns: whether the collection is locked or not */ gboolean diff --git a/library/secret-collection.h b/library/secret-collection.h index 8e60d22..34426e3 100644 --- a/library/secret-collection.h +++ b/library/secret-collection.h @@ -35,11 +35,15 @@ typedef struct _SecretCollectionPrivate SecretCollectionPrivate; struct _SecretCollection { GDBusProxy parent; + + /*< private >*/ SecretCollectionPrivate *pv; }; struct _SecretCollectionClass { GDBusProxyClass parent_class; + + /*< private >*/ gpointer padding[8]; }; diff --git a/library/secret-item.c b/library/secret-item.c index 75c493e..ee4fa11 100644 --- a/library/secret-item.c +++ b/library/secret-item.c @@ -22,6 +22,44 @@ #include <glib/gi18n-lib.h> +/** + * SECTION:secret-item + * @title: SecretItem + * @short_description: A secret item + * + * #SecretItem represents a secret item stored in the Secret Service. + * + * Each item has a value, represented by a #SecretValue, which can be + * retrieved by secret_service_get_secret() or set by secret_service_set_secret(). + * The item is only available when the item is not locked. + * + * Items can be locked or unlocked using the secret_service_lock() or + * secret_service_unlock() functions. The Secret Service may not be able to + * unlock individual items, and may unlock an entire collection when a single + * item is unlocked. + * + * Each item has a set of attributes, which are used to locate the item later. + * These are not stored or transferred in a secure manner. Each attribute has + * a string name and a string value. Use secret_service_search() to search for + * items based on their attributes, and secret_item_set_attributes to change + * the attributes associated with an item. + * + * Items can be created with secret_item_create() or secret_service_store(). + */ + +/** + * SecretItem: + * + * A proxy object representing a secret item in the Secret Service. + */ + +/** + * SecretItemClass: + * @parent_class: the parent class + * + * The class for #SecretItem. + */ + enum { PROP_0, PROP_SERVICE, @@ -240,30 +278,81 @@ secret_item_class_init (SecretItemClass *klass) proxy_class->g_properties_changed = secret_item_properties_changed; + /** + * SecretItem:service: + * + * The #SecretService object that this item is associated with and + * uses to interact with the actual DBus Secret Service. + */ g_object_class_install_property (gobject_class, PROP_SERVICE, g_param_spec_object ("service", "Service", "Secret Service", SECRET_TYPE_SERVICE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + /** + * SecretItem:attributes: + * + * The attributes set on this item. Attributes are used to locate an + * item. They are not guaranteed to be stored or transferred securely. + * + * The schema describes which attributes should be present and their types. + */ g_object_class_install_property (gobject_class, PROP_ATTRIBUTES, g_param_spec_boxed ("attributes", "Attributes", "Item attributes", G_TYPE_HASH_TABLE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * SecretItem:label: + * + * The human readable label for the item. + * + * Setting this property will result in the label of the item being + * set asynchronously. To properly track the changing of the label use the + * secret_item_set_label() function. + */ g_object_class_install_property (gobject_class, PROP_LABEL, g_param_spec_string ("label", "Label", "Item label", NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * SecretItem:schema: + * + * The schema for this item. This is a dotted string that describes + * which attributes should be present and the types of values on + * those attributes. + */ g_object_class_install_property (gobject_class, PROP_SCHEMA, g_param_spec_string ("schema", "Schema", "Item schema", NULL, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); + /** + * SecretItem:locked: + * + * Whether the item is locked or not. An item may not be independently + * lockable separate from other items in its collection. + * + * To lock or unlock a item use the secret_service_lock() or + * secret_service_unlock() functions. + */ g_object_class_install_property (gobject_class, PROP_LOCKED, g_param_spec_boolean ("locked", "Locked", "Item locked", TRUE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); + /** + * SecretItem:created: + * + * The date and time (in seconds since the UNIX epoch) that this + * item was created. + */ g_object_class_install_property (gobject_class, PROP_CREATED, g_param_spec_uint64 ("created", "Created", "Item creation date", 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * SecretItem:modified: + * + * The date and time (in seconds since the UNIX epoch) that this + * item was last modified. + */ g_object_class_install_property (gobject_class, PROP_MODIFIED, g_param_spec_uint64 ("modified", "Modified", "Item modified date", 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); @@ -590,6 +679,7 @@ item_properties_new (const gchar *schema_name, * @attributes: attributes for the new item * @value: secret value for the new item * @replace: whether to replace an existing item with the same attributes + * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to pass to the callback * diff --git a/library/secret-item.h b/library/secret-item.h index 9c4a117..645ab5c 100644 --- a/library/secret-item.h +++ b/library/secret-item.h @@ -37,11 +37,15 @@ typedef struct _SecretItemPrivate SecretItemPrivate; struct _SecretItem { GDBusProxy parent_instance; + + /*< private >*/ SecretItemPrivate *pv; }; struct _SecretItemClass { GDBusProxyClass parent_class; + + /*< private >*/ gpointer padding[4]; }; diff --git a/library/secret-methods.c b/library/secret-methods.c index 25fd776..1f057e3 100644 --- a/library/secret-methods.c +++ b/library/secret-methods.c @@ -758,7 +758,7 @@ secret_service_get_secrets_for_paths (SecretService *self, * Items that are locked will not be included the results. * * Returns: (transfer full): a newly allocated hash table of item_path keys to - * #GSecretValue values. + * #SecretValue values. */ GHashTable * secret_service_get_secrets_for_paths_finish (SecretService *self, @@ -796,7 +796,7 @@ secret_service_get_secrets_for_paths_finish (SecretService *self, * Items that are locked will not be included the results. * * Returns: (transfer full): a newly allocated hash table of item_path keys to - * #GSecretValue values. + * #SecretValue values. */ GHashTable * secret_service_get_secrets_for_paths_sync (SecretService *self, @@ -894,8 +894,8 @@ secret_service_get_secrets (SecretService *self, * * Items that are locked will not be included the results. * - * Returns: (transfer full): a newly allocated hash table of #GSecretItem keys - * to #GSecretValue values. + * Returns: (transfer full): a newly allocated hash table of #SecretItem keys + * to #SecretValue values. */ GHashTable * secret_service_get_secrets_finish (SecretService *self, @@ -953,8 +953,8 @@ secret_service_get_secrets_finish (SecretService *self, * * Items that are locked will not be included the results. * - * Returns: (transfer full): a newly allocated hash table of #GSecretItem keys - * to #GSecretValue values. + * Returns: (transfer full): a newly allocated hash table of #SecretItem keys + * to #SecretValue values. */ GHashTable * secret_service_get_secrets_sync (SecretService *self, diff --git a/library/secret-password.c b/library/secret-password.c index 48dfdc0..1c3edf2 100644 --- a/library/secret-password.c +++ b/library/secret-password.c @@ -18,6 +18,60 @@ #include <egg/egg-secure-memory.h> +/** + * SECTION:secret-password + * @title: Password storage + * @short_description: Simple password storage and lookup + * + * This is a simple API for storing passwords and retrieving passwords in the + * Secret Service. + * + * Each password is associated with a set of attributes. Attribute values can + * be either strings, integers or booleans. + * + * The names and types of allowed attributes for a given password are defined + * with a schema. Certain schemas are predefined. Additional schemas can be + * defined via the %SecretSchema structure. + * + * Each of the functions accept a variable list of attributes names and their + * values. Include a %NULL to terminate the list of attributes. + */ + +/** + * SecretSchema: + * @schema_name: the dotted name of the schema + * @attributes: the attribute names and types of those attributes + * + * Represents a set of attributes that are stored with an item. These schemas + * are used for interoperability between various services storing the same types + * of items. + * + * Each schema has a name like "org.gnome.keyring.NetworkPassword", and defines + * a set of attributes, and types (string, integer, boolean) for those attributes. + * + * 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. + */ + +/** + * SecretSchemaAttribute: + * @name: name of the attribute + * @type: the type of the attribute + * + * An attribute in a #SecretSchema. + */ + +/** + * SecretSchemaType: + * @SECRET_ATTRIBUTE_BOOLEAN: a boolean attribute, stored as 'true' or 'false' + * @SECRET_ATTRIBUTE_INTEGER: an integer attribute, stored as a decimal + * @SECRET_ATTRIBUTE_STRING: a utf-8 string attribute + * + * The type of an attribute in a #SecretSchema. 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. + */ + typedef struct { const SecretSchema *schema; GHashTable *attributes; diff --git a/library/secret-prompt.c b/library/secret-prompt.c index d33f6f4..5cb4ee3 100644 --- a/library/secret-prompt.c +++ b/library/secret-prompt.c @@ -19,7 +19,37 @@ #include <glib.h> #include <glib/gi18n-lib.h> -#include <gcrypt.h> +/** + * SECTION:secret-prompt + * @title: SecretPrompt + * @short_description: a prompt in the Service + * + * A #SecretPrompt represents a prompt in the Secret Service. + * + * Certain actions on the Secret Service require user prompting to complete, + * such as creating a collection, or unlocking a collection. When such a prompt + * is necessary, then a #SecretPrompt object is created by this library, and + * passed to the secret_service_prompt_async() method. In this way it is handled + * automatically. + * + * In order to customize prompt handling, override the + * SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish + * virtual methods of the #SecretService class. + */ + +/** + * SecretPrompt: + * + * A proxy object representing a prompt that the Secret Service will display + * to the user. + */ + +/** + * SecretPromptClass: + * @parent_class: the parent class + * + * The class for #SecretPrompt. + */ typedef struct _SecretPromptPrivate { /* Locked by mutex */ diff --git a/library/secret-prompt.h b/library/secret-prompt.h index 2894ca9..5817378 100644 --- a/library/secret-prompt.h +++ b/library/secret-prompt.h @@ -35,11 +35,15 @@ typedef struct _SecretPromptPrivate SecretPromptPrivate; struct _SecretPrompt { GDBusProxy parent_instance; + + /*< private >*/ SecretPromptPrivate *pv; }; struct _SecretPromptClass { GDBusProxyClass parent_class; + + /*< private >*/ gpointer padding[8]; }; diff --git a/library/secret-service.c b/library/secret-service.c index f486c05..04fd47d 100644 --- a/library/secret-service.c +++ b/library/secret-service.c @@ -24,6 +24,79 @@ #include "egg/egg-secure-memory.h" +/** + * SECTION:secret-service + * @title: SecretService + * @short_description: the Secret Service + * + * A #SecretService object represents the Secret Service implementation which + * runs as a DBus service. + * + * Normally a single #SecretService object can be shared between multiple + * callers. The secret_service_get() method is used to access this #SecretService + * object. If a new independent #SecretService object is required, use + * secret_service_new(). + * + * In order to securely transfer secrets to the Sercret Service, an session + * is established. This session can be established while initializing a + * #SecretService object by passing the %SECRET_SERVICE_OPEN_SESSION flag + * to the secret_service_get() or secret_service_new() functions. In order to + * establish a session on an already existing #SecretService, use the + * secret_service_ensure_session() function. + * + * To search for items, use the secret_service_search() method. + * + * Multiple collections can exist in the Secret Service, each of which contains + * secret items. In order to instantiate #SecretCollection objects which + * represent those collections while initializing a #SecretService then pass + * the %SECRET_SERVICE_LOAD_COLLECTIONS flag to the secret_service_get() or + * secret_service_new() functions. In order to establish a session on an already + * existing #SecretService, use the secret_service_ensure_collections() function. + * To access the list of collections use secret_service_get_collections(). + * + * Certain actions on the Secret Service require user prompting to complete, + * such as creating a collection, or unlocking a collection. When such a prompt + * is necessary, then a #SecretPrompt object is created by this library, and + * passed to the secret_service_prompt_async() method. In this way it is handled + * automatically. + * + * In order to customize prompt handling, override the + * SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish + * virtual methods of the #SecretService class. + */ + +/** + * SecretService: + * + * A proxy object representing the Secret Service. + */ + +/** + * SecretServiceClass: + * @parent_class: the parent class + * @collection_gtype: the #GType of the #SecretCollection objects instantiated + * by the #SecretService proxy + * @item_gtype: the #GType of the #SecretItem objects instantiated by the + * #SecretService proxy + * @prompt_async: called to perform asynchronous prompting when necessary + * @prompt_finish: called to complete an asynchronous prompt operation + * @prompt_sync: called to perform synchronous prompting when necessary + * + * The class for #SecretService. + */ + +/** + * SecretServiceFlags: + * @SECRET_SERVICE_NONE: no flags for initializing the #SecretService + * @SECRET_SERVICE_OPEN_SESSION: establish a session for transfer of secrets + * while initializing the #SecretService + * @SECRET_SERVICE_LOAD_COLLECTIONS: load collections while initializing the + * #SecretService + * + * Flags which determine which parts of the #SecretService proxy are initialized + * during a secret_service_get() or secret_service_new() operation. + */ + EGG_SECURE_GLIB_DEFINITIONS (); static const gchar *default_bus_name = SECRET_SERVICE_BUS_NAME; @@ -249,11 +322,29 @@ secret_service_class_init (SecretServiceClass *klass) klass->item_gtype = SECRET_TYPE_ITEM; klass->collection_gtype = SECRET_TYPE_COLLECTION; + /** + * SecretService:flags: + * + * A set of flags describing which parts of the secret service have + * been initialized. + */ g_object_class_install_property (object_class, PROP_FLAGS, g_param_spec_flags ("flags", "Flags", "Service flags", secret_service_flags_get_type (), SECRET_SERVICE_NONE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + /** + * SecretService:collections: + * + * A list of #SecretCollection objects representing the collections in + * the Secret Service. This list may be %NULL if the collections have + * not been loaded. + * + * To load the collections, specify the %SECRET_SERVICE_LOAD_COLLECTIONS + * initialization flag when calling the secret_service_get() or + * secret_service_new() functions. Or call the secret_service_ensure_collections() + * method. + */ g_object_class_install_property (object_class, PROP_COLLECTIONS, g_param_spec_boxed ("collections", "Collections", "Secret Service Collections", _secret_list_get_type (), G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); @@ -1319,7 +1410,7 @@ secret_service_ensure_collections_sync (SecretService *self, * This function is called by other parts of this library to handle prompts * for the various actions that can require prompting. * - * Override the #SecretService <literal>prompt_sync()</literal> virtual method + * Override the #SecretServiceClass::prompt_sync() virtual method * to change the behavior of the propmting. The default behavior is to simply * run secret_prompt_perform_sync() on the prompt. * diff --git a/library/secret-service.h b/library/secret-service.h index 48af16e..5c12efd 100644 --- a/library/secret-service.h +++ b/library/secret-service.h @@ -44,6 +44,8 @@ typedef struct _SecretServicePrivate SecretServicePrivate; struct _SecretService { GDBusProxy parent; + + /*< private >*/ SecretServicePrivate *pv; }; @@ -68,6 +70,7 @@ struct _SecretServiceClass { GAsyncResult *result, GError **error); + /*< private >*/ gpointer padding[16]; }; diff --git a/library/secret-types.h b/library/secret-types.h index ce6eb0f..b13eb78 100644 --- a/library/secret-types.h +++ b/library/secret-types.h @@ -36,11 +36,13 @@ typedef enum { } SecretSchemaType; typedef struct { + const gchar* name; + SecretSchemaType type; +} SecretSchemaAttribute; + +typedef struct { const gchar *schema_name; - struct { - const gchar* name; - SecretSchemaType type; - } attributes[32]; + SecretSchemaAttribute attributes[32]; /* <private> */ gpointer reserved1; diff --git a/library/secret-util.c b/library/secret-util.c index b5392e7..1e80d75 100644 --- a/library/secret-util.c +++ b/library/secret-util.c @@ -17,6 +17,15 @@ #include <string.h> +/** + * SecretError: + * @SECRET_ERROR_PROTOCOL: received an invalid data or message from the Secret + * Service + * + * Errors returned by the Secret Service. None of the errors are appropriate + * for display to the user. + */ + static void list_unref_free (GList *reflist) { diff --git a/library/secret-value.c b/library/secret-value.c index 20afd2d..87ec3ca 100644 --- a/library/secret-value.c +++ b/library/secret-value.c @@ -19,6 +19,30 @@ #include <string.h> +/** + * SECTION:secret-value + * @title: SecretValue + * @short_description: a value containing a secret + * + * A #SecretValue contains a password or other secret value. + * + * Use secret_value_get() to get the actual secret data, such as a password. + * The secret data is not necessarily null-terminated, unless the content type + * is "text/plain". + * + * Each #SecretValue has a content type. For passwords, this is "text/plain". + * Use secret_value_get_content_type() to look at the content type. + * + * #SecretValue is reference counted and immutable. The secret data is only + * freed when all references have been released via secret_value_unref(). + */ + +/** + * SecretValue: + * + * A secret value, like a password or other binary secret. + */ + EGG_SECURE_DECLARE (secret_value); struct _SecretValue { |