From 1589aeaa30ec641c63f1b1525eb566f3a780bf51 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Tue, 7 Dec 2010 19:30:35 +0000 Subject: [PATCH] [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 | 51 +++++++++++++++--- 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, 221 insertions(+), 44 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 @@ - - gcr Reference Manual - - for gcr [VERSION] - The latest version of this documentation can be found on-line at - http://[SERVER]/gcr/. - - + + gcr Reference Manual + + for gcr [VERSION] + The latest version of this documentation can be found on-line at + http://[SERVER]/gcr/. + + + + + Certificates + + + + + + + Storage + + + + + - - [Insert title here] - - - - - - - - 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
gcr-certificate -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
@@ -114,11 +117,12 @@ GCR_IMPORTER_GET_CLASS
gcr-simple-certificate -GcrSimpleCertificatePrivate GcrSimpleCertificate GcrSimpleCertificate gcr_simple_certificate_new +gcr_simple_certificate_new_static +GcrSimpleCertificatePrivate GCR_SIMPLE_CERTIFICATE GCR_IS_SIMPLE_CERTIFICATE GCR_TYPE_SIMPLE_CERTIFICATE @@ -129,6 +133,22 @@ GCR_SIMPLE_CERTIFICATE_GET_CLASS
+gcr-pkcs11-certificate +GcrPkcs11Certificate +GcrPkcs11Certificate +gcr_pkcs11_certificate_get_attributes +gcr_pkcs11_certificate_lookup_issuer +gcr_pkcs11_certificate_lookup_issuer_async +gcr_pkcs11_certificate_lookup_issuer_finish + +gcr_pkcs11_certificate_get_type +GCR_IS_PKCS11_CERTIFICATE +GCR_IS_PKCS11_CERTIFICATE_CLASS +GcrPkcs11CertificateClass +GcrPkcs11CertificatePrivate +
+ +
gcr-trust 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 d17d454..3f49e62 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 cd76a7e..dfa6023 100644 --- a/gcr/gcr-simple-certificate.c +++ b/gcr/gcr-simple-certificate.c @@ -27,6 +27,19 @@ #include +/** + * 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 -- 2.7.4