DSSL Library Documentation

Version 1.3.2

API Reference

Data Structures


The following list constitutes DSSL's most important data structures. Note that all of these structures should be considered as opaque types and used only as arguments to DSSL API functions.

CapEnv

This is the main structure in DSSL framework that links all the DSSL components together and with libpcap capture adapter.

DSSL_Env

This structure stores global SSL decryption environment data such as a list of SSL server addresses and SSL session cache for SSL session resumption.

DSSL_Session

Represents a single SSL session.

DSSL_ServerInfo

Represents SSL server data: IP address, RSA private key, keyfile password, etc.

TcpSession

Represents a single TCP session. This structure is used by DSSL's TCP reassemly code.

Pkt

Represents a captured network packet. This structure is used by DSSL's TCP reassemly code.

Enums and Defines


NM_PacketDir enum

Defines a packet directions within TCP session.

typedef enum NM_PacketDir_
{
	ePacketDirInvalid,
	ePacketDirFromClient,
	ePacketDirFromServer
} NM_PacketDir;

DSSL_EVENT_XXX codes

Session event codes used in CapEnvSessionCallback callback.

#define DSSL_EVENT_NEW_SESSION		0
#define DSSL_EVENT_SESSION_CLOSING	1

Function Prototypes


CapEnvSessionCallback

A prototype of CapEnv session event callback function. This callback function is called every time CapEnv is about to create a new session or an existing session is about to be closed.

typedef void (*CapEnvSessionCallback)( struct CapEnv_* env, TcpSession* sess, char event );
Parameters:
env
CapEnv instance that fired this session event.
sess
Event's TCP session.
event
An event code - either DSSL_EVENT_NEW_SESSION or DSSL_EVENT_SESSION_CLOSING.

DataCallbackProc

A prototype of the session data callback function.

typedef void (*DataCallbackProc)( NM_PacketDir dir, void* user_data, u_char* data, uint32_t len );
Parameters:
dir
Packet direction (ePacketDirFromClient or ePacketDirFromServer NM_PacketDir enum value)
user_data
Application-defined data associated with the TCP or SSL session. See SessionSetCallback function.
data
Pointer to the reassembled / decrypted packet payload data.
len
Length of data in bytes.

ErrorCallbackProc

A prototype of the session error callback function.

typedef void (*ErrorCallbackProc)( void* user_data, int error_code );
Parameters:
user_data
Application-defined data associated with the TCP or SSL session. See SessionSetCallback function.
error_code
One of DSSL_E_XXX error codes.

DSSL Framework API Functions


This section documents DSSL public instance management, initialization and data processing API.

CapEnvCreate

Creates a CapEnv structure and initialize it with pcap_t capture handle, TCP session table size and SSL session timeout interval in seconds.

CapEnv* CapEnvCreate( pcap_t* adapter, int sessionTableSize, uint32_t cache_timeout_interval );

CapEnvDestroy

Destroys a CapEnv instance and frees allocated memory.

void CapEnvDestroy( CapEnv* env );

CapEnvCapture

Process packets captured by calling by pcap_loop routine on env's pcap handle.

int CapEnvCapture( CapEnv* env );

CapEnvSetSessionCallback

Sets a callback function that is executed every time a TCP session is created or destroyed within the given CapEnv instance.

void CapEnvSetSessionCallback( 
		CapEnv*                     env,
		CapEnvSessionCallback		callback,
		void*                       user_data,
		); 

CapEnvFindDSSL_ServerInfo

Searches env's SSL server list for a server by its IP address and port number.

DSSL_ServerInfo* CapEnvFindDSSL_ServerInfo(
        CapEnv*         env,
        struct in_addr* server_ip,
        uint16_t        server_port );
Parameters:
env
CapEnv instance to search within.
ip_address
Target server's IP address.
port
Target server's TCP port number.

CapEnvSetSSL_ServerInfo

Adds SSL server data to CapEnv's DSSL decryption module.

int CapEnvSetSSL_ServerInfo( 
		CapEnv*             env,
		struct in_addr*	    ip_address,
		uint16_t            port, 
		const char*         keyfile,
		const char*         password );
Parameters:
env
CapEnv instance for which the SSL server info is set
ip_address
Server IP address
port
Server TCP port number
keyfile
Server private key file path.
password
Key file password. Can be NULL if the keyfile is not encrypted.

SSL Traffic Decryption API


SSL decryption layer has its own API that can be used as a stand-alone interface, bypassing the CapEnv TCP reassembly module. It is designed for applications that have their own TCP reassembly layer.

DSSL_EnvCreate

Creates a DSSL decryption environment object.

DSSL_Env* DSSL_EnvCreate(
		int session_cache_size,
		uint32_t cache_timeout_interval );
Parameters:
session_cache_size
Defines the size of a hash table used to store previously negotiated SSL sessions in order to handle SSL session resumption.
cache_timeout_interval
A SSL session timeout value in seconds. If a session is not resumed within this interval, it gets removed from the cache.

DSSL_EnvDestroy

Destroys DSSL_Env object.

void DSSL_EnvDestroy( DSSL_Env* env );

DSSL_EnvSetServerInfo

Adds SSL server data to DSSL_Evn server table.

int DSSL_EnvSetServerInfo( 
		DSSL_Env*           env,
		struct in_addr*	    ip_address,
		uint16_t            port, 
		const char*         keyfile,
		const char*         password );
Parameters:
env
CapEnv instance for which the SSL server info is set
ip_address
Server IP address
port
Server TCP port number
keyfile
Server private key file path.
password
Key file password. Can be NULL if the keyfile is not encrypted.

DSSL_SessionInit

Initialize DSSL_Session object.

void DSSL_SessionInit(
		DSSL_Env*			env,
		DSSL_Session*		s,
		DSSL_ServerInfo*	si );

DSSL_SessionDeInit

Destroy DSSL_Session internal structures. Call this method before freeing the DSSL_Session object.

void DSSL_SessionDeInit( DSSL_Session* s );

DSSL_SessionSetCallback

Set the data and error callback routines for DSSL_Session object.

void DSSL_SessionSetCallback( 
		DSSL_Session*		sess,
		SessionCallbackProc data_callback, 
		ErrorCallbackProc	error_callback,
		void*				user_data );
Parameters:
sess
DSSL_Session object
data_callback
A callback routine that is be called when new data (SSL payload) is decrypted and ready to be processed.
error_callback
An error callback routine that is called when an error occurs.
user_data
User-defined application data associated with this session.

DSSL_SessionProcessData

This is a main SSL layer entry point that process decrypts SSL data and returns decrypted payload through DSSL_Session data callback routine.

int DSSL_SessionProcessData(
		DSSL_Session*       sess,
		NM_PacketDir        dir,
		u_char*             data,
		uint32_t            len );
Parameters:
sess
DSSL_Session object
dir
Packet direction. Can be one of the following: ePacketDirFromClient for client-to-server packet or ePacketDirFromServer for server-to-client packet.
data
Packet data, starting from the TCP payload. Note that it is the caller's responsibility to strip lower-level network protocol headers (Ethernet, IP, TCP).
len
Data size in bytes
Copyright © SSLTech.net, 2005-2007. All rights reserved.