[glib/tls-database] Documentation for GTlsDatabase

[Stefan Walter <stefw src gnome org>]

commit 42a05089d743078ae9a26eec2fe44e829a6b39c6
Author: Stef Walter <stefw collabora co uk>
Date:   Mon Dec 27 20:29:24 2010 -0600

    Documentation for GTlsDatabase
    
    https://bugzilla.gnome.org/show_bug.cgi?id=636572

 docs/reference/gio/gio-docs.xml     |    1 +
 docs/reference/gio/gio-sections.txt |   25 ++++++
 docs/reference/gio/gio.types        |    1 +
 gio/gtlsdatabase.c                  |  157 +++++++++++++++++++++++++++++++++++
 4 files changed, 184 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index ad1aee5..e342df4 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -137,6 +137,7 @@
       <xi:include href="xml/gtlsclientconnection.xml"/>
       <xi:include href="xml/gtlsserverconnection.xml"/>
       <xi:include href="xml/gtlsbackend.xml"/>
+      <xi:include href="xml/gtlsdatabase.xml"/>
     </chapter>
     <chapter id="resolver">
       <title>DNS resolution</title>
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 2facc21..c3196e8 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -3088,6 +3088,31 @@ g_tls_client_connection_get_type
 </SECTION>
 
 <SECTION>
+<FILE>gtlsdatabase</FILE>
+<TITLE>GTlsDatabase</TITLE>
+GTlsDatabase
+GTlsDatabaseVerifyFlags
+G_TLS_DATABASE_PURPOSE_SERVER_AUTH
+G_TLS_DATABASE_PURPOSE_CLIENT_AUTH
+g_tls_database_verify_chain
+g_tls_database_verify_chain_async
+g_tls_database_verify_chain_finish
+g_tls_database_lookup_issuer
+g_tls_database_lookup_issuer_async
+g_tls_database_lookup_issuer_finish
+<SUBSECTION Standard>
+G_IS_TLS_DATABASE
+G_IS_TLS_DATABASE_CLASS
+G_TLS_DATABASE
+G_TLS_DATABASE_CLASS
+G_TLS_DATABASE_GET_CLASS
+G_TYPE_TLS_DATABASE
+<SUBSECTION Private>
+g_tls_database_get_type
+GTlsDatabasePrivate
+</SECTION>
+
+<SECTION>
 <FILE>gtlsserverconnection</FILE>
 <TITLE>GTlsServerConnection</TITLE>
 GTlsServerConnection
diff --git a/docs/reference/gio/gio.types b/docs/reference/gio/gio.types
index d631517..e808a77 100644
--- a/docs/reference/gio/gio.types
+++ b/docs/reference/gio/gio.types
@@ -110,6 +110,7 @@ g_tls_backend_get_type
 g_tls_certificate_get_type
 g_tls_client_connection_get_type
 g_tls_connection_get_type
+g_tls_database_get_type
 g_tls_server_connection_get_type
 g_unix_connection_get_type
 g_unix_fd_list_get_type
diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c
index d233d16..ec373e9 100644
--- a/gio/gtlsdatabase.c
+++ b/gio/gtlsdatabase.c
@@ -28,8 +28,46 @@
 #include "gsocketconnectable.h"
 #include "gtlscertificate.h"
 
+/**
+ * SECTION:gtlsdatabase
+ * @short_description: TLS database type
+ * @include: gio/gio.h
+ *
+ * #GTlsDatabase is used to lookup certificates and other information
+ * from a certificate or key store. It is an abstract base class which
+ * TLS library specific subtypes override.
+ *
+ * The most common operation with a %GTlsDatabase is using the
+ * g_tls_database_verify_chain () to build up and verify a chain of
+ * #GTlsCertificate objects.
+ *
+ * Since: 2.28
+ */
+
+/**
+ * GTlsDatabase:
+ *
+ * Abstract base class for the backend-specific database types.
+ *
+ * Since: 2.28
+ */
+
 G_DEFINE_ABSTRACT_TYPE (GTlsDatabase, g_tls_database, G_TYPE_OBJECT);
 
+/**
+ * G_TLS_DATABASE_PURPOSE_SERVER_AUTH:
+ *
+ * The purpose used to verify the server certificate in a TLS connection. This
+ * is the most common purpose in use. Used by TLS clients.
+ */
+
+/**
+ * G_TLS_DATABASE_PURPOSE_CLIENT_AUTH:
+ *
+ * The purpose used to verify the client certificate in a TLS connection.
+ * Used by TLS servers.
+ */
+
 static void
 g_tls_database_init (GTlsDatabase *cert)
 {
@@ -218,6 +256,46 @@ g_tls_database_class_init (GTlsDatabaseClass *klass)
   klass->lookup_issuer_finish = g_tls_database_real_lookup_issuer_finish;
 }
 
