## LmSSL

LmSSL — SSL struct for SSL support in Loudmouth

## Functions

LmSSLResponse | (*LmSSLFunction) ()
LmSSL * | lm_ssl_new ()
gboolean | lm_ssl_is_supported ()
void | lm_ssl_set_cipher_list ()
void | lm_ssl_set_ca ()
const gchar * | lm_ssl_get_fingerprint ()
void | lm_ssl_use_starttls ()
gboolean | lm_ssl_get_use_starttls ()
gboolean | lm_ssl_get_require_starttls ()
LmSSL * | lm_ssl_ref ()
void | lm_ssl_unref ()

## Types and Values

#define | LM_FINGERPRINT_PREFIX
#define | LM_FINGERPRINT_LENGTH
enum | LmCertificateStatus
enum | LmSSLStatus
enum | LmSSLResponse
| LmSSL

## Description

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

    1
    2
    3
    4
    5
    6
    7

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

## Functions

### LmSSLFunction ()

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

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

#### Parameters

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.

#### Parameters

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

    void
    lm_ssl_set_cipher_list (LmSSL *ssl,
                            const gchar *cipher_list);

Sets the list of availeble ciphers.

#### Parameters

ssl | an LmSSL |
cipher_list | list of ciphers |

### lm_ssl_set_ca ()

    void
    lm_ssl_set_ca (LmSSL *ssl,
                   const gchar *ca_path);

Sets a path to certificates which should be trusted.

#### Parameters

ssl | an LmSSL |
ca_path | path to a certificate or a directory containing certificates |

### lm_ssl_get_fingerprint ()

    const gchar *
    lm_ssl_get_fingerprint (LmSSL *ssl);

Returns the fingerprint of the remote server's certificate.

#### Parameters

ssl | an LmSSL |

#### Returns

A null terminated string representing the fingerprint or `NULL` if unknown.

### lm_ssl_use_starttls ()

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

Set whether STARTTLS should be used.

#### Parameters

ssl | an LmSSL |

### lm_ssl_get_use_starttls ()

    gboolean
    lm_ssl_get_use_starttls (LmSSL *ssl);

#### Returns

TRUE is `ssl` is configured to use STARTTLS.

### lm_ssl_get_require_starttls ()

    gboolean
    lm_ssl_get_require_starttls (LmSSL *ssl);

#### Returns

TRUE if `ssl` requires that STARTTLS succeed.

### lm_ssl_ref ()

    LmSSL *
    lm_ssl_ref (LmSSL *ssl);

Adds a reference to `ssl` .

#### Parameters

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.

#### Parameters

ssl | an LmSSL |

## Types and Values

### LM_FINGERPRINT_PREFIX

    #define LM_FINGERPRINT_PREFIX "SHA256:"

### LM_FINGERPRINT_LENGTH

    #define LM_FINGERPRINT_LENGTH 72

### enum LmCertificateStatus

Provides information of the status of a certain certificate.

#### Members

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

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

#### Members

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

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

#### Members

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

### LmSSL

    typedef struct _LmSSL LmSSL;

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