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