[gnome-keyring] gcr: Add documentation for GcrSecretExchange

[Stefan Walter <stefw src gnome org>]

commit f108c3c6a07c05eb81b5c8191130693cba7ec06a
Author: Stef Walter <stefw collabora co uk>
Date:   Tue Aug 23 09:56:02 2011 +0200

    gcr: Add documentation for GcrSecretExchange
    
    https://bugzilla.gnome.org/show_bug.cgi?id=656955

 docs/reference/gcr/gcr-docs.sgml    |    1 +
 docs/reference/gcr/gcr-sections.txt |   20 +++++++
 gcr/gcr-secret-exchange.c           |  101 +++++++++++++++++++++++++++++++++++
 gcr/gcr-secret-exchange.h           |    4 +-
 4 files changed, 124 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/gcr/gcr-docs.sgml b/docs/reference/gcr/gcr-docs.sgml
index f995d32..4746d57 100644
--- a/docs/reference/gcr/gcr-docs.sgml
+++ b/docs/reference/gcr/gcr-docs.sgml
@@ -57,6 +57,7 @@
 	<part id="misc">
 		<title>Miscellaneous</title>
 		<xi:include href="xml/gcr-library.xml"/>
+		<xi:include href="xml/gcr-secret-exchange.xml"/>
 		<xi:include href="xml/gcr-misc.xml"/>
 	</part>
 
diff --git a/docs/reference/gcr/gcr-sections.txt b/docs/reference/gcr/gcr-sections.txt
index 68a7c98..070fafe 100644
--- a/docs/reference/gcr/gcr-sections.txt
+++ b/docs/reference/gcr/gcr-sections.txt
@@ -571,6 +571,26 @@ GcrViewerWidgetPrivate
 </SECTION>
 
 <SECTION>
+<FILE>gcr-secret-exchange</FILE>
+GcrSecretExchange
+GcrSecretExchangeClass
+gcr_secret_exchange_new
+gcr_secret_exchange_begin
+gcr_secret_exchange_receive
+gcr_secret_exchange_get_secret
+gcr_secret_exchange_send
+<SUBSECTION Standard>
+gcr_secret_exchange_get_type
+GCR_IS_SECRET_EXCHANGE
+GCR_IS_SECRET_EXCHANGE_CLASS
+GCR_SECRET_EXCHANGE
+GCR_SECRET_EXCHANGE_CLASS
+GCR_SECRET_EXCHANGE_GET_CLASS
+GCR_TYPE_SECRET_EXCHANGE
+GcrSecretExchangePrivate
+</SECTION>
+
+<SECTION>
 <FILE>gcr-private</FILE>
 <SUBSECTION Private>
 GCR_GNUPG_COLLECTION
diff --git a/gcr/gcr-secret-exchange.c b/gcr/gcr-secret-exchange.c
index ff5d3e6..869b6de 100644
--- a/gcr/gcr-secret-exchange.c
+++ b/gcr/gcr-secret-exchange.c
@@ -32,6 +32,46 @@
 #include <string.h>
 #include <gcrypt.h>
 
+/**
+ * SECTION:gcr-secret-exchange
+ * @title: GcrSecretExchange
+ * @short_description: Exchange secrets between processes in an unexposed way.
+ *
+ * Allows exchange of secrets between two processes on the same system without
+ * exposing those secrets to things like loggers, non-pageable memory etc.
+ *
+ * This does not protect against active attacks like MITM attacks.
+ *
+ * Each side creates a #GcrSecretExchange object, and one of the sides calls
+ * gcr_secret_exchange_begin(). This creates a string, which should be passed
+ * to the other side. Each side passes the strings it receives into
+ * gcr_secret_exchange_receive().
+ *
+ * In order to send a reply (either with or without a secret) use
+ * gcr_secret_exchange_send(). A side must have had gcr_secret_exchange_receive()
+ * successfully called before it can use gcr_secret_exchange_send().
+ *
+ * The #GcrSecretExchange objects can be used for multiple iterations of the
+ * conversation, or for just one request/reply. The only limitation being that
+ * the initial request cannot contain a secret.
+ *
+ * Caveat: Information about the approximate length (rounded up to the nearest
+ * 16 bytes) may be leaked. If this is considered inacceptable, do not use
+ * #GcrSecretExchange.
+ */
+
+/**
+ * GcrSecretExchange:
+ *
+ * An object representing one side of a secret exchange.
+ */
+
+/**
+ * GcrSecretExchangeClass:
+ *
+ * The class for #GcrSecretExchange
+ */
+
 /*
  * This is the only set we support so far. It includes:
  *  - DH with the 1536 ike modp group for key exchange
@@ -183,12 +223,30 @@ gcr_secret_exchange_class_init (GcrSecretExchangeClass *klass)
 	egg_libgcrypt_initialize ();
 }
 
+/**
+ * gcr_secret_exchange_new:
+ *
+ * Create a new secret exchange object.
+ *
+ * Returns: (transfer full): A new #GcrSecretExchange object
+ */
 GcrSecretExchange *
 gcr_secret_exchange_new (void)
 {
 	return g_object_new (GCR_TYPE_SECRET_EXCHANGE, NULL);
 }
 
