[glib/tls-database] Documentation for GTlsDatabase
- From: Stefan Walter <stefw src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib/tls-database] Documentation for GTlsDatabase
- Date: Tue, 28 Dec 2010 02:36:30 +0000 (UTC)
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,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]