## Certificate utility functions

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

## Stability Level

Unstable, unless otherwise indicated

## Functions

gnutls_dh_params_t | inf_cert_util_create_dh_params ()
gnutls_dh_params_t | inf_cert_util_read_dh_params ()
gboolean | inf_cert_util_write_dh_params ()
gnutls_x509_privkey_t | inf_cert_util_create_private_key ()
gnutls_x509_privkey_t | inf_cert_util_read_private_key ()
gboolean | inf_cert_util_write_private_key ()
gnutls_x509_crt_t | inf_cert_util_create_certificate ()
gnutls_x509_crt_t | inf_cert_util_create_signed_certificate ()
gnutls_x509_crt_t | inf_cert_util_create_self_signed_certificate ()
GPtrArray * | inf_cert_util_read_certificate ()
gboolean | inf_cert_util_write_certificate ()
gchar * | inf_cert_util_write_certificate_mem ()
gboolean | inf_cert_util_write_certificate_with_key ()
gnutls_x509_crt_t | inf_cert_util_copy_certificate ()
GHashTable * | inf_cert_util_read_certificate_map ()
gboolean | inf_cert_util_write_certificate_map ()
gboolean | inf_cert_util_check_certificate_key ()
gboolean | inf_cert_util_compare_fingerprint ()
gchar * | inf_cert_util_get_dn ()
gchar * | inf_cert_util_get_dn_by_oid ()
gchar * | inf_cert_util_get_issuer_dn_by_oid ()
gchar * | inf_cert_util_get_hostname ()
gchar * | inf_cert_util_get_serial_number ()
gchar * | inf_cert_util_get_fingerprint ()
gchar * | inf_cert_util_get_activation_time ()
gchar * | inf_cert_util_get_expiration_time ()

## Types and Values

struct | InfCertUtilDescription

## 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`. |