DSSL Library Documentation

Version 1.3.2

DSSL Programming Guide

The best way to learn DSSL is by looking into ssltrace sample program that is located in samples subdirectory of DSSL installation v. 1.0.3

There are two different ways you can use DSSL: as a full-featured framework or just the SSL decryption module alone.

I. Using DSSL Framework

If you plan to use DSSL as your main TCP reassembly, session management, and SSL decryption module, you need to:

• Create a CapEnv object and attach it to your pcap_t capture handle using CapEnvCreate function.
• Call CapEnvSetSSL_ServerInfo for each SSL server, which traffic you want CapEnv to decrypt
• Use CapEnvSetSessionCallback function to set up a session callback routine that will be called every time CapEnv is about to create a new session (DSSL_EVENT_NEW_SESSION) or an existing session is about to be closed (DSSL_EVENT_SESSION_CLOSING).
• When your session callback function is called with DSSL_EVENT_NEW_SESSION event, set the data and error callback functions for a newly created session. These functions will be called when new data is available on a session, and when DSSL encounters an error while processing session packet, respectively.
• Call CapEnvCapture to start the capture on the pcap_t handle associated with your CapEnv instance. You’ll get your callback functions called as the data start passing through. Remember that the callback functions must not block!
• After you are done with the CapEnv object, call CapEnvDestroy.

II. Using SSL Decryption Layer only

1. General Considerations

If you already have the TCP layer reassembly and session management code, but want to use DSSL for SSL decryption, you need to follow these steps:

1. Creare a DSSL_Env structure using DSSL_EnvCreate function.
2. Call DSSL_EnvSetServerInfo function for each SSL server, which traffic you want to decrypt.
3. When you see a new SSL session in a captured traffic, create a DSSL_Session object using DSSL_EnvCreateSession function.
4. For a new SSL session, call DSSL_SessionSetCallback to set your application data and error callback routines.
5. When a new network packet arrives, resolve the corresponding DSSL_Session object and call DSSL_SessionProcessData function to process the data. Note that DSSL_SessionProcessData function expects a pointer to the TCP payload part of the packet, not the whole packet!
6. DSSL will call the data callback routine set in step 4 each time new chunk of data is deciphered.
7. When a session terminates, call DSSL_SessionDeInit on a corresponding DSSL_Session object, and then free that object.
8. Finally, destroy the DSSL_Env object when you don’t need it anymore with DSSL_EnvDestroy call.

2. TCP reassembly

You are responsible for doing all TCP/IP protocol-related processing. SSL Decryption Layer API assumes that the input data is properly reassembled TCP payload.

3. SSL Handshake Protocol Decoding

Each SSL connection starts with establishing a handshake. Handshake protocol is a part of the SSL/TLS standard. For certain SSL handshake messages (ClientHello/ServerHello in particular), DSSL API requires that a full such message is passed to DSSL_SessionProcessData function at a time - no fragmentation allowed. The best approach is to pass the whole payload of a single TCP packet at a time. If your application doesn't have access to the TCP protocol data or for any other reason can't tell where one TCP packet ends and the next one starts, the best approach is to buffer the data until the transmission direction changes, i.e. buffer all the data client sends to the server until the server starts talking and vice versa and then send the buffered data to DSSL_SessionProcessData.