c-icap-doc  0.1
Data Structures | Typedefs | Functions
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
servernameThe ip or dns name of the server
pThe port number to use
protoOne of AF_INET, AF_INET6
ctxThe 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.