secret-retrievable: New interface to represent read-only item

This is a ground work for adding a local storage backend.  As
SecretItem is derived from GDBusProxy, it cannot be simply exposed to
the application through the secret_password_search() if the item is
not backed by the DBus API.  This adds an abstract interface
representing a read-only view of a secret item for that purpose.

docs/reference/libsecret/libsecret-docs.sgml

@@ -26,6 +26,7 @@
 		<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-retrievable.xml"/>
 		<xi:include href="xml/secret-value.xml"/>
 		<xi:include href="xml/secret-attributes.xml"/>
 		<xi:include href="xml/secret-prompt.xml"/>

docs/reference/libsecret/libsecret-sections.txt

@@ -137,6 +137,21 @@ secret_password_wipe
 secret_password_free
 </SECTION>
 
+<SECTION>
+<FILE>secret-retrievable</FILE>
+<INCLUDE>libsecret/secret.h</INCLUDE>
+SECRET_TYPE_RETRIEVABLE
+SecretRetrievable
+SecretRetrievableInterface
+secret_retrievable_get_attributes
+secret_retrievable_get_created
+secret_retrievable_get_label
+secret_retrievable_get_modified
+secret_retrievable_retrieve_secret
+secret_retrievable_retrieve_secret_finish
+secret_retrievable_retrieve_secret_sync
+</SECTION>
+
 <SECTION>
 <FILE>secret-schema</FILE>
 <INCLUDE>libsecret/secret.h</INCLUDE>

libsecret/Makefile.am

@@ -12,6 +12,7 @@ libsecret_HEADS = \
 	libsecret/secret-password.h \
 	libsecret/secret-paths.h \
 	libsecret/secret-prompt.h \
+	libsecret/secret-retrievable.h \
 	libsecret/secret-schema.h \
 	libsecret/secret-schemas.h \
 	libsecret/secret-service.h \
@@ -42,6 +43,7 @@ libsecret_PUBLIC = \
 	libsecret/secret-methods.c \
 	libsecret/secret-password.h libsecret/secret-password.c \
 	libsecret/secret-prompt.h libsecret/secret-prompt.c \
+	libsecret/secret-retrievable.h libsecret/secret-retrievable.c \
 	libsecret/secret-schema.h libsecret/secret-schema.c \
 	libsecret/secret-schemas.h libsecret/secret-schemas.c \
 	libsecret/secret-service.h libsecret/secret-service.c \

libsecret/meson.build

