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