+/**
+ * g_tls_database_verify_chain:
+ * @self: a #GTlsDatabase
+ * @chain: a #GTlsCertificate chain
+ * @purpose: the purpose that this certificate chain will be used for.
+ * @identity: (allow-none): the expected peer identity
+ * @flags: additional verify flags
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: (allow-none): a #GError, or %NULL
+ *
+ * Verify's a certificate chain after looking up and adding any missing
+ * certificates to the chain.
+ *
+ * @chain is a chain of #GTlsCertificate objects each pointing to the next
+ * certificate in the chain by its %issuer property. The chain may initially
+ * consist of one or more certificates. After the verification process is
+ * complete, @chain may be modified by adding missing certificates, or removing
+ * extra certificates. If a certificate anchor was found, then it is added to
+ * the @chain.
+ *
+ * @purpose describes the purpose (or usage) for which the certificate
+ * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_SERVER_AUTH
+ * which means that the certificate is being used to authenticate a server
+ * (and we are acting as the client).
+ *
+ * The @identity is used to check for pinned certificates (trust exceptions)
+ * in the database. These will override the normal verification process on a
+ * host by host basis.
+ *
+ * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
+ * used.
+ *
+ * This function can block, use g_tls_database_verify_chain_async() to perform
+ * the verification operation asynchronously.
+ *
+ * Return value: the appropriate #GTlsCertificateFlags which represents the
+ * result of verification.
+ *
+ * Since: 2.28
+ */
 GTlsCertificateFlags
 g_tls_database_verify_chain (GTlsDatabase           *self,
                              GTlsCertificate        *chain,
@@ -239,6 +317,24 @@ g_tls_database_verify_chain (GTlsDatabase           *self,
                                                         error);
 }
 
+/**
+ * g_tls_database_verify_chain_async:
+ * @self: a #GTlsDatabase
+ * @chain: a #GTlsCertificate chain
+ * @purpose: the purpose that this certificate chain will be used for.
+ * @identity: (allow-none): the expected peer identity
+ * @flags: additional verify flags
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: callback to call when the operation completes
+ * @user_data: the data to pass to the callback function
+ *
+ * Asynchronously verify's a certificate chain after looking up and adding
+ * any missing certificates to the chain. See g_tls_database_verify_chain()
+ * for more information.
+ *
+ * Since: 2.28
+ */
+
 void
 g_tls_database_verify_chain_async (GTlsDatabase           *self,
                                    GTlsCertificate        *chain,
@@ -261,6 +357,19 @@ g_tls_database_verify_chain_async (GTlsDatabase           *self,
                                                        user_data);
 }
 
+/**
+ * g_tls_database_verify_chain_finish:
+ * @self: a #GTlsDatabase
+ * @result: a #GAsyncResult.
+ * @error: a #GError pointer, or %NULL
+ *
+ * Finish an asynchronous verify chain operation. See
+ * g_tls_database_verify_chain() for more information. *
+ * Return value: the appropriate #GTlsCertificateFlags which represents the
+ * result of verification.
+ *
+ * Since: 2.28
+ */
 GTlsCertificateFlags
 g_tls_database_verify_chain_finish (GTlsDatabase          *self,
                                     GAsyncResult          *result,
@@ -274,6 +383,27 @@ g_tls_database_verify_chain_finish (GTlsDatabase          *self,
                                                                error);
 }
 
+/**
+ * g_tls_database_lookup_issuer:
+ * @self: a #GTlsDatabase
+ * @certificate: a #GTlsCertificate
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: (allow-none): a #GError, or %NULL
+ *
+ * Lookup the issuer of @certificate in the database.
+ *
+ * The %issuer property
+ * of @certificate is not modified, and the two certificates are not hooked
+ * into a chain.
+ *
+ * This function can block, use g_tls_database_lookup_issuer_async() to perform
+ * the lookup operation asynchronously.
+ *
+ * Return value: (transfer full): a newly allocated issuer #GTlsCertificate,
+ * or %NULL. Use g_object_unref() to release the certificate.
+ *
+ * Since: 2.28
+ */
 GTlsCertificate*
 g_tls_database_lookup_issuer (GTlsDatabase          *self,
                               GTlsCertificate       *certificate,
@@ -288,6 +418,19 @@ g_tls_database_lookup_issuer (GTlsDatabase          *self,
                                                          error);
 }
 
+/**
+ * g_tls_database_lookup_issuer_async:
+ * @self: a #GTlsDatabase
+ * @certificate: a #GTlsCertificate
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: callback to call when the operation completes
+ * @user_data: the data to pass to the callback function
+ *
+ * Asynchronously lookup the issuer of @certificate in the database. See
+ * g_tls_database_lookup_issuer() for more information.
+ *
+ * Since: 2.28
+ */
 void
 g_tls_database_lookup_issuer_async (GTlsDatabase          *self,
                                     GTlsCertificate       *certificate,
@@ -304,6 +447,20 @@ g_tls_database_lookup_issuer_async (GTlsDatabase          *self,
                                                         user_data);
 }
 
+/**
+ * g_tls_database_lookup_issuer_finish:
+ * @self: a #GTlsDatabase
+ * @result: a #GAsyncResult.
+ * @error: a #GError pointer, or %NULL
+ *
+ * Finish an asynchronous lookup issuer operation. See
+ * g_tls_database_lookup_issuer() for more information.
+ *
+ * Return value: (transfer full): a newly allocated issuer #GTlsCertificate,
+ * or %NULL. Use g_object_unref() to release the certificate.
+ *
+ * Since: 2.28
+ */
 GTlsCertificate*
 g_tls_database_lookup_issuer_finish (GTlsDatabase          *self,
                                      GAsyncResult          *result,