@@ -7,6 +7,7 @@ libsecret_sources = [
   'secret-methods.c',
   'secret-password.c',
   'secret-prompt.c',
+  'secret-retrievable.c',
   'secret-schema.c',
   'secret-schemas.c',
   'secret-service.c',
@@ -24,6 +25,7 @@ libsecret_headers = [
   'secret-password.h',
   'secret-paths.h',
   'secret-prompt.h',
+  'secret-retrievable.h',
   'secret-schema.h',
   'secret-schemas.h',
   'secret-service.h',
@@ -104,6 +106,8 @@ libsecret_gir_sources = [
   'secret-paths.h',
   'secret-prompt.c',
   'secret-prompt.h',
+  'secret-retrievable.c',
+  'secret-retrievable.h',
   'secret-schema.c',
   'secret-schema.h',
   'secret-schemas.c',

libsecret/secret-retrievable.c

@@ -0,0 +1,307 @@
+/* libsecret - GLib wrapper for Secret Service
+ *
+ * Copyright 2019 Red Hat, Inc.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation; either version 2.1 of the licence or (at
+ * your option) any later version.
+ *
+ * See the included COPYING file for more information.
+ *
+ * Author: Daiki Ueno
+ */
+
+#include "config.h"
+
+#include "secret-retrievable.h"
+#include "secret-private.h"
+
+/**
+ * SECTION:secret-retrievable
+ * @title: SecretRetrievable
+ * @short_description: A read-only secret item
+ *
+ * #SecretRetrievable provides a read-only view of a secret item
+ * stored in the Secret Service.
+ *
+ * Each item has a value, represented by a #SecretValue, which can be
+ * retrieved by secret_retrievable_retrieve_secret() and
+ * secret_retrievable_retrieve_secret_finish().
+ *
+ * Stability: Stable
+ */
+
+/**
+ * SecretRetrievable:
+ *
+ * An object representing a read-only view of a secret item in the
+ * Secret Service.
+ *
+ * Since: 0.19.0
+ */
+
+/**
+ * SecretRetrievableInterface:
+ * @parent_iface: the parent interface
+ * @retrieve_secret: implementation of secret_retrievable_retrieve_secret(),
+ *                   required
+ * @retrieve_secret_finish: implementation of
+ *                   secret_retrievable_retrieve_secret_finish(), required
+ *
+ * The interface for #SecretRetrievable.
+ *
+ * Since: 0.19.0
+ */
+
+G_DEFINE_INTERFACE (SecretRetrievable, secret_retrievable, G_TYPE_OBJECT);
+
+static void
+secret_retrievable_default_init (SecretRetrievableInterface *iface)
+{
+	/**
+	 * SecretRetrievable:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full)
+	 *
+	 * The attributes set on this item. Attributes are used to locate an
+	 * item. They are not guaranteed to be stored or transferred securely.
+	 *
+	 * Since: 0.19.0
+	 */
+	g_object_interface_install_property (iface,
+	             g_param_spec_boxed ("attributes", "Attributes", "Item attributes",
+	                                 G_TYPE_HASH_TABLE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * SecretRetrievable:label:
+	 *
+	 * The human readable label for the item.
+	 *
+	 * Since: 0.19.0
+	 */
+	g_object_interface_install_property (iface,
+	            g_param_spec_string ("label", "Label", "Item label",
+	                                 NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * SecretRetrievable:created:
+	 *
+	 * The date and time (in seconds since the UNIX epoch) that this
+	 * item was created.
+	 *
+	 * Since: 0.19.0
+	 */
+	g_object_interface_install_property (iface,
+	            g_param_spec_uint64 ("created", "Created", "Item creation date",
+	                                 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * SecretRetrievable:modified:
+	 *
+	 * The date and time (in seconds since the UNIX epoch) that this
+	 * item was last modified.
+	 *
+	 * Since: 0.19.0
+	 */
+	g_object_interface_install_property (iface,
+	            g_param_spec_uint64 ("modified", "Modified", "Item modified date",
+	                                 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+}
+
+/**
+ * secret_retrievable_retrieve_secret:
+ * @self: a retrievable object
+ * @cancellable: (nullable): optional cancellation object
+ * @callback: called when the operation completes
+ * @user_data: data to pass to the callback
+ *
+ * Retrieve the secret value of this object.
+ *
+ * Each retrievable object has a single secret which might be a
+ * password or some other secret binary value.
+ *
+ * This function returns immediately and completes asynchronously.
+ *
+ * Since: 0.19.0
+ */
+void
+secret_retrievable_retrieve_secret (SecretRetrievable *self,
+				    GCancellable *cancellable,
+				    GAsyncReadyCallback callback,
+				    gpointer user_data)
+{
+	SecretRetrievableInterface *iface;
+
+	g_return_if_fail (SECRET_IS_RETRIEVABLE (self));
+	iface = SECRET_RETRIEVABLE_GET_IFACE (self);
+	g_return_if_fail (iface->retrieve_secret != NULL);
+	iface->retrieve_secret (self, cancellable, callback, user_data);
+}
+
+/**
+ * secret_retrievable_retrieve_secret_finish:
+ * @self: a retrievable object
+ * @result: asynchronous result passed to callback
+ * @error: location to place error on failure
+ *
+ * Complete asynchronous operation to retrieve the secret value of this object.
+ *
+ * Returns: (transfer full) (nullable): the secret value which should be
+ *          released with secret_value_unref(), or %NULL
+ *
+ * Since: 0.19.0
+ */
+SecretValue *
+secret_retrievable_retrieve_secret_finish (SecretRetrievable *self,
+					   GAsyncResult *result,
+					   GError **error)
+{
+	SecretRetrievableInterface *iface;
+
+	g_return_val_if_fail (SECRET_IS_RETRIEVABLE (self), NULL);
+	iface = SECRET_RETRIEVABLE_GET_IFACE (self);
+	g_return_val_if_fail (iface->retrieve_secret_finish != NULL, NULL);
+	return iface->retrieve_secret_finish (self, result, error);
+}
+
+/**
+ * secret_retrievable_retrieve_secret_sync:
+ * @self: a retrievable object
+ * @cancellable: (nullable): optional cancellation object
+ * @error: location to place error on failure
+ *
+ * Retrieve the secret value of this object synchronously.
+ *
+ * Each retrievable object has a single secret which might be a
+ * password or some other secret binary value.
+ *
+ * This method may block indefinitely and should not be used in user interface
+ * threads.
+ *
+ * Returns: (transfer full) (nullable): the secret value which should be
+ *          released with secret_value_unref(), or %NULL
+ *
+ * Since: 0.19.0
+ */
+SecretValue *
+secret_retrievable_retrieve_secret_sync (SecretRetrievable *self,
+					 GCancellable *cancellable,
+					 GError **error)
+{
+	SecretSync *sync;
+	SecretValue *value;
+
+	g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
+	g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
+
+	sync = _secret_sync_new ();
+	g_main_context_push_thread_default (sync->context);
+
+	secret_retrievable_retrieve_secret (self,
+					    cancellable,
+					    _secret_sync_on_result, sync);
+
+	g_main_loop_run (sync->loop);
+
+	value = secret_retrievable_retrieve_secret_finish (self,
+							   sync->result,
+							   error);
+
+	g_main_context_pop_thread_default (sync->context);
+	_secret_sync_free (sync);
+
+	return value;
+}
+
+/**
+ * secret_retrievable_get_attributes:
+ * @self: a retrievable object
+ *
+ * Get the attributes of this object.
+ *
+ * The attributes are a mapping of string keys to string values.
+ * Attributes are used to search for items. Attributes are not stored
+ * or transferred securely by the secret service.
+ *
+ * Do not modify the attribute returned by this method.
+ *
+ * Returns: (transfer full) (element-type utf8 utf8): a new reference
+ *          to the attributes, which should not be modified, and
+ *          released with g_hash_table_unref()
+ *
+ * Since: 0.19.0
+ */
+GHashTable *
+secret_retrievable_get_attributes (SecretRetrievable *self)
+{
+	GHashTable *value;
+
+	g_return_val_if_fail (SECRET_IS_RETRIEVABLE (self), NULL);
+
+	g_object_get (G_OBJECT (self), "attributes", &value, NULL);
+	return value;
+}
+
+/**
+ * secret_retrievable_get_label:
+ * @self: a retrievable object
+ *
+ * Get the label of this item.
+ *
+ * Returns: (transfer full): the label, which should be freed with g_free()
+ *
+ * Since: 0.19.0
+ */
+gchar *
+secret_retrievable_get_label (SecretRetrievable *self)
+{
+	gchar *value;
+
+	g_return_val_if_fail (SECRET_IS_RETRIEVABLE (self), NULL);
+
+	g_object_get (G_OBJECT (self), "label", &value, NULL);
+	return value;
+}
+
+/**
+ * secret_retrievable_get_created:
+ * @self: a retrievable object
+ *
+ * Get the created date and time of the object. The return value is
+ * the number of seconds since the unix epoch, January 1st 1970.
+ *
+ * Returns: the created date and time
+ *
+ * Since: 0.19.0
+ */
+guint64
+secret_retrievable_get_created (SecretRetrievable *self)
+{
+	guint64 value;
+
+	g_return_val_if_fail (SECRET_IS_RETRIEVABLE (self), 0);
+
+	g_object_get (G_OBJECT (self), "created", &value, NULL);
+	return value;
+}
+
+/**
+ * secret_retrievable_get_modified:
+ * @self: a retrievable object
+ *
+ * Get the modified date and time of the object. The return value is
+ * the number of seconds since the unix epoch, January 1st 1970.
+ *
+ * Returns: the modified date and time
+ *
+ * Since: 0.19.0
+ */
+guint64
+secret_retrievable_get_modified (SecretRetrievable *self)
+{
+	guint64 value;
+
+	g_return_val_if_fail (SECRET_IS_RETRIEVABLE (self), 0);
+
+	g_object_get (G_OBJECT (self), "modified", &value, NULL);
+	return value;
+}

libsecret/secret-retrievable.h

@@ -0,0 +1,64 @@
+/* libsecret - GLib wrapper for Secret Service
+ *
+ * Copyright 2019 Red Hat, Inc.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation; either version 2.1 of the licence or (at
+ * your option) any later version.
+ *
+ * See the included COPYING file for more information.
+ *
+ * Author: Daiki Ueno
+ */
+
+#if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION)
+#error "Only <libsecret/secret.h> can be included directly."
+#endif
+
+#ifndef __SECRET_RETRIEVABLE_H__
+#define __SECRET_RETRIEVABLE_H__
+
+#include <glib-object.h>
+#include "secret-value.h"
+
+G_BEGIN_DECLS
+
+#define SECRET_TYPE_RETRIEVABLE secret_retrievable_get_type ()
+G_DECLARE_INTERFACE (SecretRetrievable, secret_retrievable, SECRET, RETRIEVABLE, GObject)
+
+struct _SecretRetrievableInterface
+{
+	GTypeInterface parent_iface;
+
+	void         (*retrieve_secret)        (SecretRetrievable *self,
+						GCancellable *cancellable,
+						GAsyncReadyCallback callback,
+						gpointer user_data);
+	SecretValue *(*retrieve_secret_finish) (SecretRetrievable *self,
+						GAsyncResult *result,
+						GError **error);
+};
+
+void         secret_retrievable_retrieve_secret        (SecretRetrievable *self,
+							GCancellable *cancellable,
+							GAsyncReadyCallback callback,
+							gpointer user_data);
+
+SecretValue *secret_retrievable_retrieve_secret_finish (SecretRetrievable *self,
+							GAsyncResult *result,
+							GError **error);
+
+SecretValue *secret_retrievable_retrieve_secret_sync   (SecretRetrievable *self,
+							GCancellable *cancellable,
+							GError **error);
+
+GHashTable  *secret_retrievable_get_attributes         (SecretRetrievable *self);
+gchar       *secret_retrievable_get_label              (SecretRetrievable *self);
+guint64      secret_retrievable_get_created            (SecretRetrievable *self);
+guint64      secret_retrievable_get_modified           (SecretRetrievable *self);
+
+
+G_END_DECLS
+
+#endif /* __SECRET_RETRIEVABLE_H__ */

libsecret/secret.h

@@ -25,6 +25,7 @@
 #include <libsecret/secret-item.h>
 #include <libsecret/secret-password.h>
 #include <libsecret/secret-prompt.h>
+#include <libsecret/secret-retrievable.h>
 #include <libsecret/secret-schema.h>
 #include <libsecret/secret-schemas.h>
 #include <libsecret/secret-service.h>