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