+/**
+ * gcr_secret_exchange_begin:
+ * @self: a #GcrSecretExchange object
+ *
+ * Begin the secret exchange. The resulting string should be sent to the other
+ * side of the exchange. The other side should use gcr_secret_exchange_receive()
+ * to process the string.
+ *
+ * Returns: (transfer full): A newly allocated string to be sent to the other
+ *     side of the secret exchange
+ */
 gchar *
 gcr_secret_exchange_begin (GcrSecretExchange *self)
 {
@@ -314,6 +372,16 @@ perform_aes_decrypt (GcrSecretExchange *self,
 	return result;
 }
 
+/**
+ * gcr_secret_exchange_receive:
+ * @self: a #GcrSecretExchange object
+ * @exchange: the string received
+ *
+ * Receive a string from the other side of secret exchange. This string will
+ * have been created by gcr_secret_exchange_begin() or gcr_secret_exchange_send()
+ *
+ * Returns: whether the string was successfully parsed and received
+ */
 gboolean
 gcr_secret_exchange_receive (GcrSecretExchange *self,
                              const gchar *exchange)
@@ -357,6 +425,23 @@ gcr_secret_exchange_receive (GcrSecretExchange *self,
 	return ret;
 }
 
+/**
+ * gcr_secret_exchange_get_secret:
+ * @self: a #GcrSecretExchange object
+ * @secret_len: (allow-none): optionally, a location to store the length of returned secret
+ *
+ * Returns the last secret received. If no secret has yet been received this
+ * will return %NULL. The string is owned by the #GcrSecretExchange object
+ * and will be valid until the next time that gcr_secret_exchange_receive()
+ * is called on this object, or the object is destroyed.
+ *
+ * Depending on the secret passed into the other side of the secret exchange,
+ * the resurt may be a binary string. It does however have a null terminator,
+ * so if you're certain that it is does not contain arbitrary binary data,
+ * it can be used as a string.
+ *
+ * Returns: (transfer none): The last secret received.
+ */
 const gchar *
 gcr_secret_exchange_get_secret (GcrSecretExchange *self,
                                 gsize *secret_len)
@@ -436,6 +521,22 @@ perform_aes_encrypt (GKeyFile *output,
 	return TRUE;
 }
 
+/**
+ * gcr_secret_exchange_send:
+ * @self: a #GcrSecretExchange object
+ * @secret: (allow-none): optionally, a secret to send to the other side
+ * @secret_len: length of @secret, or -1 if null terminated
+ *
+ * Send a reply to the other side of the secret exchange, optionally sending a
+ * secret.
+ *
+ * gcr_secret_exchange_receive() must have been successfully called at least
+ * once on this object. In other words this object must have received data
+ * from the other side of the secret exchange, before we can send a secret.
+ *
+ * Returns: (transfer full): a newly allocated string to be sent to the other
+ *     side of the secret exchange
+ */
 gchar *
 gcr_secret_exchange_send (GcrSecretExchange *self,
                           const gchar *secret,
diff --git a/gcr/gcr-secret-exchange.h b/gcr/gcr-secret-exchange.h
index 5bd3ecf..41ff8b3 100644
--- a/gcr/gcr-secret-exchange.h
+++ b/gcr/gcr-secret-exchange.h
@@ -42,13 +42,13 @@ typedef struct _GcrSecretExchangeClass GcrSecretExchangeClass;
 typedef struct _GcrSecretExchangePrivate GcrSecretExchangePrivate;
 
 struct _GcrSecretExchange {
-	GObject parent;
-
 	/*< private >*/
+	GObject parent;
 	GcrSecretExchangePrivate *pv;
 };
 
 struct _GcrSecretExchangeClass {
+	/*< private >*/
 	GObjectClass parent_class;
 };