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