Cypher_Stack/libsecret
2
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/libsecret.git synced 2024-12-22 04:38:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Reference documentation

Browse Source
This commit is contained in:
Stef Walter 2012-02-02 14:59:59 +01:00
parent 06e8436557
commit 3edec36350
28 changed files with 870 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
.gitignore vendored
View File

@ -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

2
Makefile.am
View File

@ -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 \

2
autogen.sh
View File

@ -91,6 +91,8 @@ $ACLOCAL $ACLOCAL_FLAGS || exit $?
libtoolize --force || exit $?
intltoolize --force --copy || exit $?
gtkdocize || exit $?
autoheader || exit $?
$AUTOMAKE --add-missing || exit $?

6
configure.ac
View File

@ -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

2
docs/Makefile.am Normal file
View File

@ -0,0 +1,2 @@
SUBDIRS = reference

30
docs/reference/COPYING Normal file
View File

@ -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.

2
docs/reference/Makefile.am Normal file
View File

@ -0,0 +1,2 @@
SUBDIRS = libsecret

102
docs/reference/libsecret/Makefile.am Normal file
View File

@ -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)

34
docs/reference/libsecret/libsecret-docs.sgml Normal file
View File

@ -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>

2
docs/reference/libsecret/libsecret-overrides.txt Normal file
View File

@ -0,0 +1,2 @@
# These are manually-edited to override or add declarations to those scanned
# from the header files.

252
docs/reference/libsecret/libsecret-sections.txt Normal file
View File

@ -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>

6
docs/reference/libsecret/libsecret.interfaces Normal file
View File

@ -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

7
docs/reference/libsecret/libsecret.types Normal file
View File

@ -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

1
docs/reference/libsecret/version.xml.in Normal file
View File

@ -0,0 +1 @@
@VERSION@

2
library/Makefile.am
View File

@ -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

73
library/secret-collection.c
View File

@ -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

4
library/secret-collection.h
View File

@ -35,11 +35,15 @@ typedef struct _SecretCollectionPrivate SecretCollectionPrivate;
struct _SecretCollection {
GDBusProxy parent;
/*< private >*/
SecretCollectionPrivate *pv;
};
struct _SecretCollectionClass {
GDBusProxyClass parent_class;
/*< private >*/
gpointer padding[8];
};

90
library/secret-item.c
View File

@ -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
*

4
library/secret-item.h
View File

@ -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];
};

12
library/secret-methods.c
View File

@ -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,

54
library/secret-password.c
View File

@ -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;

32
library/secret-prompt.c
View File

@ -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 */

4
library/secret-prompt.h
View File

@ -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];
};

93
library/secret-service.c
View File

@ -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.
*

3
library/secret-service.h
View File

@ -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];
};

10
library/secret-types.h
View File

@ -35,12 +35,14 @@ typedef enum {
SECRET_ATTRIBUTE_INTEGER
} 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;

9
library/secret-util.c
View File

@ -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)
{

24
library/secret-value.c
View File

@ -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 {