## EpcTls EpcTls — TLS support |

## Stability Level

Private, unless otherwise indicated

## Synopsis

    #include <libepc/shell.h>

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

    gnutls_x509_crt_t   epc_tls_certificate_load            (const gchar *filename,
                                                             GError **error);
    gnutls_x509_crt_t   epc_tls_certificate_new             (const gchar *hostname,
                                                             guint validity,
                                                             gnutls_x509_privkey_t key,
                                                             GError **error);
    gboolean            epc_tls_certificate_save            (gnutls_x509_crt_t certificate,
                                                             const gchar *filename,
                                                             GError **error);

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

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

## Description

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

## Details

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

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

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

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

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

`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

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

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

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

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

`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