Certificate utility functions

Certificate utility functions — Helper functions to read and write information from X.509 certificates.

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libinfinity/common/inf-cert-util.h>

struct              InfCertUtilDescription;
gnutls_dh_params_t  inf_cert_util_create_dh_params      (GError **error);
gnutls_dh_params_t  inf_cert_util_read_dh_params        (const gchar *filename,
                                                         GError **error);
gboolean            inf_cert_util_write_dh_params       (gnutls_dh_params_t params,
                                                         const gchar *filename,
                                                         GError **error);
gnutls_x509_privkey_t inf_cert_util_create_private_key  (gnutls_pk_algorithm_t algo,
                                                         unsigned int bits,
                                                         GError **error);
gnutls_x509_privkey_t inf_cert_util_read_private_key    (const gchar *filename,
                                                         GError **error);
gboolean            inf_cert_util_write_private_key     (gnutls_x509_privkey_t key,
                                                         const gchar *filename,
                                                         GError **error);
gnutls_x509_crt_t   inf_cert_util_create_certificate    (gnutls_x509_privkey_t key,
                                                         const InfCertUtilDescription *desc,
                                                         GError **error);
gnutls_x509_crt_t   inf_cert_util_create_signed_certificate
                                                        (gnutls_x509_privkey_t key,
                                                         const InfCertUtilDescription *desc,
                                                         gnutls_x509_crt_t sign_cert,
                                                         gnutls_x509_privkey_t sign_key,
                                                         GError **error);
gnutls_x509_crt_t   inf_cert_util_create_self_signed_certificate
                                                        (gnutls_x509_privkey_t key,
                                                         const InfCertUtilDescription *desc,
                                                         GError **error);
GPtrArray *         inf_cert_util_read_certificate      (const gchar *filename,
                                                         GPtrArray *current,
                                                         GError **error);
gboolean            inf_cert_util_write_certificate     (gnutls_x509_crt_t *certs,
                                                         guint n_certs,
                                                         const gchar *filename,
                                                         GError **error);
gchar *             inf_cert_util_write_certificate_mem (gnutls_x509_crt_t *certs,
                                                         guint n_certs,
                                                         GError **error);
gboolean            inf_cert_util_write_certificate_with_key
                                                        (gnutls_x509_privkey_t key,
                                                         gnutls_x509_crt_t *certs,
                                                         guint n_certs,
                                                         const gchar *filename,
                                                         GError **error);
gnutls_x509_crt_t   inf_cert_util_copy_certificate      (gnutls_x509_crt_t src,
                                                         GError **error);
gboolean            inf_cert_util_check_certificate_key (gnutls_x509_crt_t cert,
                                                         gnutls_x509_privkey_t key);
gchar *             inf_cert_util_get_dn                (gnutls_x509_crt_t cert);
gchar *             inf_cert_util_get_dn_by_oid         (gnutls_x509_crt_t cert,
                                                         const char *oid,
                                                         unsigned int index);
gchar *             inf_cert_util_get_issuer_dn_by_oid  (gnutls_x509_crt_t cert,
                                                         const char *oid,
                                                         unsigned int index);
gchar *             inf_cert_util_get_hostname          (gnutls_x509_crt_t cert);
gchar *             inf_cert_util_get_serial_number     (gnutls_x509_crt_t cert);
gchar *             inf_cert_util_get_fingerprint       (gnutls_x509_crt_t cert,
                                                         gnutls_digest_algorithm_t algo);
gchar *             inf_cert_util_get_activation_time   (gnutls_x509_crt_t cert);
gchar *             inf_cert_util_get_expiration_time   (gnutls_x509_crt_t cert);

Description

These functions are utility functions that can be used when dealing with certificates, private key and Diffie-Hellman parameters for key exchange. The functionality these functions provide include creating, reading and writing these data structures to disk in PEM format, or to read values from certificates.

Details

struct InfCertUtilDescription

struct InfCertUtilDescription {
  guint64 validity;

  const gchar* dn_common_name;

  const gchar* san_dnsname;
};

