Certificate utility functions

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

Stability Level

Unstable, unless otherwise indicated

Functions

Types and Values

Includes

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

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.

Functions

inf_cert_util_create_dh_params ()

gnutls_dh_params_t
inf_cert_util_create_dh_params (GError **error);

Creates new, random Diffie-Hellman parameters.

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.

[transfer full]


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.

Parameters

filename

A path to a DH parameters file.

[type filename]

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.

[transfer full]


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.

Parameters

params

An initialized gnutls_dh_params_t structure.

[transfer none]

filename

The path at which so store params .

[type filename]

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.

Parameters

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 occurred.

[transfer full]


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.

Parameters

filename

A path to a X.509 private key file.

[type filename]

error

Location for error information, if any.

 

Returns

A private key. Free with gnutls_x509_privkey_deinit().

[transfer full]


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.

Parameters

key

An initialized gnutls_x509_privkey_t structure.

[transfer none]

filename

The path at which so store the key.

[type filename]

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.

Parameters

key

The private key to be used for the new certificate.

[transfer none]

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.

[transfer full]


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 .

Parameters

key

The private key to be used for the new certificate.

[transfer none]

desc

The certificate properties.

 

sign_cert

A certificate used to sign the newly created certificate.

[transfer none]

sign_key

The private key for sign_cert .

[transfer none]

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.

[transfer full]


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.

Parameters

key

The private key to be used for the new certificate.

[transfer none]

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.

[transfer full]


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 .

Parameters

filename

A path to a X.509 certificate file.

[type filename]

current

An array of gnutls_x509_crt_t objects, or NULL.

[element-type gnutls_x509_crt_t][allow-none][transfer full]

error

Location to store error information, if any.

 

Returns

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

[transfer full][element-type gnutls_x509_crt_t]


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.

Parameters

certs

An array of gnutls_x509_crt_t objects.

[array length=n_certs][transfer none]

n_certs

Number of certificates in the error.

 

filename

The path at which to store the certificates.

[type filename]

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.

Parameters

certs

An array of gnutls_x509_crt_t objects.

[transfer none]

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().

[transfer full]


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.

Parameters

key

An initialized gnutls_x509_privkey_t structure.

[transfer none]

certs

An array of gnutls_x509_crt_t objects.

[transfer none][array length=n_certs]

n_certs

Number of certificates in the error.

 

filename

The path at which to store the certificates.

[type filename]

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.

Parameters

src

The certificate to copy.

[transfer none]

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.

[transfer full]


inf_cert_util_read_certificate_map ()

GHashTable *
inf_cert_util_read_certificate_map (const gchar *filename,
                                    GError **error);

Reads a certificate map, i.e. a mapping from hostname to certificate, from the given file. The format of the file is expected to be one entry per line, where each entry consists of the hostname, then a colon character (':'), and then the base64-encoded certificate in DER format.

If the file with the given filename does not exist, an empty hash table is returned and the function succeeds.

Parameters

filename

The filename to read the certificate map from.

 

error

Location to store error information, if any.

 

Returns

A hash table with the read mapping, or NULL on error. Use g_hash_table_unref() to free the hash table when no longer needed.

[transfer container][element-type string gnutls_x509_crt_t]


inf_cert_util_write_certificate_map ()

gboolean
inf_cert_util_write_certificate_map (GHashTable *cert_map,
                                     const gchar *filename,
                                     GError **error);

Writes the given certificate mapping to a file with the given filename. See inf_cert_util_read_certificate_map() for the format of the written file. If an error occurs, error is set and the function returns FALSE.

This function can be useful to implement trust-on-first-use (TOFU) semantics.

Parameters

cert_map

A certificate mapping, i.e. a hash table mapping hostname strings to gnutls_x509_crt_t instances.

[transfer none][element-type string gnutls_x509_crt_t]

filename

The name of the file to write the mapping to.

 

error

Location to store error information, if any.

 

Returns

TRUE on success or FALSE on error.


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.

Parameters

cert

The certificate to be checked.

[transfer none]

key

The private key to be checked.

[transfer none]

Returns

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


inf_cert_util_compare_fingerprint ()

gboolean
inf_cert_util_compare_fingerprint (gnutls_x509_crt_t cert1,
                                   gnutls_x509_crt_t cert2,
                                   GError **error);

Checks whether the SHA-256 fingerprints of the two given certificates are identical or not. If a fingerprint cannot be obtained, the function returns FALSE and error is set.

Parameters

cert1

The first certificate to compare.

 

cert2

The second certificate to compare.

 

error

Location to store error information, if any.

 

Returns

Whether the two certificates have identical fingerprints. Returns FALSE on error.


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.

Parameters

cert

An initialized gnutls_x509_crt_t.

[transfer none]

Returns

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

[transfer full]


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.

Parameters

cert

An initialized gnutls_x509_crt_t.

[transfer none]

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.

[transfer full]


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.

Parameters

cert

An initialized gnutls_x509_crt_t.

[transfer none]

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.

[transfer full]


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.

Parameters

cert

An initialized gnutls_x509_crt_t.

[transfer none]

Returns

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

[transfer full][allow-none]


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.

Parameters

cert

An initialized gnutls_x509_crt_t.

[transfer none]

Returns

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

[transfer full]


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.

Parameters

cert

An initialized gnutls_x509_crt_t.

[transfer none]

algo

The hashing algorithm to use.

 

Returns

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

[transfer full]


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.

Parameters

cert

An initialized gnutls_x509_crt_t.

[transfer none]

Returns

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

[transfer full]


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.

Parameters

cert

An initialized gnutls_x509_crt_t.

[transfer none]

Returns

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

[transfer full]

Types and Values

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.

Members

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.