## LmSSL LmSSL — SSL struct for SSL support in Loudmouth |

## Synopsis

                        LmSSL;
    enum                LmCertificateStatus;
    enum                LmSSLStatus;
    enum                LmSSLResponse;
    LmSSLResponse       (*LmSSLFunction)                    (LmSSL *ssl,
                                                             LmSSLStatus status,
                                                             gpointer user_data);
    LmSSL *             lm_ssl_new                          (const gchar *expected_fingerprint,
                                                             LmSSLFunction ssl_function,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    gboolean            lm_ssl_is_supported                 (void);
    const gchar *       lm_ssl_get_fingerprint              (LmSSL *ssl);
    void                lm_ssl_use_starttls                 (LmSSL *ssl,
                                                             gboolean use_starttls,
                                                             gboolean require_starttls);
    gboolean            lm_ssl_get_use_starttls             (LmSSL *ssl);
    gboolean            lm_ssl_get_require_starttls         (LmSSL *ssl);
    LmSSL *             lm_ssl_ref                          (LmSSL *ssl);
    void                lm_ssl_unref                        (LmSSL *ssl);

## Description

Use this together with an LmConnection to get the connection to use SSL. Example of how to use the LmSSL API.

    LmConnection *connection;
    LmSSL        *ssl;
    connection = lm_connection_new ("myserver");
    ssl = lm_ssl_new (NULL, my_ssl_func, NULL, NULL);
    lm_connection_set_ssl (connection, ssl);
    ...

## Details

### LmSSL

    typedef struct _LmSSL LmSSL;

This should not be accessed directly. Use the accessor functions as described below.

### enum LmCertificateStatus

    typedef enum {
    	LM_CERT_INVALID,
    	LM_CERT_ISSUER_NOT_FOUND,
    	LM_CERT_REVOKED
    } LmCertificateStatus;

Provides information of the status of a certain certificate.

`LM_CERT_INVALID` | The certificate is invalid.
`LM_CERT_ISSUER_NOT_FOUND` | The issuer of the certificate is not found.
`LM_CERT_REVOKED` | The certificate has been revoked.

### enum LmSSLStatus

    typedef enum {
    	LM_SSL_STATUS_NO_CERT_FOUND,
    	LM_SSL_STATUS_UNTRUSTED_CERT,
    	LM_SSL_STATUS_CERT_EXPIRED,
    	LM_SSL_STATUS_CERT_NOT_ACTIVATED,
    	LM_SSL_STATUS_CERT_HOSTNAME_MISMATCH,
    	LM_SSL_STATUS_CERT_FINGERPRINT_MISMATCH,
    	LM_SSL_STATUS_GENERIC_ERROR
    } LmSSLStatus;

Provides information about something gone wrong when trying to setup the SSL connection.

`LM_SSL_STATUS_NO_CERT_FOUND` | The server doesn't provide a certificate.
`LM_SSL_STATUS_UNTRUSTED_CERT` | The certification can not be trusted.
`LM_SSL_STATUS_CERT_EXPIRED` | The certificate has expired.
`LM_SSL_STATUS_CERT_NOT_ACTIVATED` | The certificate has not been activated.
`LM_SSL_STATUS_CERT_HOSTNAME_MISMATCH` | The server hostname doesn't match the one in the certificate.
`LM_SSL_STATUS_CERT_FINGERPRINT_MISMATCH` | The fingerprint doesn't match your expected.
`LM_SSL_STATUS_GENERIC_ERROR` | Some other error.

### enum LmSSLResponse

    typedef enum {
    	LM_SSL_RESPONSE_CONTINUE,
    	LM_SSL_RESPONSE_STOP
    } LmSSLResponse;

Used to inform LmConnection if you want to stop due to an error reported or if you want to continue to connect.

`LM_SSL_RESPONSE_CONTINUE` | Continue to connect.
`LM_SSL_RESPONSE_STOP` | Stop the connection.

### LmSSLFunction ()

    LmSSLResponse       (*LmSSLFunction)                    (LmSSL *ssl,
                                                             LmSSLStatus status,
                                                             gpointer user_data);

This function is called if something goes wrong during the connecting phase.

`ssl` : | An LmSSL.
`status` : | The status informing what went wrong.
`user_data` : | User data provided in the callback.
Returns : | User should return LM_SSL_RESPONSE_CONTINUE if connection should proceed and otherwise LM_SSL_RESPONSE_STOP.

### lm_ssl_new ()

    LmSSL *             lm_ssl_new                          (const gchar *expected_fingerprint,
                                                             LmSSLFunction ssl_function,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Creates a new SSL struct, call lm_connection_set_ssl to use it.

`expected_fingerprint` : | The expected fingerprint. `ssl_function` will be called if there is a mismatch. `NULL` if you are not interested in this check.
`ssl_function` : | Callback called to inform the user of a problem during setting up the SSL connection and how to proceed. If `NULL` is passed the default function that always continues will be used.
`user_data` : | Data sent with the callback.
`notify` : | Function to free `user_dataa` when the connection is finished. `NULL` if `user_data` should not be freed.
Returns : | A new LmSSL struct.

### lm_ssl_is_supported ()

    gboolean            lm_ssl_is_supported                 (void);

Checks whether Loudmouth supports SSL or not.

Returns : | TRUE if this installation of Loudmouth supports SSL, otherwise returns FALSE.

### lm_ssl_get_fingerprint ()

    const gchar *       lm_ssl_get_fingerprint              (LmSSL *ssl);

Returns the MD5 fingerprint of the remote server's certificate.

`ssl` : | an LmSSL
Returns : | A 16-byte array representing the fingerprint or `NULL` if unknown.

### lm_ssl_use_starttls ()

    void                lm_ssl_use_starttls                 (LmSSL *ssl,
                                                             gboolean use_starttls,
                                                             gboolean require_starttls);

Set whether STARTTLS should be used.

`ssl` : | an LmSSL
`use_starttls` : | TRUE if STARTTLS should be used.
`require_starttls` : | TRUE if STARTTLS should be required.

### lm_ssl_get_use_starttls ()

    gboolean            lm_ssl_get_use_starttls             (LmSSL *ssl);

Fetches whether STARTTLS is used.

`ssl` : | an LmSSL
Returns : | TRUE is `ssl` is configured to use STARTTLS.

### lm_ssl_get_require_starttls ()

    gboolean            lm_ssl_get_require_starttls         (LmSSL *ssl);

Fetches whether STARTTLS is required.

`ssl` : | an LmSSL
Returns : | TRUE if `ssl` requires that STARTTLS succeed.

### lm_ssl_ref ()

    LmSSL *             lm_ssl_ref                          (LmSSL *ssl);

Adds a reference to `ssl`.

`ssl` : | an LmSSL
Returns : | the ssl

### lm_ssl_unref ()

    void                lm_ssl_unref                        (LmSSL *ssl);

Removes a reference from `ssl`. When no more references are present `ssl` is freed.

`ssl` : | an LmSSL