EpcTls: Easy Publish and Consume Reference Manual

## EpcTls EpcTls — TLS support |

## Stability Level

Private, unless otherwise indicated

## Functions

gnutls_x509_crt_t | epc_tls_certificate_load ()
gnutls_x509_crt_t | epc_tls_certificate_new ()
gboolean | epc_tls_certificate_save ()
gnutls_x509_privkey_t | epc_tls_private_key_load ()
gnutls_x509_privkey_t | epc_tls_private_key_new ()
gboolean | epc_tls_private_key_save ()
gchar * | epc_tls_get_private_key_filename ()
gchar * | epc_tls_get_certificate_filename ()
gboolean | epc_tls_get_server_credentials ()

## Types and Values

#define | EPC_TLS_ERROR
#define | EPC_TLS_SECONDS_PER_DAY
#define | EPC_TLS_SECONDS_PER_HOUR
#define | EPC_TLS_SECONDS_PER_MINUTE

## Includes

    #include <libepc/shell.h>

## Description

Functions for handling TLS (X.509) certificates and keys.

## Functions

### epc_tls_certificate_load ()

    gnutls_x509_crt_t
    epc_tls_certificate_load (const gchar *filename,
                              GError **error);

Reads a PEM encoded X.509 certificate.

If the call was successful, the newly created certificate object is returned. This key can be used with functions of the GNU TLS library. If the call was not successful, it returns `NULL` and sets `error` . The error domain is EPC_TLS_ERROR. Error codes are taken from the GNU TLS library.

#### Parameters

filename | name of a file to read the certificate from, in the GLib file name encoding |
error | return location for a GError, or `NULL` |

#### Returns

The newly created certificate object, or `NULL`.

### epc_tls_certificate_new ()

    gnutls_x509_crt_t
    epc_tls_certificate_new (const gchar *hostname,
                             guint validity,
                             gnutls_x509_privkey_t key,
                             GError **error);

Creates a self signed X.509 certificate. The certificate will mention `hostname` as common name and as DNS host name, and it will be valid for `validity` days.

If the call was successful, the newly created certificate is returned. This certificate can be used with functions of the GNU TLS library. If the call was not successful, it returns `NULL` and sets `error` . The error domain is EPC_TLS_ERROR. Error codes are taken from the

GNU TLS library.

#### Parameters

hostname | the name of the host that will use this certificate |
validity | the number of days the certificate will remain valid |
key | the private key for signing the certificate |
error | return location for a GError, or `NULL` |

#### Returns

The newly created certificate object, or `NULL`.

### epc_tls_certificate_save ()

    gboolean
    epc_tls_certificate_save (gnutls_x509_crt_t certificate,
                              const gchar *filename,
                              GError **error);

Writes a PEM encoded X.509 certificate.

If the call was successful, it returns `TRUE`. If the call was not successful, it returns `FALSE` and sets `error` . The error domain is EPC_TLS_ERROR. Error codes are taken from the GNU TLS library.

#### Parameters

certificate | a X.509 certificate |
filename | name of a file to write the certificate to, in the GLib file name encoding |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on successful, `FALSE` if an error occurred

### epc_tls_private_key_load ()

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

Reads a PEM encoded private X.509 key.

If the call was successful, the newly created private key object is returned. This key can be used with functions of the GNU TLS library. If the call was not successful, it returns `NULL` and sets `error` . The error domain is EPC_TLS_ERROR. Error codes are taken from the GNU TLS library.

#### Parameters

filename | name of a file to read the key from, in the GLib file name encoding |
error | return location for a GError, or `NULL` |

#### Returns

The newly created key object, or `NULL`.

### epc_tls_private_key_new ()

    gnutls_x509_privkey_t
    epc_tls_private_key_new (GError **error);

Creates a self private X.509 key. Generating secure keys needs quite some time. Call `epc_tls_set_private_key_hooks()` to install hooks providing some feedback to your users. Key generation takes place in a separate background thread, whilst the calling thread waits in a GMainLoop. So for instance the GTK+ widget system remains responsible during that phase.

If the call was successful, the newly created key is returned. This certificate can be used with functions of the GNU TLS library. If the call was not successful, it returns `NULL` and sets `error` . The error domain is EPC_TLS_ERROR. Error codes are taken from the

GNU TLS library.

See also: EpcEntropyProgress

#### Parameters

error | return location for a GError, or `NULL` |

#### Returns

The newly created private key object, or `NULL`.

### epc_tls_private_key_save ()

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

Writes a PEM encoded private X.509 key.

If the call was successful, it returns `TRUE`. If the call was not successful, it returns `FALSE` and sets `error` . The error domain is EPC_TLS_ERROR. Error codes are taken from the GNU TLS library.

#### Parameters

key | a private X.509 key |
filename | name of a file to write the private key to, in the GLib file name encoding |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on successful, `FALSE` if an error occured

### epc_tls_get_private_key_filename ()

    gchar *
    epc_tls_get_private_key_filename (const gchar *hostname);

Queries the preferred location for storing private X.509 keys for the server identified by `hostname` . This file is located in the current user's XDG configuration folder (`g_get_user_config_dir()`). The filename also contains program's name when specified by `g_set_prgname()`.

#### Parameters

hostname | the server's host name |

#### Returns

The preferred private key location for `hostname` .

### epc_tls_get_certificate_filename ()

    gchar *
    epc_tls_get_certificate_filename (const gchar *hostname);

Queries the preferred location for storing X.509 certificates for the server identified by `hostname` . This file is located in the current user's XDG configuration folder (`g_get_user_config_dir()`). The filename also contains program's name when specified by `g_set_prgname()`.

#### Parameters

hostname | the server's host name |

#### Returns

The preferred certificate location for `hostname` .

### epc_tls_get_server_credentials ()

    gboolean
    epc_tls_get_server_credentials (const gchar *hostname,
                                    gchar **crtfile,
                                    gchar **keyfile,
                                    GError **error);

Searches or creates X.509 certificate and key for the server identified by `hostname` . This function uses `epc_tls_get_certificate_filename()` and `epc_tls_get_private_key_filename()` to locate existing certificates and keys. New certificates and keys are generated, when the files cannot be found, or the existing files contain invalid or expired information.

If the call was successful, it returns `TRUE`. If the call was not successful, it returns `FALSE` and sets `error` . The error domain is EPC_TLS_ERROR. Error codes are taken from the GNU TLS library.

#### Parameters

hostname | the server's host name |
crtfile | location for storing the certificate's filename in GLib filename encoding |
keyfile | location for storing the private key's filename in GLib filename encoding |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on successful, `FALSE` if an error occurred

## Types and Values

### EPC_TLS_ERROR

    #define EPC_TLS_ERROR (epc_tls_error_quark ())

Error domain for TLS operations. Errors in this domain will be GNU TLS error codes. See GError for information on error domains.

### EPC_TLS_SECONDS_PER_DAY

    #define EPC_TLS_SECONDS_PER_DAY     (24 * EPC_TLS_SECONDS_PER_HOUR)

The number of seconds per day.

### EPC_TLS_SECONDS_PER_HOUR

    #define EPC_TLS_SECONDS_PER_HOUR    (60 * EPC_TLS_SECONDS_PER_MINUTE)

The number of seconds per hour.

### EPC_TLS_SECONDS_PER_MINUTE

    #define EPC_TLS_SECONDS_PER_MINUTE  (60)

The number of seconds per minute.