Version 1.3.2
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.
If you plan to use DSSL as your main TCP reassembly, session management, and SSL decryption module, you need to:
CapEnv
object and attach it to your pcap_t
capture
handle using CapEnvCreate
function.CapEnvSetSSL_ServerInfo
for each SSL server, which traffic
you want CapEnv to decryptCapEnvSetSessionCallback
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).
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!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:
DSSL_Session
object using DSSL_EnvCreateSession
function.DSSL_SessionSetCallback
to set your
application data and error callback routines.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!DSSL_SessionDeInit
on a
corresponding DSSL_Session
object, and then free that object.DSSL_Env
object when you don’t need it
anymore with DSSL_EnvDestroy
call.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.
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
.