You can use the ssldump utility to examine, decrypt, and decode SSL-encrypted packet streams managed by the BIG-IP system. The ssldump utility can act on packet streams real-time as they traverse the system, or on a packet capture file saved in the libpcap format, such as that produced by the tcpdump utility. Although it is possible for the ssldump utility to decode and display live traffic real-time as it traverses the BIG-IP system, it is rarely the most effective method to examine the voluminous and complex output of the ssldump utility. Capturing the target traffic to a file using the tcpdump utility, then decoding the file using the ssldump utility offers a better opportunity to examine the traffic in detail.
Here are the steps
- Capture the traffic
- Examine the SSL handshake and other SSL traffic
- Examine the decrypted application data
Capture the traffic
Capture traffic that contains the SSL traffic you want to examine.
When you capture SSL conversations for ssldump examination, follow these guidelines:
- If you use a browser to test, first close all existing browser windows and then use a newly-opened browser window to reproduce the issue to ensure a new session key is used. The ssldump utility cannot decrypt traffic for which the handshake including the key exchange was not seen.
- To write the captured packets to a file for examination with the ssldump utility, you must specify the -w option with the name of the file to which the captured data should be stored.
- Use the -i option to specify the interface or VLAN from which traffic is to be captured.
- Use the appropriate tcpdump filters to include only the traffic you want to examine.
- If you want to decrypt and examine the application data, you must capture the entire packet by specifying a value of 0 or the maximum size of the target packet to the -s option.
- Consider using the -v (verbose) option to increase the level of detail captured.
Capturing traffic examples
if you want to save for examination client-side traffic to a specific SSL virtual server listening on the VLAN external, the following command includes the appropriate options and filters on the virtual server's IP address and port:
tcpdump -vvv -s 0 -nni external -w /var/tmp/www-ssl-client.cap host 10.1.1.100 and port 443
If you want to examine server-side traffic from one client to any pool member, use the -i option to specify the VLAN on which the servers reside, and filter on the client IP address, the server subnet, and the port on which the servers are listening. To do so, use the following command:
tcpdump -vvv -s 0 -nni internal -w /var/tmp/www-ssl-server.cap host 192.168.22.33 and net 10.1.1.0/24 and port 8080
The traffic matching the specified filter is saved to the indicated capture file.
The options used are:
- -vvv Maximum verbosity
- -s Snaplength (0 captures full packets)
- -nn Do not resolve host or service names
- -i Interface - can be ifname or vlan name
- -w Write output to file
Examine the SSL handshake and other SSL traffic
SSL connections are established on top of an existing TCP connection using an SSL handshake that accomplishes the following:
- The client and server negotiate security capabilities, such as the public-key algorithm, the symmetric key algorithm, and compression algorithms.
- The server transmits its certificate to the client, allowing the client to validate the identity of the server.
- The client and server exchange session key information.
- The client may also send its certificate to the server, allowing the server to validate the identity of the client.
The handshake transactions consist of a number of SSL record messages. These messages can be examined by executing the ssldump utility using the -r option to specify the path and name of the tcpdump capture file to be examined. Other useful options include the following:
- -n Do not resolve host names.
- -A Print all fields (ssldump, by default, prints only the most interesting).
- -e Print absolute timestamps.
- -d Display application data, including traffic before session initiates.
- -M Output a pre-master secret log file (v. 11.2.0 and later)
For example, the following command displays all of the SSL record messages found in the tcpdump capture file named www-ssl-client.cap:
ssldump -nr /var/tmp/www-ssl-client.cap
The SSL records printed by the ssldump utility appear similar to the following example:
The first line defines a new TCP connection which appears similar to the following example:
To differentiate records belonging to different connections, each connection is numbered. The example defines connection 2. The host that sends the first SYN is printed on the left and the host that responds is printed on the right. In most cases, the SSL client is printed on the left with the SSL server on the right. In this case we have a connection from 172.16.31.22 port 32866 to 192.168.1.8 port 8080.
Subsequent lines represent SSL records sent between the client and the server. The printout of each SSL record begins with a record line. It contains the connection number with which the record is associated, and the sequence number of the record itself, followed by two time stamps. The first time stamp is the time, in seconds, since the beginning of the connection. The second time stamp is the time, in seconds, since the previous record on the same connection. The next column indicates the origin of the message. Communications originating from the client are indicated in the next column by C>S (client to server), while messages originating from the server are marked with S>C (server to client). The last column indicates the type of SSL record message that was received, which can be either Handshake, Alert, ChangeCipherSpec, or application_data. Finally, the ssldump utility may print record-specific data on the rest of the line. For Handshake records, the utility prints the handshake message. For application_data messages, the utility prints the decrypted application data.
By default, the ssldump utility decodes and displays useful details of some SSL record messages.
Details the version, offered cipher suites, and session id, if provided.
Details the version, session_id, chosen cipher suite, and compression method.
Details type and level, if provided.
The following example is the ssldump output for the second record on connection 2:
The record was sent by the server, and it is a Handshake record that contains a Server Hello message.
Examine the decrypted application data
Decrypting the SSL application data may expose sensitive information such as credit card numbers and passwords
The ssldump utility must have access to either the (asymmetric) private key from the server you want to debug, or the (symmetric) pre-master secret keys. Using the pre-master secret keys allows you to examine the decrypted application data in Wireshark without having access to the (asymmetric) private key.
Examine the decrypted application data using the (symmetric) pre-master secret keys
Beginning in BIG-IP 11.2.0, the ssldump -M option allows you to create a pre-master secret (PMS) key log file. You can load the PMS log file into Wireshark (1.6 and later) along with the capture file and use it to decrypt the application data without having access to the server's private key. This option gives F5 Support the ability to fully decrypt sessions in the targeted capture file without revealing sensitive information about the private key.
To run ssldump using the -M option to create a pre-master secret key log file, perform the following procedure:
- Log in to the BIG-IP command line.
- Capture the packet trace containing the SSL traffic (refer to the Capturing the target traffic section).
To create a pre-master secret key log file, use the following ssldump syntax:
ssldump -r /path/to/capture_file -k /path/to/private_key -M /path/to/pre-master-key_log_file
For example, the following ssldump command reads the www-ssl-client1.cap capture file using the test.org key file to decrypt the session, and creates the PMS log file called client1.pms:
ssldump -r /var/tmp/www-ssl-client1.cap -k /config/filestore/files_d/Common_d/certificate_key_d/\:Common\:test.org.key_1 -M /var/tmp/client1.pms
You can now load the capture file and the PMS log file into Wireshark (1.6 and later).
Note: To load the pre-master secret (PMS) key log file in Wireshark, go to Edit > Preferences > Protocols > TLS, and enter the path and file name of the PMS key in the (Pre)-Master-Secret log filename field.
Examine the decrypted application data using the (asymmetric) private key
To decrypt and display application data, the ssldump utility will need a copy of the private key from the server you want to debug. If you do not have the key, the application data cannot be decrypted, and you will only be able to examine and decode the SSL handshake packets.
Not all ciphers provide the ability to decrypt SSL traffic using a utility such as ssldump. Depending on the cipher negotiated, the ssldump utility may not be able to derive enough information from the SSL handshake and the server’s private key to decrypt the application data. Examples of such SSL ciphers would be the Diffie-Hellman Ephemeral (DHE) cipher suites and export-grade RSA cipher suites. If you have to decrypt application data for a virtual server, from BIG-IP 11.6.0, you can use an iRule to get a premaster key for the DHE/ECDHE cipher suite. For details, refer to K16700: Decrypting SSL traffic using the SSL::sessionsecret iRule command. If you are using software earlier than BIG-IP 11.6.0, you can change the cipher suite used in your SSL profile so traffic can be decrypted with ssldump. To do so, make a note of the cipher string currently configured in the SSL profile, then temporarily modify the SSL profile to specify a custom cipher string such as NONE:AES128-SHA.
In the previous example, the ssldump command that is provided prints the application_data record type but does not display the application data itself. Since no key was provided, the application data has not been decrypted. To print the decrypted application data, use the -k option to specify the path and name of the file containing the server's private key.
ssldump -Aed -nr /var/tmp/www-ssl-client.cap -k /config/ssl/ssl.key/www-ssl.key
Decoded application data records printed by ssldump appear similar to the following example:
Locate a BIG-IP virtual server's private key
The private key that the BIG-IP system uses for a virtual server is specified in the Client SSL profile applied to the virtual server. The key file locations are listed below:
BIG-IP 11.x - 16.x:
Resumed TLS handshake
One of the most common reasons an ssldump may not decrypt application data, is if the data is contained within a resumed TLS session. Public key operations are expensive in terms of processing power during the initial setup and key exchange. TLS specifications allow a secure shortcut by using the session_id to resume an SSL connection for which the key exchange was already performed.
In situations where the SSL communication is using a resumed session, ssldump will not be able decrypt the application data unless the capture file contains the initial handshake containing the asymmetric key exchange and session_id. The ssldump utility relies on the information that is exchanged during the initial session setup to decrypt the data.
The following packet capture output example shows a resumed connection:
A client requesting to resume an SSL session appears similar to the following example:
A server agreeing to resume the session returns the ServerHello with the same session_id as displayed below:
The previous example is a resumed session; the client sends a ClientHello that includes a resume, the server responds with a ServerHello that contains the same session_id the client sent.
The server is under no obligation to resume a session. This is specified within the TLS 1.0 specification RFC2246:
To avoid this situation, you can use one of the following methods:
- Temporarily disable the SSL session cache in the Client SSL profile by disabling the Renegotiation option. Disabling the SSL session cache causes the BIG-IP system to perform a full SSL handshake for each connection.
- Force the client to start a new session.