GcrCertificate: Gcr Library Reference Manual

## GcrCertificate GcrCertificate — Represents an X.509 certificate |

## Functions

const guint8 * | gcr_certificate_get_der_data ()
gchar * | gcr_certificate_get_issuer_cn ()
gchar * | gcr_certificate_get_issuer_dn ()
gchar * | gcr_certificate_get_issuer_name ()
gchar * | gcr_certificate_get_issuer_part ()
guchar * | gcr_certificate_get_issuer_raw ()
gboolean | gcr_certificate_is_issuer ()
gchar * | gcr_certificate_get_subject_cn ()
gchar * | gcr_certificate_get_subject_dn ()
gchar * | gcr_certificate_get_subject_name ()
gchar * | gcr_certificate_get_subject_part ()
guchar * | gcr_certificate_get_subject_raw ()
GDate * | gcr_certificate_get_issued_date ()
GDate * | gcr_certificate_get_expiry_date ()
guchar * | gcr_certificate_get_serial_number ()
gchar * | gcr_certificate_get_serial_number_hex ()
guint | gcr_certificate_get_key_size ()
guchar * | gcr_certificate_get_fingerprint ()
gchar * | gcr_certificate_get_fingerprint_hex ()
gboolean | gcr_certificate_get_basic_constraints ()
void | gcr_certificate_mixin_class_init ()
void | gcr_certificate_mixin_emit_notify ()
void | gcr_certificate_mixin_get_property ()
#define | GCR_CERTIFICATE_MIXIN_IMPLEMENT_COMPARABLE
void | gcr_certificate_mixin_comparable_init ()
gint | gcr_certificate_compare ()
GIcon * | gcr_certificate_get_icon ()
gchar * | gcr_certificate_get_markup_text ()

## Properties

char * | description | Read
GDate * | expiry | Read
GIcon * | icon | Read
char * | issuer | Read
char * | label | Read
char * | markup | Read
char * | subject | Read

## Types and Values

| GcrCertificate
struct | GcrCertificateIface

## Object Hierarchy

        GInterface
        ╰── GcrCertificate

## Prerequisites

GcrCertificate requires GcrComparable and GObject.

## Known Implementations

GcrCertificate is implemented by GcrCertificateRenderer, GcrPkcs11Certificate and GcrSimpleCertificate.

## Description

This is an interface that represents an X.509 certificate. Objects can implement this interface to make a certificate usable with the GCR library.

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.

The GcrCertificate interface has several properties that must be implemented. You can use a mixin to implement these properties if desired. See the `gcr_certificate_mixin_class_init()` and `gcr_certificate_mixin_get_property()` functions.

All certificates are comparable. If implementing a GcrCertificate, you can use `GCR_CERTIFICATE_MIXIN_IMPLEMENT_COMPARABLE()` to implement the GcrComparable interface.

## Functions

### gcr_certificate_get_der_data ()

    const guint8 *
    gcr_certificate_get_der_data (GcrCertificate *self,
                                  gsize *n_data);

Gets the raw DER data for an X.509 certificate.

[virtual get_der_data]

#### Parameters

self | a GcrCertificate |
n_data | a pointer to a location to store the size of the resulting DER data. |

#### Returns

raw DER data of the X.509 certificate.

[transfer none][array length=n_data]

### gcr_certificate_get_issuer_cn ()

    gchar *
    gcr_certificate_get_issuer_cn (GcrCertificate *self);

Get the common name of the issuer of this certificate.

The string returned should be freed by the caller when no longer required.

#### Parameters

self | a GcrCertificate |

#### Returns

The allocated issuer CN, or `NULL` if no issuer CN present.

### gcr_certificate_get_issuer_dn ()

    gchar *
    gcr_certificate_get_issuer_dn (GcrCertificate *self);

Get the full issuer DN of the certificate as a (mostly) readable string.

The string returned should be freed by the caller when no longer required.

#### Parameters

self | a GcrCertificate |

#### Returns

The allocated issuer DN of the certificate.

### gcr_certificate_get_issuer_name ()

    gchar *
    gcr_certificate_get_issuer_name (GcrCertificate *self);