This structure contains information that is used to generate a certificate with the inf_cert_util_create_certificate(), inf_cert_util_create_self_signed_certificate() and inf_cert_util_create_signed_certificate() functions.

guint64 validity;

The number of seconds the certificate is valid, beginning from the current time.

const gchar *dn_common_name;

The common name of the certificate, or NULL.

const gchar *san_dnsname;

The DNS name of the certificate, or NULL.

inf_cert_util_create_dh_params ()

gnutls_dh_params_t  inf_cert_util_create_dh_params      (GError **error);

Creates new, random Diffie-Hellman parameters.

error :

Location to store error information, if any.

Returns :

New dhparams to be freed with gnutls_dh_params_deinit(), or NULL in case of error.

inf_cert_util_read_dh_params ()

gnutls_dh_params_t  inf_cert_util_read_dh_params        (const gchar *filename,
                                                         GError **error);

Reads the Diffie-Hellman parameters located at filename into a gnutls_dh_params_t structure.

filename :

A path to a DH parameters file.

error :

Location to store error information, if any.

Returns :

New dhparams to be freed with gnutls_dh_params_deinit(), or NULL in case of error.

inf_cert_util_write_dh_params ()

gboolean            inf_cert_util_write_dh_params       (gnutls_dh_params_t params,
                                                         const gchar *filename,
                                                         GError **error);

Writes the given Diffie-Hellman parameters to the given path on the filesystem. If an error occurs, error is set and FALSE is returned.

params :

An initialized gnutls_dh_params_t structure.

filename :

The path at which so store params.

error :

Location to store error information, if any.

Returns :

TRUE on success or FALSE otherwise.

inf_cert_util_create_private_key ()

gnutls_x509_privkey_t inf_cert_util_create_private_key  (gnutls_pk_algorithm_t algo,
                                                         unsigned int bits,
                                                         GError **error);

Generates a new, random X.509 private key. This function is a thin wrapper around gnutls_x509_privkey_generate() which provides GError-style error reporting.

algo :

The key algorithm to use (RSA or DSA).

bits :

The length of the key to generate.

error :

Location to store error information, if any.

Returns :

A new key to be freed with gnutls_x509_privkey_deinit(), or NULL if an error occured.

inf_cert_util_read_private_key ()

gnutls_x509_privkey_t inf_cert_util_read_private_key    (const gchar *filename,
                                                         GError **error);

Reads the key located at filename into a gnutls_x509_privkey_t structure.

filename :

A path to a X.509 private key file

error :

Location for error information, if any.

Returns :

A private key. Free with gnutls_x509_privkey_deinit().

inf_cert_util_write_private_key ()

gboolean            inf_cert_util_write_private_key     (gnutls_x509_privkey_t key,
                                                         const gchar *filename,
                                                         GError **error);

Writes key to the location specified by filename on the filesystem. If an error occurs, the function returns FALSE and error is set.

key :

An initialized gnutls_x509_privkey_t structure.

filename :

The path at which so store the key.

error :

Location to store error information, if any.

Returns :

TRUE on success, FALSE otherwise.

inf_cert_util_create_certificate ()

gnutls_x509_crt_t   inf_cert_util_create_certificate    (gnutls_x509_privkey_t key,
                                                         const InfCertUtilDescription *desc,
                                                         GError **error);

Creates a new X.509 certificate with the given key and properties. If an error occurs the function returns NULL and error is set. The returned certificate will not be signed.

key :

The private key to be used for the new certificate.

desc :

The certificate properties.

error :

Location to store error information, if any, or NULL.

Returns :

A new gnutls_x509_crt_t, or NULL. Free with gnutls_x509_crt_deinit() when no longer needed.

inf_cert_util_create_signed_certificate ()

gnutls_x509_crt_t   inf_cert_util_create_signed_certificate
                                                        (gnutls_x509_privkey_t key,
                                                         const InfCertUtilDescription *desc,
                                                         gnutls_x509_crt_t sign_cert,
                                                         gnutls_x509_privkey_t sign_key,
                                                         GError **error);

