Products | DSSL DSSL Library, v. 1.4.4 (December 5, 2008) December 5, 2008: New! DSSL Library v.1.4.4 is available for download (Change Log) DSSL is a SSL traffic decryption and TCP reassembly toolkit, implemented as a cross-platform C library. Currently, DSSL is built and tested on Linux and Microsoft Windows platforms. DSSL provides application developers with the functionality to reassemble captured network packets into TCP streams, and, if the traffic is SSL-encrypted, decrypt the data (provided with SSL server’s private key). After that, the reassembled and decrypted data can be analyzed by the user application. DSSL Library Documentation * Installation o Prerequisites o Installing DSSL on Linux o Installing DSSL on Windows * DSSL Architecture Overview * Programming Guide o DSSL Framework o Using SSL Decryption layer only * API Reference * FAQ DSSL Library Documentation Version 1.3.3 Installation Prerequisites DSSL requires the libpcap (WinPcap v. 3.1 for Windows platform) library and the OpenSSL library v. 0.9.8d or above to be installed on your system. Installing DSSL on Linux 1. Make sure that libpcap and OpenSSL libraries are installed on your system. 2. Uncompress and unpack the dssl-1.0.3.tar.gz archive into a temp directory: cd /tmp gunzip dssl-1.0.3.tar.gz tar xvf dssl-1.0.3.tar 3. Build and install the DSSL library and header files: cd /tmp/dssl-1.0.3 ./configure make su -c "make install" If everything went well, DSSL library and header files are installed into /usr/local/lib/ and /usr/local/include/dssl directories, respectively. Installing DSSL on Windows Currently, DSSL supports only VisualStudio.NET 2003 / 2005 compilers. 1. Unzip dssl-1.0.3.zip into a folder you want DSSL to be installed (e.g. c:\dssl). 2. Add the libdssl.vcproj file to your VS.NET solution. 3. Adjust the OpenSSL and WinPcap include directories: * In the Solution Explorer window, right-click on the libdssl project node, then click Properties * In the libdssl Property Page dialog, go to Configuration Properties / C/C++ / General tab. * In the Additional Include Directories field, replace the ..\WdpPack\Include and ..\openssl\win32 entries with the actual paths to your WinPcap and OpenSSL include folders, respectively. If everything went well, you should be able to build libdssl.vcproj project. DSSL Library Documentation Version 1.3.3 DSSL Architecture Overview DSSL library consists of the following functional parts: Packet Processing Layer Packet layer receives captured network packets and process the link (Ethernet) and network (IP) protocols, detects TCP packets and directs them to the TCP layer. TCP layer TCP layer resolves packet's TCP session object using a table of all active TCP sessions it maintains. Then, the session packets are sorted and reassembled into client-to-server and server-to-client TCP streams. When a new chunk of reassembled data becomes available, the TCP layer passes it to the data callback routine for further processing. For plaintext TCP traffic (no SSL), the output from TCP session reassembly is headed directly to user-provided callback function for application-level processing. If SSL encryption is present, the reassembled traffic first passes through the SSL Decryption layer before it reaches the application. SSL decryption layer This module reconstructs the SSL protocol carried over its input TCP payload data. Then, using SSL server’s private key provided, it decrypts the SSL payload and passes the decrypted plaintext to the application-defined callback routine for processing. SSL Decryption layer's design allows it to be used independently from the other parts of the library. This simplifies the task of adding SSL encryption support for applications that already have their own TCP reassembly and session management code. DSSL Library Documentation Version 1.3.3 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 DSSL Library Documentation Version 1.3.3 DSSL FAQ What is DSSL? DSSL is a programming toolkit that decodes and deciphers captured SSL/TLS traffic. The toolkit is implemented as a C library built on top of libpcap/winpcap and OpenSSL API and consists of packet capture, TCP reassembly and SSL decryption modules. How it works? DSSL processes captured network traffic from both directions (from client to server and vice versa) and reconstructs both client's and server's SSL states, including session encryption keys to decipher the encrypted traffic. DSSL does not "crack" SSL cryptography (it is virtually impossible). Instead, it reconstructs session's keying material using server's private RSA key. Who should use DSSL? DSSL toolkit is designed primarily for network monitoring, network security, traffic and protocol analyzing software, but also for any software products that process captured network traffic. Why? Due to growing market demand, more and more client-server systems and other network software start offering network traffic encryption through SSL/TLS - the leading standard in network data security. This trend is widely appreciated by the end users and security experts, but also presents a real challenge to a wide variety of software systems mentioned above. Existing solutions to that dual-sword nature of SSL usually include dedicated SSL terminators or SSL proxies, which are clumsy, hard to maintain and greatly reduce the attractiveness, or even defeat the purpose, of using SSL. Ignoring the encrypted traffic is perceived as lack of functionality and, therefore, is hardly an option for a modern network monitoring or security product. The ability to speak SSL natively presents a much better choice indeed. So here comes DSSL. Is there some sample code that can get me started with DSSL? Yes. Look into samples subdirectory. CHANGELOG 2008-12-05: version 1.4.4 * Fixed TCP session hashing bug - thanks to Faisal Shaikh * TCP session timeout set to 180 seconds 2008-11-30: version 1.4.3 * Fixed memory leak in TCP session processing * Added TCP session table cleanup 2008-09-25: version 1.4 * Added ACK control to TCP stream processing 2008-09-18: version 1.3.3 * Added session start timestamp to the TCP session object 2008-07-11: version 1.3.2 * Missing const keyword added to SessionSetUserData function * TCP session capture can no longer start from the middle of TCP session 2008-07-05: version 1.3.1 * Fixed wrong ASSERT statement bug in decoder.c 2008-05-06: version 1.3.0 * Added SSL version 2.0 support * Fixed TCP reassembly bug 2008-03-23: version 1.2.0 * Added DEFLATE compression support (RFC 3749) * Added MacOS support - thanks to Michael Dickey from Atomic Labs (http://www.atomiclabs.com) 2007-06-05: version 1.0.3 * Fixed session management bug causing non-existing empty sessions being created and destroyed * Added ssltrace sample - a simple command line utility that dumps decrypted SSL data * Added server's certificate check to make sure the cert is signed with the same private key DSSL initialized with * New error codes added (see errors.h) * Fixed SSL decryption engine: block cipher padding length check added to prevent possible buffer overrun condition * Fixed NULL password parameter was causing a segmentation fault (access violation on Win32) 2007-04-19: build 1.0.2 * DSSL_NO_PCAP define added. Now you can compile DSSL without referencing functions from pcap library. 2007-03-26: version 1.0.1 * Fix RSA private key file loading errors. * Fix memory leak in MAC calculation. 2007-01-17: version 1.0.0 * First public release.