TLS/SSL related API

TLS/SSL related API. More...

Data Structures
struct	ci_tls_client_options
	Stores basic parameters for connecting to the remote TLS server. More...

Typedefs
typedef struct ci_tls_client_options	ci_tls_client_options_t
	Stores basic parameters for connecting to the remote TLS server.

Functions
void	ci_tls_init ()
	Initializes c-icap tls subsystem. More...
void	ci_tls_cleanup ()
	Deinitializes c-icap tls subsystem. More...
SSL_CTX *	ci_tls_create_context (ci_tls_client_options_t *opts)
	Create a context based on given opts. More...
ci_connection_t *	ci_tls_connect (const char *servername, int port, int proto, SSL_CTX *ctx, int timeout)
	Initializes and establishes a connection to a server. More...
int	ci_tls_connect_nonblock (ci_connection_t *connection, const char *servername, int port, int proto, SSL_CTX *ctx)
	The non-blocking version of ci_tls_connect function. More...
int	ci_connection_should_read_tls (ci_connection_t *connection)
	The TLS subsystem wants to read data from the connection. More...
int	ci_connection_should_write_tls (ci_connection_t *connection)
	The TLS subsystem wants to write data to the connection. More...
int	ci_connection_read_pending_tls (ci_connection_t *conn)
	There are pending bytes to read from TLS connection. More...
int	ci_connection_write_pending_tls (ci_connection_t *conn)
	There are pending bytes to write to TLS connection. More...

Detailed Description

TLS/SSL related API.

Function Documentation

int ci_connection_read_pending_tls

(

ci_connection_t *

conn

)

There are pending bytes to read from TLS connection.

Returns

The number of pending bytes or 0

int ci_connection_should_read_tls

(

ci_connection_t *

connection

)

The TLS subsystem wants to read data from the connection.

Returns

-1 on non TLS connection or error, 1 if wants to read data, 0 otherwise

int ci_connection_should_write_tls

(

ci_connection_t *

connection

)

The TLS subsystem wants to write data to the connection.

Returns

-1 on non TLS connection or error, 1 if wants to write data, 0 otherwise

int ci_connection_write_pending_tls

(

ci_connection_t *

conn

)

There are pending bytes to write to TLS connection.

Returns

The number of pending bytes or 0

void ci_tls_cleanup

(

)

Deinitializes c-icap tls subsystem.

Normally called on shutdown to clean-up.

ci_connection_t* ci_tls_connect	(	const char *	servername,
		int	port,
		int	proto,
		SSL_CTX *	ctx,
		int	timeout
	)

Initializes and establishes a connection to a server.

Parameters

servername	The ip or dns name of the server
p	The port number to use
proto	One of AF_INET, AF_INET6
ctx	The context object to use

Returns

NULL on failures the ci_connection_t object which can be used with various ci_connection_* api functions on success.

int ci_tls_connect_nonblock	(	ci_connection_t *	connection,
		const char *	servername,
		int	port,
		int	proto,
		SSL_CTX *	ctx
	)

The non-blocking version of ci_tls_connect function.

Returns

-1 on error, 1 when connection is established or 0 if should be called again.

To establish a connection required more than one calls to ci_tls_connect_nonblock. The user should monitor the connection->fd file descriptor for events in order to call again ci_tls_connect_nonblock. If it is used with a custom monitor of file descriptors event, it should be used with ci_connection_should_read_tls/ci_connection_should_write_tls functions. In this case it should be used as follows:

ci_connection_t *connection = ci_connection_create();
int ret = ci_tls_connect_nonblock(connection, servername, port, proto, use_ctx);
while (ret == 0) {
    int wants_read = ci_connection_should_read_tls(connection);
    int wants_write = ci_connection_should_write_tls(connection);
    if (wants_read == 0 && wants_write == 0)
        wants_write = 1;
    int mresult = monitor_fd(connection->fd,
                             (wants_read > 0 ? MONITOR_FD_FOR_READ : 0),
                             (wants_write > 0 ? MONITOR_FD_FOR_WRITE : 0)
        );
    if (mresult == error) {
        return error;
    }
    ret = ci_tls_connect_nonblock(connection, servername, port, proto, use_ctx);
}
if (ret < 0)
    return error;

SSL_CTX* ci_tls_create_context

(

ci_tls_client_options_t *

opts

)

Create a context based on given opts.

A context can be used to open more than one connections to a TLS server.

void ci_tls_init

(

)

Initializes c-icap tls subsystem.

Normally called on programs startup.