1SSLDUMP(1) General Commands Manual SSLDUMP(1)
2
6 ssldump - dump SSL traffic on a network
7
9 ssldump [ -vTshVq -aAdeHnNqTxXvy ] [ -i interface ]
10 [ -k keyfile ] [ -p password ] [ -r dumpfile ]
11 [ -S [crypto|d|ht|H|nroff] ] [ expression ]
12
14 ssldump is an SSL/TLS network protocol analyzer. It identifies TCP con‐
15 nections on the chosen network interface and attempts to interpret them
16 as SSL/TLS traffic. When it identifies SSL/TLS traffic, it decodes the
17 records and displays them in a textual form to stdout. If provided with
18 the appropriate keying material, it will also decrypt the connections
19 and display the application data traffic.
20 ssldump has been tested on FreeBSD, Linux, Solaris, and HP/UX. Since
22 it's based on PCAP, it should work on most platforms. However, unlike
23 tcpdump, ssldump needs to be able to see both sides of the data trans‐
24 mission so you may have trouble using it with network taps such as
25 SunOS nit that don't permit you to see transmitted data. Under SunOS
26 with nit or bpf: To run tcpdump you must have read access to /dev/nit
27 or /dev/bpf*. Under Solaris with dlpi: You must have read access to
28 the network pseudo device, e.g. /dev/le. Under HP-UX with dlpi: You
29 must be root or it must be installed setuid to root. Under IRIX with
30 snoop: You must be root or it must be installed setuid to root. Under
31 Linux: You must be root or it must be installed setuid to root. Under
32 Ultrix and Digital UNIX: Once the super-user has enabled promiscuous-
33 mode operation using pfconfig(8), any user may run ssldump Under BSD:
34 You must have read access to /dev/bpf*.
35
37 -a Print bare TCP ACKs (useful for observing Nagle behavior)
38 -A Print all record fields (by default ssldump chooses the most
40 interesting fields)
41 -d Display the application data traffic. This usually means
43 decrypting it, but when -d is used ssldump will also decode
44 application data traffic before the SSL session initiates. This
45 allows you to see HTTPS CONNECT behavior as well as SMTP START‐
46 TLS. As a side effect, since ssldump can't tell whether plain‐
47 text is traffic before the initiation of an SSL connection or
48 just a regular TCP connection, this allows you to use ssldump to
49 sniff any TCP connection. ssldump will automatically detect
50 ASCII data and display it directly to the screen. non-ASCII data
51 is displayed as hex dumps. See also -X.
52 -e Print absolute timestamps instead of relative timestamps
54 -H Print the full SSL packet header.
56 -n Don't try to resolve host names from IP addresses
58 -N Attempt to parse ASN.1 when it appears, such as in certificates
60 and DNs.
61 -p Use password as the SSL keyfile password.
63 -P Don't put the interface into promiscuous mode.
65 -q Don't decode any record fields beyond a single summary line.
67 (quiet mode).
68 -T Print the TCP headers.
70 -v Display version and copyright information.
72 -x Print each record in hex, as well as decoding it.
74 -X When the -d option is used, binary data is automatically printed
76 in two columns with a hex dump on the left and the printable
77 characters on the right. -X suppresses the display of the print‐
78 able characters, thus making it easier to cut and paste the hex
79 data into some other program.
80 -y Decorate the output for processing with nroff/troff. Not very
82 useful for the average user.
83 -i interface
85 Use interface as the network interface on which to sniff SSL/TLS
86 traffic.
87 -k keyfile
89 Use keyfile as the location of the SSL keyfile (OpenSSL format)
90 Previous versions of ssldump automatically looked in
91 ./server.pem. Now you must specify your keyfile every time.
92 -p password
94 Use password as the SSL keyfile password.
95 -r file
97 Read data from file instead of from the network. The old -f
98 option still works but is deprecated and will probably be
99 removed with the next version.
100 -S [ crypto | d | ht | H ]
102 Specify SSL flags to ssldump. These flags include:
103 crypto Print cryptographic information.
105 d Print fields as decoded.
107 ht Print the handshake type.
109 H Print handshake type and highlights.
111 expression
113 Selects what packets ssldump will examine. Technically speaking,
114 ssldump supports the full expression syntax from PCAP and tcp‐
115 dump. In fact, the description here is cribbed from the tcpdump
116 man page. However, since ssldump needs to examine full TCP
117 streams, most of the tcpdump expressions will select traffic
118 mixes that ssldump will simply ignore. Only the expressions
119 which don't result in incomplete TCP streams are listed here.
120 The expression consists of one or more primitives. Primitives
122 usually consist of an id (name or number) preceded by one or
123 more qualifiers. There are three different kinds of qualifier:
124 type qualifiers say what kind of thing the id name or number
126 refers to. Possible types are host, net and port. E.g.,
127 `host foo', `net 128.3', `port 20'. If there is no type
128 qualifier, host is assumed.
129 dir qualifiers specify a particular transfer direction to
131 and/or from id. Possible directions are src, dst, src or
132 dst and src and dst. E.g., `src foo', `dst net 128.3',
133 `src or dst port ftp-data'. If there is no dir quali‐
134 fier, src or dst is assumed. For `null' link layers
135 (i.e. point to point protocols such as slip) the inbound
136 and outbound qualifiers can be used to specify a desired
137 direction.
138 More complex filter expressions are built up by using the words
140 and, or and not to combine primitives. E.g., `host foo and not
141 port ftp and not port ftp-data'. To save typing, identical
142 qualifier lists can be omitted. E.g., `tcp dst port ftp or ftp-
143 data or domain' is exactly the same as `tcp dst port ftp or tcp
144 dst port ftp-data or tcp dst port domain'.
145 Allowable primitives are:
147 dst host host
149 True if the IPv4/v6 destination field of the packet is
150 host, which may be either an address or a name.
151 src host host
153 True if the IPv4/v6 source field of the packet is host.
154 host host
156 True if either the IPv4/v6 source or destination of the
157 packet is host. Any of the above host expressions can be
158 prepended with the keywords, ip, arp, rarp, or ip6 as in:
159 ip host host
160 which is equivalent to:
161 ether proto \ip and host host
162 If host is a name with multiple IP addresses, each
163 address will be checked for a match.
164 ether dst ehost
166 True if the ethernet destination address is ehost. Ehost
167 may be either a name from /etc/ethers or a number (see
168 ethers(3N) for numeric format).
169 ether src ehost
171 True if the ethernet source address is ehost.
172 ether host ehost
174 True if either the ethernet source or destination address
175 is ehost.
176 gateway host
178 True if the packet used host as a gateway. I.e., the
179 ethernet source or destination address was host but nei‐
180 ther the IP source nor the IP destination was host. Host
181 must be a name and must be found in both /etc/hosts and
182 /etc/ethers. (An equivalent expression is
183 ether host ehost and not host host
184 which can be used with either names or numbers for host /
185 ehost.) This syntax does not work in IPv6-enabled con‐
186 figuration at this moment.
187 dst net net
189 True if the IPv4/v6 destination address of the packet has
190 a network number of net. Net may be either a name from
191 /etc/networks or a network number (see networks(4) for
192 details).
193 src net net
195 True if the IPv4/v6 source address of the packet has a
196 network number of net.
197 net net
199 True if either the IPv4/v6 source or destination address
200 of the packet has a network number of net.
201 net net mask mask
203 True if the IP address matches net with the specific net‐
204 mask. May be qualified with src or dst. Note that this
205 syntax is not valid for IPv6 net.
206 net net/len
208 True if the IPv4/v6 address matches net a netmask len
209 bits wide. May be qualified with src or dst.
210 dst port port
212 True if the packet is ip/tcp, ip/udp, ip6/tcp or ip6/udp
213 and has a destination port value of port. The port can
214 be a number or a name used in /etc/services (see tcp(4P)
215 and udp(4P)). If a name is used, both the port number
216 and protocol are checked. If a number or ambiguous name
217 is used, only the port number is checked (e.g., dst port
218 513 will print both tcp/login traffic and udp/who traf‐
219 fic, and port domain will print both tcp/domain and
220 udp/domain traffic).
221 src port port
223 True if the packet has a source port value of port.
224 port port
226 True if either the source or destination port of the
227 packet is port. Any of the above port expressions can be
228 prepended with the keywords, tcp or udp, as in:
229 tcp src port port
230 which matches only tcp packets whose source port is port.
231 Primitives may be combined using:
233 A parenthesized group of primitives and operators (paren‐
235 theses are special to the Shell and must be escaped).
236 Negation (`!' or `not').
238 Concatenation (`&&' or `and').
240 Alternation (`||' or `or').
242 Negation has highest precedence. Alternation and concatenation
244 have equal precedence and associate left to right. Note that
245 explicit and tokens, not juxtaposition, are now required for
246 concatenation.
247 If an identifier is given without a keyword, the most recent
249 keyword is assumed. For example,
250 not host vs and ace
251 is short for
252 not host vs and host ace
253 which should not be confused with
254 not ( host vs or ace )
255 Expression arguments can be passed to ssldump as either a single
257 argument or as multiple arguments, whichever is more convenient.
258 Generally, if the expression contains Shell metacharacters, it
259 is easier to pass it as a single, quoted argument. Multiple
260 arguments are concatenated with spaces before being parsed.
261
263 To listen to traffic on interface le0 port 443
264 ssldump -i le0 port 443
265 To listen to traffic to the server romeo on port 443.
267 ssldump -i le0 port 443 and host romeo
268 To decrypt traffic to to host romeo server.pem and the password foobar
270 ssldump -Ad -k ~/server.pem -p foobar -i le0 host romeo
271
273 All output is printed to standard out.
274 ssldump prints an indication of every new TCP connection using a line
276 like the following
277 New TCP connection #2: iromeo.rtfm.com(2302) <-> sr1.rtfm.com(4433)
279 The host which send the first SYN is printed on the left and the host
281 which responded is printed on the right. Ordinarily, this means that
282 the SSL client will be printed on the left with the SSL server on the
283 right. In this case we have a connection from iromeo.rtfm.com (port
284 2303) to sr1.rtfm.com (port 4433). To allow the user to disentangle
285 traffic from different connections, each connection is numbered. This
286 is connection 2.
287 The printout of each SSL record begins with a record line. This line
289 contains the connection and record number, a timestamp, and the record
290 type, as in the following:
291 2 3 0.2001 (0.0749) S>C Handshake Certificate
293 This is record 3 on connection 2. The first timestamp is the time since
295 the beginning of the connection. The second is the time since the pre‐
296 vious record. Both are in seconds.
297 The next field in the record line is the direction that the record was
299 going. C>S indicates records transmitted from client to server and S>C
300 indicates records transmitted from server to client. ssldump assumes
301 that the host to transmit the first SYN is the SSL client (this is
302 nearly always correct).
303 The next field is the record type, one of Handshake, IAlert, ChangeCi‐
305 pherSpec, or application_data. Finally, ssldump may print record-spe‐
306 cific data on the rest of the line. For Handshake records, it prints
307 the handshake message. Thus, this record is a Certificate message.
308 ssldump chooses certain record types for further decoding. These are
310 the ones that have proven to be most useful for debugging:
311 ClientHello - version, offered cipher suites, session id
313 if provided)
314 ServerHello - version, session_id, chosen cipher suite,
315 compression method
316 Alert - type and level (if obtainable)
317 Fuller decoding of the various records can be obtained by using the -A
319 , -d , -k and -p flags.
320
322 ssldump can decrypt traffic between two hosts if the following two con‐
323 ditions are met:
324 1. ssldump has the keys.
325 2. Static RSA was used.
326 In any other case, once encryption starts, ssldump will only be able to
327 determine the record type. Consider the following section of a trace.
328 1 5 0.4129 (0.1983) C>S Handshake ClientKeyExchange
330 1 6 0.4129 (0.0000) C>S ChangeCipherSpec
331 1 7 0.4129 (0.0000) C>S Handshake
332 1 8 0.5585 (0.1456) S>C ChangeCipherSpec
333 1 9 0.6135 (0.0550) S>C Handshake
334 1 10 2.3121 (1.6986) C>S application_data
335 1 11 2.5336 (0.2214) C>S application_data
336 1 12 2.5545 (0.0209) S>C application_data
337 1 13 2.5592 (0.0046) S>C application_data
338 1 14 2.5592 (0.0000) S>C Alert
339 Note that the ClientKeyExchange message type is printed but the rest of
341 the Handshake messages do not have types. These are the Finished mes‐
342 sages, but because they are encrypted ssldump only knows that they are
343 of type Handshake. Similarly, had the Alert in record 14 happened dur‐
344 ing the handshake, it's type and level would have been printed. How‐
345 ever, since it is encrypted we can only tell that it is an alert.
346
348 Please send bug reports to ssldump@rtfm.com.
349 The TCP reassembler is not perfect. No attempt is made to reassemble IP
351 fragments and the 3-way handshake and close handshake are imperfectly
352 implemented. In practice, this turns out not to be much of a problem.
353 Support is provided for only for Ethernet and loopback interfaces
355 because that's all that I have. If you have another kind of network you
356 will need to modify pcap_cb in base/pcap-snoop.c. If you have direct
357 experience with ssldump on other networks, please send me patches.
358 ssldump doesn't implement session caching and therefore can't decrypt
360 resumed sessions.
361
363 tcpdump(1)
364
366 ssldump was written by Eric Rescorla <ekr@rtfm.com>.
367 28 September 2001 SSLDUMP(1)