tlssep

tlssep

Functions

Types and Values

Description

Functions

tlssep_init ()

tlssep_status_t
tlssep_init (tlssep_context_t *context);

This function initializes libtlssep and executes a network decorator in preparation for later creating a TLS session.

Parameters

context

a pointer to a tlssep_context_t which this function will initialize

 

Returns

a tlssep_status_t


tlssep_connect ()

tlssep_status_t
tlssep_connect (tlssep_context_t *context,
                int file_descriptor,
                const char *expected_common_name,
                char *common_name,
                tlssep_desc_t *desc);

This function creates a TLS session by connecting over the given file descriptor. Most commonly, the file descriptor is a socket with an existing transport-layer connection to the remote host.

Parameters

context

a pointer to a valid tlssep_context_t

 

file_descriptor

the file descriptor upon which to create a TLS session; usually a network socket

 

expected_common_name

a pointer to NULL or a valid string representing the common name which is expected to be present in the remote certificate; what is done with this depends on the configured verification engine

 

common_name

if not NULL, this function will copy the remote certificate's common name to this address; the buffer must be at least TLSSEP_MAX_COMMON_NAME_SIZE bytes long

 

desc

a pointer to a tlssep_desc_t which this function will initialize

 

Returns

a tlssep_status_t


tlssep_accept ()

tlssep_status_t
tlssep_accept (tlssep_context_t *context,
               int file_descriptor,
               const char *expected_common_name,
               char *common_name,
               tlssep_desc_t *desc);

This function creates a TLS session by accepting on the given file descriptor. Most commonly, the file descriptor is a socket with an existing transport-layer connection to the remote host.

Parameters

context

a pointer to a valid tlssep_context_t

 

file_descriptor

the file descriptor upon which to create a TLS session; usually a network socket

 

expected_common_name

a pointer to NULL or a valid string representing the common name which is expected to be present in the remote certificate; what is done with this depends on the configured verification engine

 

common_name

if not NULL, this function will copy the remote certificate's common name to this address; the buffer must be at least TLSSEP_MAX_COMMON_NAME_SIZE bytes long

 

desc

a pointer to a tlssep_desc_t which this function will initialize

 

Returns

a tlssep_status_t


tlssep_write ()

tlssep_status_t
tlssep_write (tlssep_desc_t *desc,
              const void *buf,
              int buf_size,
              int *bytes_written);

This function passes a number of bytes to the network decorator which will encrypt the bytes before writing them to the TLS connection.

Parameters

desc

a pointer to a valid tlssep_desc_t

 

buf

some buffer of bytes to write

 

buf_size

the number of bytes to write from buf

 

bytes_written

a pointer to an integer which this function will set to the number of bytes actually written

 

Returns

a tlssep_status_t


tlssep_read ()

tlssep_status_t
tlssep_read (tlssep_desc_t *desc,
             void *buf,
             int buf_size,
             int *bytes_read);

This function requests that a number of bytes will be read by the network decorator. The network decorator will decrypt the bytes read from the TLS connection before returning them to the application.

Parameters

desc

a pointer to a valid tlssep_desc_t

 

buf

a buffer which will hold any bytes read

 

buf_size

the size of buf in bytes

 

Returns

a tlssep_status_t


tlssep_peek ()

tlssep_status_t
tlssep_peek (tlssep_desc_t *desc,
             void *buf,
             int buf_size,
             int *bytes_read);

This function requests that a number of bytes will be read by the network decorator. The network decorator will decrypt the bytes read from the TLS connection before returning them to the application. Unlike with tlssep_read, the network decorator will not remove the bytes from its TLS buffer; thus subsequent tlssep_read/tlssep_peek calls will read the same bytes again.

Parameters

desc

a pointer to a valid tlssep_desc_t

 

buf

a buffer which will hold any bytes read

 

buf_size

the size of buf in bytes

 

Returns

a tlssep_status_t


tlssep_poll ()

tlssep_status_t
tlssep_poll (tlssep_desc_t *desc,
             unsigned int timeout);

This function blocks until there is data ready to be read from the TLS connection up to the limit of timeout seconds.

Parameters

desc

a pointer to a valid tlssep_desc_t

 

timeout

the number of seconds to wait for data before giving up

 

Returns

a tlssep_status_t


tlssep_setnonblock ()