Get a name to represent the issuer of this certificate.

This will try to lookup the common name, orianizational unit, organization in that order.

#### Parameters

self | a GcrCertificate |

#### Returns

the allocated issuer name, or `NULL` if no issuer name

### gcr_certificate_get_issuer_part ()

    gchar *
    gcr_certificate_get_issuer_part (GcrCertificate *self,
                                     const gchar *part);

Get a part of the DN of the issuer of this certificate.

Examples of a `part` might be the 'OU' (organizational unit) or the 'CN' (common name). Only the value of that part of the DN is returned.

The string returned should be freed by the caller when no longer required.

#### Parameters

self | a GcrCertificate |
part | a DN type string or OID. |

#### Returns

the allocated part of the issuer DN, or `NULL` if no such part is present.

[nullable]

### gcr_certificate_get_issuer_raw ()

    guchar *
    gcr_certificate_get_issuer_raw (GcrCertificate *self,
                                    gsize *n_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.

#### Parameters

self | a GcrCertificate |
n_data | The length of the returned data. |

#### Returns

allocated memory containing the raw issuer.

[transfer full][array length=n_data]

### gcr_certificate_is_issuer ()

    gboolean
    gcr_certificate_is_issuer (GcrCertificate *self,
                               GcrCertificate *issuer);

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.

#### Parameters

self | a GcrCertificate |
issuer | a possible issuer GcrCertificate |

#### Returns

whether `issuer` could be the issuer of the certificate.

### gcr_certificate_get_subject_cn ()

    gchar *
    gcr_certificate_get_subject_cn (GcrCertificate *self);

Get the common name of the subject of this certificate.

The string returned should be freed by the caller when no longer required.

#### Parameters

self | a GcrCertificate |

#### Returns

The allocated subject CN, or `NULL` if no subject CN present.

### gcr_certificate_get_subject_dn ()

    gchar *
    gcr_certificate_get_subject_dn (GcrCertificate *self);

Get the full subject DN of the certificate as a (mostly) readable string.

The string returned should be freed by the caller when no longer required.

#### Parameters

self | a GcrCertificate |

#### Returns

The allocated subject DN of the certificate.

### gcr_certificate_get_subject_name ()

    gchar *
    gcr_certificate_get_subject_name (GcrCertificate *self);

Get a name to represent the subject of this certificate.

This will try to lookup the common name, orianizational unit, organization in that order.

#### Parameters

self | a GcrCertificate |

#### Returns

the allocated subject name, or `NULL` if no subject name

### gcr_certificate_get_subject_part ()

    gchar *
    gcr_certificate_get_subject_part (GcrCertificate *self,
                                      const gchar *part);

Get a part of the DN of the subject of this certificate.

Examples of a `part` might be the 'OU' (organizational unit) or the 'CN' (common name). Only the value of that part of the DN is returned.

The string returned should be freed by the caller when no longer required.

#### Parameters

self | a GcrCertificate |
part | a DN type string or OID. |

#### Returns

the allocated part of the subject DN, or `NULL` if no such part is present.

[nullable]

### gcr_certificate_get_subject_raw ()

    guchar *
    gcr_certificate_get_subject_raw (GcrCertificate *self,
                                     gsize *n_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.

#### Parameters

self | a GcrCertificate |
n_data | The length of the returned data. |

#### Returns

allocated memory containing the raw subject.

[transfer full][array length=n_data]

### gcr_certificate_get_issued_date ()

    GDate *
    gcr_certificate_get_issued_date (GcrCertificate *self);

Get the issued date of this certificate.

The GDate returned should be freed by the caller using `g_date_free()` when no longer required.

#### Parameters

self | a GcrCertificate |

#### Returns

An allocated issued date of this certificate.

### gcr_certificate_get_expiry_date ()

    GDate *
    gcr_certificate_get_expiry_date (GcrCertificate *self);

Get the expiry date of this certificate.

The GDate returned should be freed by the caller using `g_date_free()` when no longer required.

#### Parameters

self | a GcrCertificate |

#### Returns

An allocated expiry date of this certificate.

### gcr_certificate_get_serial_number ()

    guchar *
    gcr_certificate_get_serial_number (GcrCertificate *self,
                                       gsize *n_length);

Get the raw binary serial number of the certificate.

The caller should free the returned data using `g_free()` when it is no longer required.

#### Parameters

self | a GcrCertificate |
n_length | the length of the returned data. |

#### Returns

the raw binary serial number.

[array length=n_length]

### gcr_certificate_get_serial_number_hex ()

    gchar *
    gcr_certificate_get_serial_number_hex (GcrCertificate *self);

Get the serial number of the certificate as a hex string.

The caller should free the returned data using `g_free()` when it is no longer required.

#### Parameters

self | a GcrCertificate |

#### Returns

an allocated string containing the serial number as hex.

### gcr_certificate_get_key_size ()

    guint
    gcr_certificate_get_key_size (GcrCertificate *self);

Get the key size in bits of the public key represented by this certificate.

#### Parameters

self | a GcrCertificate |

#### Returns

The key size of the certificate.

### gcr_certificate_get_fingerprint ()

    guchar *
    gcr_certificate_get_fingerprint (GcrCertificate *self,
                                     GChecksumType type,
                                     gsize *n_length);

Calculate the fingerprint for this certificate.

The caller should free the returned data using `g_free()` when it is no longer required.

#### Parameters

self | a GcrCertificate |
type | the type of algorithm for the fingerprint. |
n_length | The length of the resulting fingerprint. |

#### Returns

the raw binary fingerprint.

[array length=n_length]

### gcr_certificate_get_fingerprint_hex ()

    gchar *
    gcr_certificate_get_fingerprint_hex (GcrCertificate *self,
                                         GChecksumType type);

Calculate the fingerprint for this certificate, and return it as a hex string.

The caller should free the returned data using `g_free()` when it is no longer required.

#### Parameters

self | a GcrCertificate |
type | the type of algorithm for the fingerprint. |

#### Returns

an allocated hex string which contains the fingerprint.

### gcr_certificate_get_basic_constraints ()

    gboolean
    gcr_certificate_get_basic_constraints (GcrCertificate *self,
                                           gboolean *is_ca,
                                           gint *path_len);

Get the basic constraints for the certificate if present. If `FALSE` is returned then no basic constraints are present and the `is_ca` and `path_len` arguments are not changed.

#### Parameters

self | the certificate |
is_ca | location to place a `TRUE` if is an authority. | [out][optional]
path_len | location to place the max path length. | [out][optional]

#### Returns

whether basic constraints are present or not

### gcr_certificate_mixin_class_init ()

    void
    gcr_certificate_mixin_class_init (GObjectClass *object_class);

Initialize the certificate mixin for the class. This mixin implements the various required properties for the certificate.

Call this function near the end of your derived class_init function. The derived class must implement the GcrCertificate interface.

[skip]

#### Parameters

object_class | The GObjectClass for this class |

### gcr_certificate_mixin_emit_notify ()

    void
    gcr_certificate_mixin_emit_notify (GcrCertificate *self);

Implementers of the GcrCertificate mixin should call this function to notify when the certificate has changed to emit notifications on the various properties.

#### Parameters

self | the GcrCertificate |

### gcr_certificate_mixin_get_property ()

    void
    gcr_certificate_mixin_get_property (GObject *obj,
                                        guint prop_id,
                                        GValue *value,
                                        GParamSpec *pspec);

Implementation to get various required certificate properties. This should be called from your derived class get_property function, or used as a get_property virtual function.

Example of use as called from derived class get_property function:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    static void
    my_get_property (GObject *obj, guint prop_id, GValue *value, GParamSpec *pspec)
    {
    	switch (prop_id) {

    	...

    	default:
    		gcr_certificate_mixin_get_property (obj, prop_id, value, pspec);
    		break;
    	}
    }

Example of use as get_property function:

    1
    2
    3
    4
    5
    6
    7
    8
    static void
    my_class_init (MyClass *klass)
    {
    	GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
    	gobject_class->get_property = gcr_certificate_mixin_get_property;

    	...
    }

[skip]

#### Parameters

obj | The object |
prop_id | The property id |
value | The value to fill in. |
pspec | The param specification. |

### GCR_CERTIFICATE_MIXIN_IMPLEMENT_COMPARABLE

    #define             GCR_CERTIFICATE_MIXIN_IMPLEMENT_COMPARABLE()

Implement the GcrComparable interface. Use this macro like this:

    1
    2
    3
    4
    G_DEFINE_TYPE_WITH_CODE (MyCertificate, my_certificate, G_TYPE_OBJECT,
    GCR_CERTIFICATE_MIXIN_IMPLEMENT_COMPARABLE ();
    G_IMPLEMENT_INTERFACE (GCR_TYPE_CERTIFICATE, my_certificate_iface_init);
    );

### gcr_certificate_mixin_comparable_init ()

    void
    gcr_certificate_mixin_comparable_init (GcrComparableIface *iface);

Initialize a GcrComparableIface to compare the current certificate. In general it's easier to use the `GCR_CERTIFICATE_MIXIN_IMPLEMENT_COMPARABLE()` macro instead of this function.

[skip]

#### Parameters

iface | The interface |

### gcr_certificate_compare ()

    gint
    gcr_certificate_compare (GcrComparable *first,
                             GcrComparable *other);

Compare one certificate against another. If the certificates are equal then zero is returned. If one certificate is `NULL` or not a certificate, then a non-zero value is returned.

The return value is useful in a stable sort, but has no user logical meaning.

#### Parameters

first | the certificate to compare. | [nullable]
other | the certificate to compare against. | [nullable]

#### Returns

zero if the certificates match, non-zero otherwise.

### gcr_certificate_get_icon ()

    GIcon *
    gcr_certificate_get_icon (GcrCertificate *self);

Get the icon for a certificate.

[skip]

#### Parameters

self | The certificate |

#### Returns

the icon for this certificate, which should be released with `g_object_unref()`.

[transfer full]

### gcr_certificate_get_markup_text ()

    gchar *
    gcr_certificate_get_markup_text (GcrCertificate *self);

Calculate a GMarkup string for displaying this certificate.

#### Parameters

self | a certificate |

#### Returns

the markup string.

[transfer full]

## Types and Values

### GcrCertificate

    typedef struct _GcrCertificate GcrCertificate;

An object which holds a certificate.

### struct GcrCertificateIface

    struct GcrCertificateIface {
    	GTypeInterface parent;

    	/**
    	 * GcrCertificateIface::get_der_data:
    	 * @self: a #GcrCertificate
    	 * @n_data: (out): a location to store the size of the resulting DER data.
    	 *
    	 * Implemented to return the raw DER data for an X.509 certificate. The data
    	 * should be owned by the #GcrCertificate object.
    	 *
    	 * Returns: (transfer none) (array length=n_data): raw DER data of the X.509 certificate
    	 */
    	const guint8 * (* get_der_data) (GcrCertificate *self,
    	                                 gsize *n_data);
    };

The interface that implementors of GcrCertificate must implement.

#### Members

GTypeInterface `parent`; | the parent interface type |
`get_der_data` () | a method which returns the RAW der data of the certificate |

## Property Details

### The `“description”` property

      “description”              char *

A readable description for this certificate

Owner: GcrCertificate

Flags: Read

Default value: ""

### The `“expiry”` property

      “expiry”                   GDate *

The expiry date of the certificate

Owner: GcrCertificate

Flags: Read

### The `“icon”` property

      “icon”                     GIcon *

An icon representing the certificate

Owner: GcrCertificate

Flags: Read

### The `“issuer”` property

      “issuer”                   char *

Common name part of the certificate issuer

Owner: GcrCertificate

Flags: Read

Default value: ""

### The `“label”` property

      “label”                    char *

A readable label for this certificate.

Owner: GcrCertificate

Flags: Read

Default value: ""

### The `“markup”` property

      “markup”                   char *

GLib markup to describe the certificate

Owner: GcrCertificate

Flags: Read

Default value: ""

### The `“subject”` property

      “subject”                  char *

Common name part of the certificate subject

Owner: GcrCertificate

Flags: Read

Default value: ""