Creates a new X.509 certificate with the given key and properties. If an error occurs the function returns NULL and error is set. The returned certificate will be signed by sign_cert.

key :

The private key to be used for the new certificate.

desc :

The certificate properties.

sign_cert :

A certificate used to sign the newly created certificate.

sign_key :

The private key for sign_cert.

error :

Location to store error information, if any, or NULL.

Returns :

A new gnutls_x509_crt_t, or NULL. Free with gnutls_x509_crt_deinit() when no longer needed.

inf_cert_util_create_self_signed_certificate ()

gnutls_x509_crt_t   inf_cert_util_create_self_signed_certificate
                                                        (gnutls_x509_privkey_t key,
                                                         const InfCertUtilDescription *desc,
                                                         GError **error);

Creates a new X.509 certificate with the given key and properties. If an error occurs the function returns NULL and error is set. The returned certificate will be signed by itself.

key :

The private key to be used for the new certificate.

desc :

The certificate properties.

error :

Location to store error information, if any, or NULL.

Returns :

A new gnutls_x509_crt_t, or NULL. Free with gnutls_x509_crt_deinit() when no longer needed.

inf_cert_util_read_certificate ()

GPtrArray *         inf_cert_util_read_certificate      (const gchar *filename,
                                                         GPtrArray *current,
                                                         GError **error);

Loads X.509 certificates in PEM format from the file at filename. There can be any number of certificates in the file. If current is not NULL, the new certificates are appended to the array. Otherwise, a new array with the read certificates is returned.

If an error occurs, the function returns NULL and error is set. If current is non-NULL and the function succeeds, the return value is the same as current.

filename :

A path to a X.509 certificate file.

current :

An array of gnutls_x509_crt_t objects, or NULL.

error :

Location to store error information, if any.

Returns :

An array of the read certificates, or NULL on error.

inf_cert_util_write_certificate ()

gboolean            inf_cert_util_write_certificate     (gnutls_x509_crt_t *certs,
                                                         guint n_certs,
                                                         const gchar *filename,
                                                         GError **error);

This function writes the certificates in the array certs to disk, in PEM format. If an error occurs the function returns FALSE and error is set.

certs :

An array of gnutls_x509_crt_t objects.

n_certs :

Number of certificates in the error.

filename :

The path at which to store the certificates.

error :

Location to store error information, if any.

Returns :

TRUE on success or FALSE otherwise.

inf_cert_util_write_certificate_mem ()

gchar *             inf_cert_util_write_certificate_mem (gnutls_x509_crt_t *certs,
                                                         guint n_certs,
                                                         GError **error);

This function writes the certificates in the array certs into memory, in PEM format. If an error occurs the function returns NULL and error is set.

certs :

An array of gnutls_x509_crt_t objects.

n_certs :

Number of certificates in the error.

error :

Location to store error information, if any.

Returns :

A string with PEM-encoded certificate data, or NULL on error. Free with g_free().

inf_cert_util_write_certificate_with_key ()

gboolean            inf_cert_util_write_certificate_with_key
                                                        (gnutls_x509_privkey_t key,
                                                         gnutls_x509_crt_t *certs,
                                                         guint n_certs,
                                                         const gchar *filename,
                                                         GError **error);

This function writes both the private key key as well as the certificates in the array certs to disk, in PEM format. If an error occurs the function returns FALSE and error is set.

key :

An initialized gnutls_x509_privkey_t structure.

certs :

An array of gnutls_x509_crt_t objects.

n_certs :

Number of certificates in the error.

filename :

The path at which to store the certificates.

error :

Location to store error information, if any.

Returns :

TRUE on success or FALSE otherwise.

inf_cert_util_copy_certificate ()

gnutls_x509_crt_t   inf_cert_util_copy_certificate      (gnutls_x509_crt_t src,
                                                         GError **error);

Creates a copy of the certificate src and returns the copy. If the function fails FALSE is returned and error is set.

src :

The certificate to copy.

error :

Location to store error information, if any.

Returns :

A copy of src, or NULL on error. Free with gnutls_x509_crt_deinit() when no longer in use.

inf_cert_util_check_certificate_key ()

