1SSLDUMP(1)                  General Commands Manual                 SSLDUMP(1)
2
3
4

NAME

6       ssldump - dump SSL traffic on a network
7

SYNOPSIS

9       ssldump [ -vTshVq -aAdeHnNqTxXvy ] [ -i interface ]
10               [ -k keyfile ] [ -p password ] [ -r dumpfile ]
11               [ -S [crypto|d|ht|H|nroff] ] [ expression ]
12

DESCRIPTION

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
21       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

OPTIONS

37       -a     Print bare TCP ACKs (useful for observing Nagle behavior)
38
39       -A     Print  all  record  fields  (by default ssldump chooses the most
40              interesting fields)
41
42       -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
53       -e     Print absolute timestamps instead of relative timestamps
54
55       -H     Print the full SSL packet header.
56
57       -n     Don't try to resolve host names from IP addresses
58
59       -N     Attempt  to parse ASN.1 when it appears, such as in certificates
60              and DNs.
61
62       -p     Use password as the SSL keyfile password.
63
64       -P     Don't put the interface into promiscuous mode.
65
66       -q     Don't decode any record fields beyond  a  single  summary  line.
67              (quiet mode).
68
69       -T     Print the TCP headers.
70
71       -v     Display version and copyright information.
72
73       -x     Print each record in hex, as well as decoding it.
74
75       -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
81       -y     Decorate  the  output  for processing with nroff/troff. Not very
82              useful for the average user.
83
84       -i interface
85              Use interface as the network interface on which to sniff SSL/TLS
86              traffic.
87
88       -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
93       -p password
94              Use password as the SSL keyfile password.
95
96       -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
101       -S [ crypto | d | ht | H ]
102              Specify SSL flags to ssldump.  These flags include:
103
104              crypto Print cryptographic information.
105
106              d      Print fields as decoded.
107
108              ht     Print the handshake type.
109
110              H      Print handshake type and highlights.
111
112       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
121              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
125              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
130              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
139              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
146              Allowable primitives are:
147
148              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
152              src host host
153                     True if the IPv4/v6 source field of the packet is host.
154
155              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
165              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
170              ether src ehost
171                     True if the ethernet source address is ehost.
172
173              ether host ehost
174                     True if either the ethernet source or destination address
175                     is ehost.
176
177              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
188              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
194              src net net
195                     True if the IPv4/v6 source address of the  packet  has  a
196                     network number of net.
197
198              net net
199                     True  if either the IPv4/v6 source or destination address
200                     of the packet has a network number of net.
201
202              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
207              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
211              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
222              src port port
223                     True if the packet has a source port value of port.
224
225              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
232              Primitives may be combined using:
233
234                     A parenthesized group of primitives and operators (paren‐
235                     theses are special to the Shell and must be escaped).
236
237                     Negation (`!' or `not').
238
239                     Concatenation (`&&' or `and').
240
241                     Alternation (`||' or `or').
242
243              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
248              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
256              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

EXAMPLES

263       To listen to traffic on interface le0 port 443
264              ssldump -i le0 port 443
265
266       To listen to traffic to the server romeo on port 443.
267              ssldump -i le0 port 443 and host romeo
268
269       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

OUTPUT FORMAT

273       All output is printed to standard out.
274
275       ssldump prints an indication of every new TCP connection using  a  line
276       like the following
277
278       New TCP connection #2: iromeo.rtfm.com(2302) <-> sr1.rtfm.com(4433)
279
280       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
288       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
292       2 3  0.2001 (0.0749)  S>C  Handshake      Certificate
293
294       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
298       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
304       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
309       ssldump chooses certain record types for further  decoding.  These  are
310       the ones that have proven to be most useful for debugging:
311
312       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
318       Fuller  decoding of the various records can be obtained by using the -A
319       , -d , -k and -p flags.
320

DECRYPTION

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
329       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
340       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

BUGS

348       Please send bug reports to ssldump@rtfm.com.
349
350       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
354       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
359       ssldump doesn't implement session caching and therefore  can't  decrypt
360       resumed sessions.
361

SEE ALSO

363       tcpdump(1)
364

AUTHOR

366       ssldump was written by Eric Rescorla <ekr@rtfm.com>.
367
368
369
370                               28 September 2001                    SSLDUMP(1)
Impressum