tlssep_status_t
tlssep_setnonblock (tlssep_desc_t *desc);

This function sets the mode of the network decorator’s TLS file descriptor to non-blocking.

Parameters

desc

a pointer to a valid tlssep_desc_t

 

Returns

a tlssep_status_t


tlssep_close ()

tlssep_status_t
tlssep_close (tlssep_desc_t *desc);

This function instructs the decorator to close the given TLS connection and remove its file descriptor from the select file descriptor set. The procedure also frees any state associated with the connection

Parameters

desc

a pointer to a valid tlssep_desc_t

 

Returns

a tlssep_status_t


tlssep_terminate ()

tlssep_status_t
tlssep_terminate (tlssep_context_t *context);

This function instructs the network decorator to exit.

Parameters

context

a pointer to a valid tlssep_context_t

 

Returns

a tlssep_status_t


tlssep_strerror ()

char *
tlssep_strerror (tlssep_status_t error);

This function transforms a tlssep_status_t into its string description.

Parameters

error

a tlssep_status_t

 

Returns

the string description of the given tlssep_status_t

Types and Values

enum tlssep_status_t

Enum values used to specify status conditions.

Members

TLSSEP_STATUS_OK

No error

 

TLSSEP_STATUS_AGAIN

Try again

 

TLSSEP_STATUS_ERROR

Generic error

 

TLSSEP_STATUS_ERROR_TLS

Generic TLS error

 

TLSSEP_STATUS_ERROR_TLS_CONNECT

Error connecting TLS

 

TLSSEP_STATUS_ERROR_TLS_ACCEPT

Error accepting TLS

 

TLSSEP_STATUS_ERROR_TLS_WRITE

Error writing TLS

 

TLSSEP_STATUS_ERROR_TLS_READ

Error reading TLS

 

TLSSEP_STATUS_ERROR_RPC_FAILURE

RPC failure

 

TLSSEP_STATUS_ERROR_ALLOCATION_FAILED

Error allocating memory

 

TLSSEP_STATUS_ERROR_POLL_FAILED

Error polling decorator

 

TLSSEP_STATUS_ERROR_SOCKET_FAILED

Error setting up a socket

 

TLSSEP_STATUS_ERROR_DECORATOR_BAD_EXIT

Bad exit code from decorator

 

TLSSEP_STATUS_ERROR_DECORATOR_FORK

Fork decorator error

 

TLSSEP_STATUS_ERROR_DECORATOR_MISSING

Decorator missing

 

TLSSEP_STATUS_ERROR_DESCRIPTORS_EXHAUSTED

No more descriptors available

 

TLSSEP_STATUS_ERROR_TRANSMITTING_FILE_DESCRIPTOR

Error transmitting file descriptor

 

TLSSEP_STATUS_ERROR_DECORATOR_BAD_CERT_PATH

Decorator bad certificate path

 

TLSSEP_STATUS_ERROR_DECORATOR_BAD_PRIVKEY_PATH

Decorator bad private key path

 

TLSSEP_STATUS_ERROR_DECORATOR_BAD_CA_PATH

Decorator bad CA path

 

TLSSEP_STATUS_ERROR_DECORATOR_BAD_VERIFICATION_ENGINE

Bad verification engine

 

TLSSEP_STATUS_ERROR_DECORATOR_BAD_CERTIFICATE

Bad certificate

 

TLSSEP_STATUS_ERROR_DECORATOR_MISSING_CERTIFICATE

Missing certificate

 

TLSSEP_STATUS_ERROR_DECORATOR_MISSING_CERTIFICATE_CHAIN

   

TLSSEP_STATUS_ERROR_DECORATOR_CERTIFICATE_MISMATCH

Unexpected name in certificate

 

TLSSEP_STATUS_ERROR_DECORATOR_CERTIFICATE_NAME_CONTAINS_NULL

   

TLSSEP_STATUS_LAST

   

tlssep_context_t

typedef struct {
} tlssep_context_t;

Maintains the state of a set of TLS connections, but contains no public fields. Initialize this structure by calling tlssep_init.


tlssep_desc_t

typedef struct {
	int               notificationSocket;
} tlssep_desc_t;

Serves as the descriptor of a single TLS connection. An application can poll the notificationSocket file descriptor to determine if there exists data which can be read from the network decorator using tlssep_read. Initialize this structure by calling tlssep_connect or tlssep_accept.