gboolean            inf_cert_util_check_certificate_key (gnutls_x509_crt_t cert,
                                                         gnutls_x509_privkey_t key);

This function returns TRUE if key is the private key belonging to cert, or FALSE otherwise.

cert :

The certificate to be checked.

key :

The private key to be checked.

Returns :

TRUE if cert was signed with key, or FALSE otherwise.

inf_cert_util_get_dn ()

gchar *             inf_cert_util_get_dn                (gnutls_x509_crt_t cert);

Retrieves the full distinguished name (DN) from the certificate, allocating memory for the return value.

cert :

An initialized gnutls_x509_crt_t.

Returns :

The DN of the certificate. Free with g_free() after use.

inf_cert_util_get_dn_by_oid ()

gchar *             inf_cert_util_get_dn_by_oid         (gnutls_x509_crt_t cert,
                                                         const char *oid,
                                                         unsigned int index);

Retrieves the given item from the certificate. This function is a thin wrapper around gnutls_x509_crt_get_dn_by_oid(), allocating memory for the return value. The function returns NULL if there is no such entry in the certificate.

cert :

An initialized gnutls_x509_crt_t.

oid :

The name of the requested entry.

index :

Index of the entry to retrieve.

Returns :

The certificate entry, or NULL if it is not present. Free with g_free() after use.

inf_cert_util_get_issuer_dn_by_oid ()

gchar *             inf_cert_util_get_issuer_dn_by_oid  (gnutls_x509_crt_t cert,
                                                         const char *oid,
                                                         unsigned int index);

Retrieves the given item from the issuer of the certificate. This function is a thin wrapper around gnutls_x509_crt_get_issuer_dn_by_oid(), allocating memory for the return value. The functions returns NULL if there is no such entry in the certificate.

cert :

An initialized gnutls_x509_crt_t.

oid :

The name of the requested entry.

index :

Index of the entry to retrieve.

Returns :

The certificate entry, or NULL if it is not present. Free with g_free() after use.

inf_cert_util_get_hostname ()

gchar *             inf_cert_util_get_hostname          (gnutls_x509_crt_t cert);

Attempts to read the hostname of a certificate. This is done by looking at the DNS name and IP address SANs. If both are not available, the common name of the certificate is returned.

cert :

An initialized gnutls_x509_crt_t.

Returns :

The best guess for the certificate's hostname, or NULL when it cannot be retrieved. Free with g_free() after use.

inf_cert_util_get_serial_number ()

gchar *             inf_cert_util_get_serial_number     (gnutls_x509_crt_t cert);

Read the serial number of a certificate and return it in hexadecimal format. If the serial number cannot be read NULL is returned.

cert :

An initialized gnutls_x509_crt_t.

Returns :

The serial number of the certificate, or NULL. Free with g_free() after use.

inf_cert_util_get_fingerprint ()

gchar *             inf_cert_util_get_fingerprint       (gnutls_x509_crt_t cert,
                                                         gnutls_digest_algorithm_t algo);

Returns the fingerprint of the certificate hashed with the specified algorithm, in hexadecimal format. If the fingerprint cannot be read NULL is returned.

cert :

An initialized gnutls_x509_crt_t.

algo :

The hashing algorithm to use.

Returns :

The fingerprint of the certificate, or NULL. Free with g_free() after use.

inf_cert_util_get_activation_time ()

gchar *             inf_cert_util_get_activation_time   (gnutls_x509_crt_t cert);

Returns the activation time of the certificate as a string in human-readable format. If the activation time cannot be read NULL is returned.

cert :

An initialized gnutls_x509_crt_t.

Returns :

The activation time of the certificate, or NULL. Free with g_free() after use.

inf_cert_util_get_expiration_time ()

gchar *             inf_cert_util_get_expiration_time   (gnutls_x509_crt_t cert);

Returns the expiration time of the certificate as a string in human-readable format. If the expiration time cannot be read NULL is returned.

cert :

An initialized gnutls_x509_crt_t.

Returns :

The expiration time of the certificate, or NULL. Free with g_free() after use.