[gnome-keyring/trust-store] [gcr] Complete documentation for various certificate types.
- From: Stefan Walter <stefw src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-keyring/trust-store] [gcr] Complete documentation for various certificate types.
- Date: Tue, 7 Dec 2010 19:30:59 +0000 (UTC)
commit e7fc25a56cb4c4e039e60f2b4457183711ca5e75
Author: Stef Walter <stefw collabora co uk>
Date: Tue Dec 7 19:30:35 2010 +0000
[gcr] Complete documentation for various certificate types.
docs/reference/gcr/gcr-docs.sgml | 41 ++++++++------
docs/reference/gcr/gcr-sections.txt | 24 ++++++++-
docs/reference/gcr/gcr.types | 1 +
gcr/gcr-certificate.c | 53 ++++++++++++++++---
gcr/gcr-pkcs11-certificate.c | 102 ++++++++++++++++++++++++++++++----
gcr/gcr-pkcs11-certificate.h | 10 ++--
gcr/gcr-simple-certificate.c | 34 ++++++++++++
gcr/gcr-trust.c | 2 +-
8 files changed, 222 insertions(+), 45 deletions(-)
---
diff --git a/docs/reference/gcr/gcr-docs.sgml b/docs/reference/gcr/gcr-docs.sgml
index f7a0eaa..208be0a 100644
--- a/docs/reference/gcr/gcr-docs.sgml
+++ b/docs/reference/gcr/gcr-docs.sgml
@@ -2,23 +2,28 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
- <bookinfo>
- <title>gcr Reference Manual</title>
- <releaseinfo>
- for gcr [VERSION]
- The latest version of this documentation can be found on-line at
- <ulink role="online-location" url="http://[SERVER]/gcr/index.html";>http://[SERVER]/gcr/</ulink>.
- </releaseinfo>
- </bookinfo>
+ <bookinfo>
+ <title>gcr Reference Manual</title>
+ <releaseinfo>
+ for gcr [VERSION]
+ The latest version of this documentation can be found on-line at
+ <ulink role="online-location" url="http://[SERVER]/gcr/index.html";>http://[SERVER]/gcr/</ulink>.
+ </releaseinfo>
+ </bookinfo>
+
+ <part id="certificates">
+ <title>Certificates</title>
+ <xi:include href="xml/gcr-certificate.xml"/>
+ <xi:include href="xml/gcr-simple-certificate.xml"/>
+ <xi:include href="xml/gcr-pkcs11-certificate.xml"/>
+ </part>
+
+ <part id="storage">
+ <title>Storage</title>
+ <xi:include href="xml/gcr-trust.xml"/>
+ <xi:include href="xml/gcr-initializer.xml"/>
+ <xi:include href="xml/gcr-importer.xml"/>
+ <xi:include href="xml/gcr-parser.xml"/>
+ </part>
- <chapter>
- <title>[Insert title here]</title>
- <xi:include href="xml/gcr-parser.xml"/>
- <xi:include href="xml/gcr-certificate.xml"/>
- <xi:include href="xml/gcr-initializer.xml"/>
- <xi:include href="xml/gcr-importer.xml"/>
- <xi:include href="xml/gcr-simple-certificate.xml"/>
- <xi:include href="xml/gcr-types.xml"/>
- <xi:include href="xml/gcr-trust.xml"/>
- </chapter>
</book>
diff --git a/docs/reference/gcr/gcr-sections.txt b/docs/reference/gcr/gcr-sections.txt
index fec7175..1359b0e 100644
--- a/docs/reference/gcr/gcr-sections.txt
+++ b/docs/reference/gcr/gcr-sections.txt
@@ -39,16 +39,18 @@ GCR_PARSER_GET_CLASS
<SECTION>
<FILE>gcr-certificate</FILE>
-GCR_CERTIFICATE_GET_INTERFACE
GcrCertificate
GcrCertificateIface
gcr_certificate_get_der_data
gcr_certificate_get_issuer_cn
gcr_certificate_get_issuer_dn
gcr_certificate_get_issuer_part
+gcr_certificate_get_issuer_raw
+gcr_certificate_is_issuer
gcr_certificate_get_subject_cn
gcr_certificate_get_subject_dn
gcr_certificate_get_subject_part
+gcr_certificate_get_subject_raw
gcr_certificate_get_issued_date
gcr_certificate_get_expiry_date
gcr_certificate_get_serial_number
@@ -60,6 +62,7 @@ gcr_certificate_get_fingerprint_hex
GCR_CERTIFICATE
GCR_IS_CERTIFICATE
GCR_TYPE_CERTIFICATE
+GCR_CERTIFICATE_GET_INTERFACE
gcr_certificate_get_type
</SECTION>
@@ -114,11 +117,12 @@ GCR_IMPORTER_GET_CLASS
<SECTION>
<FILE>gcr-simple-certificate</FILE>
-GcrSimpleCertificatePrivate
<TITLE>GcrSimpleCertificate</TITLE>
GcrSimpleCertificate
gcr_simple_certificate_new
+gcr_simple_certificate_new_static
<SUBSECTION Standard>
+GcrSimpleCertificatePrivate
GCR_SIMPLE_CERTIFICATE
GCR_IS_SIMPLE_CERTIFICATE
GCR_TYPE_SIMPLE_CERTIFICATE
@@ -129,6 +133,22 @@ GCR_SIMPLE_CERTIFICATE_GET_CLASS
</SECTION>
<SECTION>
+<FILE>gcr-pkcs11-certificate</FILE>
+<TITLE>GcrPkcs11Certificate</TITLE>
+GcrPkcs11Certificate
+gcr_pkcs11_certificate_get_attributes
+gcr_pkcs11_certificate_lookup_issuer
+gcr_pkcs11_certificate_lookup_issuer_async
+gcr_pkcs11_certificate_lookup_issuer_finish
+<SUBSECTION Standard>
+gcr_pkcs11_certificate_get_type
+GCR_IS_PKCS11_CERTIFICATE
+GCR_IS_PKCS11_CERTIFICATE_CLASS
+GcrPkcs11CertificateClass
+GcrPkcs11CertificatePrivate
+</SECTION>
+
+<SECTION>
<FILE>gcr-trust</FILE>
GCR_PURPOSE_SERVER_AUTH
GCR_PURPOSE_CLIENT_AUTH
diff --git a/docs/reference/gcr/gcr.types b/docs/reference/gcr/gcr.types
index c52c795..dc87a0a 100644
--- a/docs/reference/gcr/gcr.types
+++ b/docs/reference/gcr/gcr.types
@@ -2,3 +2,4 @@ gcr_parser_get_type
gcr_certificate_get_type
gcr_importer_get_type
gcr_simple_certificate_get_type
+gcr_pkcs11_certificate_get_type
\ No newline at end of file
diff --git a/gcr/gcr-certificate.c b/gcr/gcr-certificate.c
index 06a7b46..26ef3ed 100644
--- a/gcr/gcr-certificate.c
+++ b/gcr/gcr-certificate.c
@@ -34,13 +34,18 @@
/**
* SECTION:gcr-certificate
* @title: GcrCertificate
- * @short_description: Represents a certificate.
+ * @short_description: Represents an X.509 certificate
*
- * This is an interface that represents an X509 certificate. Objects can
+ * This is an interface that represents an X.509 certificate. Objects can
* implement this interface to make a certificate usable with the GCR
* library.
- *
- * You can use #GcrSimpleCertificate to simply load a certificate.
+ *
+ * Various methods are available to parse out relevant bits of the certificate.
+ * However no verification of the validity of a certificate is done here. Use
+ * your favorite crypto library to do this.
+ *
+ * You can use #GcrSimpleCertificate to simply load a certificate for which
+ * you already have the raw certificate data.
*/
/*
@@ -107,7 +112,7 @@ certificate_info_load (GcrCertificate *cert)
/* Cache is invalid or non existent */
asn1 = egg_asn1x_create_and_decode (pkix_asn1_tab, "Certificate", der, n_der);
if (asn1 == NULL) {
- g_warning ("a derived class provided an invalid or unparseable X509 DER certificate data.");
+ g_warning ("a derived class provided an invalid or unparseable X.509 DER certificate data.");
return NULL;
}
@@ -271,9 +276,9 @@ gcr_certificate_get_type (void)
* @self: a #GcrCertificate
* @n_data: a pointer to a location to store the size of the resulting DER data.
*
- * Gets the raw DER data for an X509 certificate.
+ * Gets the raw DER data for an X.509 certificate.
*
- * Returns: raw DER data of the X509 certificate.
+ * Returns: raw DER data of the X.509 certificate.
**/
gconstpointer
gcr_certificate_get_der_data (GcrCertificate *self, gsize *n_data)
@@ -340,6 +345,17 @@ _gcr_certificate_get_issuer_const (GcrCertificate *self, gsize *n_data)
return egg_asn1x_get_raw_element (egg_asn1x_node (info->asn1, "tbsCertificate", "issuer", NULL), n_data);
}
+/**
+ * gcr_certificate_get_issuer_raw:
+ * @self: a #GcrCertificate
+ * @n_data: The length of the returned data.
+ *
+ * Get the raw DER data for the issuer DN of the certificate.
+ *
+ * The data should be freed by using g_free() when no longer required.
+ *
+ * Returns: allocated memory containing the raw issuer.
+ */
gpointer
gcr_certificate_get_issuer_raw (GcrCertificate *self, gsize *n_data)
{
@@ -352,6 +368,18 @@ gcr_certificate_get_issuer_raw (GcrCertificate *self, gsize *n_data)
return g_memdup (data, data ? *n_data : 0);
}
+/**
+ * gcr_certificate_is_issuer:
+ * @self: a #GcrCertificate
+ * @issuer: a possible issuer #GcrCertificate
+ *
+ * Check if @issuer could be the issuer of this certificate. This is done by
+ * comparing the relevant subject and issuer fields. No signature check is
+ * done. Proper verification of certificates must be done via a crypto
+ * library.
+ *
+ * Returns: whether @issuer could be the issuer of the certificate.
+ */
gboolean
gcr_certificate_is_issuer (GcrCertificate *self, GcrCertificate *issuer)
{
@@ -478,6 +506,17 @@ _gcr_certificate_get_subject_const (GcrCertificate *self, gsize *n_data)
return egg_asn1x_get_raw_element (egg_asn1x_node (info->asn1, "tbsCertificate", "subject", NULL), n_data);
}
+/**
+ * gcr_certificate_get_subject_raw:
+ * @self: a #GcrCertificate
+ * @n_data: The length of the returned data.
+ *
+ * Get the raw DER data for the subject DN of the certificate.
+ *
+ * The data should be freed by using g_free() when no longer required.
+ *
+ * Returns: allocated memory containing the raw subject.
+ */
gpointer
gcr_certificate_get_subject_raw (GcrCertificate *self, gsize *n_data)
{
diff --git a/gcr/gcr-pkcs11-certificate.c b/gcr/gcr-pkcs11-certificate.c
index 0a613a1..2ea8494 100644
--- a/gcr/gcr-pkcs11-certificate.c
+++ b/gcr/gcr-pkcs11-certificate.c
@@ -33,6 +33,21 @@
#include "pkcs11/pkcs11.h"
+/**
+ * SECTION:gcr-pkcs11-certificate
+ * @title: GcrPkcs11Certificate
+ * @short_description: A certificate loaded from PKCS\#11 storage
+ *
+ * A #GcrPkcs11Certificate is a certificate loaded from a PKCS\#11 storage.
+ * It is also a valid #GckObject and can be used as such.
+ *
+ * Use gcr_pkcs11_certificate_lookup_issuer() to lookup the issuer of a given
+ * certificate in the PKCS\#11 store.
+ *
+ * Various common PKCS\#11 certificate attributes are automatically loaded and
+ * are available via gcr_pkcs11_certificate_get_attributes().
+ */
+
enum {
PROP_0,
PROP_ATTRIBUTES
@@ -235,6 +250,11 @@ gcr_pkcs11_certificate_class_init (GcrPkcs11CertificateClass *klass)
gobject_class->set_property = gcr_pkcs11_certificate_set_property;
gobject_class->finalize = gcr_pkcs11_certificate_finalize;
+ /**
+ * GcrPkcs11Certificate:attributes:
+ *
+ * Automatically loaded attributes for this certificate.
+ */
g_object_class_install_property (gobject_class, PROP_ATTRIBUTES,
g_param_spec_boxed ("attributes", "Attributes", "The data displayed in the renderer",
GCK_TYPE_ATTRIBUTES, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
@@ -270,7 +290,14 @@ gcr_certificate_iface (GcrCertificateIface *iface)
* PUBLIC
*/
-
+/**
+ * gcr_pkcs11_certificate_get_attributes:
+ * @self: A #GcrPkcs11Certificate
+ *
+ * Access the automatically loaded attributes for this certificate.
+ *
+ * Returns: the certificate attributes
+ */
GckAttributes*
gcr_pkcs11_certificate_get_attributes (GcrPkcs11Certificate *self)
{
@@ -278,55 +305,106 @@ gcr_pkcs11_certificate_get_attributes (GcrPkcs11Certificate *self)
return self->pv->attrs;
}
+/**
+ * gcr_pkcs11_certificate_lookup_issuer:
+ * @certificate: a #GcrCertificate
+ * @cancellable: a #GCancellable
+ * @error: a #GError, or NULL
+ *
+ * Lookup a the issuer of a @certificate in the PKCS\#11 storage. The
+ * lookup is done using the issuer DN of the certificate. No certificate chain
+ * verification is done. Use a crypto library to make trust decisions.
+ *
+ * This call may block, see gcr_pkcs11_certificate_lookup_issuer() for the
+ * non-blocking version.
+ *
+ * Will return %NULL if no issuer certificate is found. Use @error to determine
+ * if an error occurred.
+ *
+ * Returns: a new #GcrPkcs11Certificate, or %NULL
+ */
GcrCertificate*
-gcr_pkcs11_certificate_lookup_issuer (GcrCertificate *cert, GCancellable *cancel,
+gcr_pkcs11_certificate_lookup_issuer (GcrCertificate *certificate, GCancellable *cancellable,
GError **error)
{
GckEnumerator *en;
GcrCertificate *issuer;
- en = prepare_lookup_certificate_issuer (cert);
+ g_return_val_if_fail (GCR_IS_CERTIFICATE (certificate), NULL);
+
+ en = prepare_lookup_certificate_issuer (certificate);
g_return_val_if_fail (en, FALSE);
- issuer = perform_lookup_certificate (en, cancel, error);
+ issuer = perform_lookup_certificate (en, cancellable, error);
g_object_unref (en);
return issuer;
}
+/**
+ * gcr_pkcs11_certificate_lookup_issuer_async:
+ * @certificate: a #GcrCertificate
+ * @cancellable: a #GCancellable
+ * @callback: a #GAsyncReadyCallback to call when the operation completes
+ * @user_data: the data to pass to callback function
+ *
+ * Lookup a the issuer of a @certificate in the PKCS\#11 storage. The
+ * lookup is done using the issuer DN of the certificate. No certificate chain
+ * verification is done. Use a crypto library to make trust decisions.
+ *
+ * When the operation is finished, callback will be called. You can then call
+ * gcr_pkcs11_certificate_lookup_issuer_finish() to get the result of the
+ * operation.
+ */
void
-gcr_pkcs11_certificate_lookup_issuer_async (GcrCertificate *cert, GCancellable *cancel,
+gcr_pkcs11_certificate_lookup_issuer_async (GcrCertificate *certificate, GCancellable *cancellable,
GAsyncReadyCallback callback, gpointer user_data)
{
GSimpleAsyncResult *async;
GckEnumerator *en;
- en = prepare_lookup_certificate_issuer (cert);
+ g_return_if_fail (GCR_IS_CERTIFICATE (certificate));
+
+ en = prepare_lookup_certificate_issuer (certificate);
g_return_if_fail (en);
async = g_simple_async_result_new (G_OBJECT (en), callback, user_data,
gcr_pkcs11_certificate_lookup_issuer_async);
g_simple_async_result_run_in_thread (async, thread_lookup_certificate,
- G_PRIORITY_DEFAULT, cancel);
+ G_PRIORITY_DEFAULT, cancellable);
g_object_unref (async);
g_object_unref (en);
}
+/**
+ * gcr_pkcs11_certificate_lookup_issuer_finish:
+ * @result: the #GAsyncResult passed to the callback
+ * @error: a #GError, or NULL
+ *
+ * Finishes an asynchronous operation started by
+ * gcr_pkcs11_certificate_lookup_issuer_async().
+ *
+ * Will return %NULL if no issuer certificate is found. Use @error to determine
+ * if an error occurred.
+ *
+ * Returns: a new #GcrPkcs11Certificate, or %NULL
+ */
GcrCertificate*
-gcr_pkcs11_certificate_lookup_issuer_finish (GAsyncResult *res, GError **error)
+gcr_pkcs11_certificate_lookup_issuer_finish (GAsyncResult *result, GError **error)
{
GcrCertificate *cert;
- g_return_val_if_fail (g_simple_async_result_is_valid (res,
- g_async_result_get_source_object (res),
+ g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
+ g_return_val_if_fail (g_simple_async_result_is_valid (result,
+ g_async_result_get_source_object (result),
gcr_pkcs11_certificate_lookup_issuer_async), NULL);
- if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (res), error))
+ if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result), error))
return NULL;
- cert = g_simple_async_result_get_op_res_gpointer (G_SIMPLE_ASYNC_RESULT (res));
+ cert = g_simple_async_result_get_op_res_gpointer (G_SIMPLE_ASYNC_RESULT (result));
if (cert != NULL)
g_object_ref (cert);
diff --git a/gcr/gcr-pkcs11-certificate.h b/gcr/gcr-pkcs11-certificate.h
index a90c860..e127691 100644
--- a/gcr/gcr-pkcs11-certificate.h
+++ b/gcr/gcr-pkcs11-certificate.h
@@ -59,16 +59,16 @@ GType gcr_pkcs11_certificate_get_type (void);
GckAttributes* gcr_pkcs11_certificate_get_attributes (GcrPkcs11Certificate *self);
-GcrCertificate* gcr_pkcs11_certificate_lookup_issuer (GcrCertificate *cert,
- GCancellable *cancel,
+GcrCertificate* gcr_pkcs11_certificate_lookup_issuer (GcrCertificate *certificate,
+ GCancellable *cancellable,
GError **error);
-void gcr_pkcs11_certificate_lookup_issuer_async (GcrCertificate *cert,
- GCancellable *cancel,
+void gcr_pkcs11_certificate_lookup_issuer_async (GcrCertificate *certificate,
+ GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
-GcrCertificate* gcr_pkcs11_certificate_lookup_issuer_finish (GAsyncResult *res,
+GcrCertificate* gcr_pkcs11_certificate_lookup_issuer_finish (GAsyncResult *result,
GError **error);
G_END_DECLS
diff --git a/gcr/gcr-simple-certificate.c b/gcr/gcr-simple-certificate.c
index fe1bc57..5ec7ff2 100644
--- a/gcr/gcr-simple-certificate.c
+++ b/gcr/gcr-simple-certificate.c
@@ -27,6 +27,19 @@
#include <string.h>
+/**
+ * SECTION:gcr-simple-certificate
+ * @title: GcrSimpleCertificate
+ * @short_description: A certificate loaded from a memory buffer
+ *
+ * An implementation of #GcrCertificate which loads a certificate from DER
+ * data already located in memory.
+ *
+ * To create a #GcrSimpleCertificate object use the
+ * gcr_simple_certificate_new() or gcr_simple_certificate_new_static()
+ * functions.
+ */
+
struct _GcrSimpleCertificatePrivate {
const guchar *data;
gsize n_data;
@@ -93,6 +106,16 @@ gcr_certificate_iface (GcrCertificateIface *iface)
* PUBLIC
*/
+/**
+ * gcr_simple_certificate_new:
+ * @data: The raw DER certificate data
+ * @n_data: The length of @data
+ *
+ * Create a new #GcrSimpleCertificate for the raw DER data. The @data memory is
+ * copied so you can dispose of it after this function returns.
+ *
+ * Returns: a new #GcrSimpleCertificate
+ */
GcrCertificate*
gcr_simple_certificate_new (gconstpointer data, gsize n_data)
{
@@ -108,6 +131,17 @@ gcr_simple_certificate_new (gconstpointer data, gsize n_data)
return GCR_CERTIFICATE (cert);
}
+/**
+ * gcr_simple_certificate_new_static:
+ * @data: The raw DER certificate data
+ * @n_data: The length of @data
+ *
+ * Create a new #GcrSimpleCertificate for the raw DER data. The @data memory is
+ * not copied and must persist until the #GcrSimpleCertificate object is
+ * destroyed.
+ *
+ * Returns: a new #GcrSimpleCertificate
+ */
GcrCertificate*
gcr_simple_certificate_new_static (gconstpointer data, gsize n_data)
{
diff --git a/gcr/gcr-trust.c b/gcr/gcr-trust.c
index 37fb2ea..324a950 100644
--- a/gcr/gcr-trust.c
+++ b/gcr/gcr-trust.c
@@ -36,7 +36,7 @@
/**
* SECTION:gcr-trust
* @title: Trust Storage and Lookups
- * @short_description: Used to store and lookup bits of information used for
+ * @short_description: Store and lookup bits of information used for
* verifying certificates.
*
* These functions provide access to stored information about which
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
