mirror of
https://github.com/adulau/ssldump.git
synced 2024-09-18 00:38:14 +00:00
394 lines
20 KiB
HTML
394 lines
20 KiB
HTML
<HTML>
|
|
<BODY>
|
|
<PRE>
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
|
<!-- Tiny bit of hand editing by GHS -->
|
|
ssldump - dump SSL traffic on a network
|
|
|
|
|
|
</PRE>
|
|
<H2>SYNOPSIS</H2><PRE>
|
|
<B>ssldump</B> [ <B>-vtaTnsAxXhHVNdq</B> ] [ <B>-r</B> <I>dumpfile</I> ]
|
|
[ <B>-i</B> <I>interface</I> ] [ <B>-k</B> <I>keyfile</I> ] [ <B>-p</B> <I>password</I> ] [ <I>expression</I> ]
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
<I>ssldump</I> is an SSL/TLS network protocol analyzer. It iden-
|
|
tifies TCP connections on the chosen network interface and
|
|
attempts to interpret them as SSL/TLS traffic. When it
|
|
identifies SSL/TLS traffic, it decodes the records and
|
|
displays them in a textual form to stdout. If provided
|
|
with the appropriate keying material, it will also decrypt
|
|
the connections and display the application data traffic.
|
|
|
|
ssldump has been tested on FreeBSD, Linux, Solaris, and
|
|
HP/UX. Since it's based on PCAP, it should work on most
|
|
platforms. However, unlike tcpdump, ssldump needs to be
|
|
able to see both sides of the data transmission so you may
|
|
have trouble using it with network taps such as SunOS nit
|
|
that don't permit you to see transmitted data. <B>Under</B>
|
|
<B>SunOS</B> <B>with</B> <B>nit</B> <B>or</B> <B>bpf:</B> To run <I>tcpdump</I> you must have read
|
|
access to <I>/dev/nit</I> or <I>/dev/bpf*</I>. <B>Under</B> <B>Solaris</B> <B>with</B> <B>dlpi:</B>
|
|
You must have read access to the network pseudo device,
|
|
e.g. <I>/dev/le</I>. <B>Under</B> <B>HP-UX</B> <B>with</B> <B>dlpi:</B> You must be root or
|
|
it must be installed setuid to root. <B>Under</B> <B>IRIX</B> <B>with</B>
|
|
<B>snoop:</B> You must be root or it must be installed setuid to
|
|
root. <B>Under</B> <B>Linux:</B> You must be root or it must be
|
|
installed setuid to root. <B>Under</B> <B>Ultrix</B> <B>and</B> <B>Digital</B> <B>UNIX:</B>
|
|
Once the super-user has enabled promiscuous-mode operation
|
|
using <B>pfconfig(8)</B>, any user may run <B>ssldump</B> <B>Under</B> <B>BSD:</B> You
|
|
must have read access to <I>/dev/bpf*</I>.
|
|
|
|
|
|
</PRE>
|
|
<H2>OPTIONS</H2><PRE>
|
|
<B>-a</B> Print bare TCP ACKs (useful for observing Nagle behav-
|
|
ior)
|
|
|
|
<B>-A</B> Print all record fields (by default ssldump chooses
|
|
the most interesting fields)
|
|
|
|
<B>-d</B> Display the application data traffic. This usually
|
|
means decrypting it, but when -d is used ssldump
|
|
will also decode application data traffic _before_
|
|
the SSL session initiates. This allows you to see
|
|
HTTPS CONNECT behavior as well as SMTP STARTTLS. As
|
|
a side effect, since ssldump can't tell whether
|
|
plaintext is traffic before the initiation of an
|
|
SSL connection or just a regular TCP connection,
|
|
this allows you to use ssldump to sniff any TCP
|
|
connection. ssldump will automatically detect
|
|
ASCII data and display it directly to the screen.
|
|
|
|
<B>-e</B> Print absolute timestamps instead of relative
|
|
timestamps
|
|
|
|
<B>-r</B> Read data from <I>file</I> instead of from the network.
|
|
The old -f option still works but is deprecated and
|
|
will probably be removed with the next version.
|
|
|
|
<B>-H</B>
|
|
Print the full SSL packet header.
|
|
|
|
<B>-k</B> Use <I>keyfile</I> as the location of the SSL keyfile
|
|
(OpenSSL format) ssldump automatically looks in
|
|
./server.pem.
|
|
|
|
<B>-n</B> Don't try to resolve host names from IP addresses
|
|
|
|
<B>-N</B> Attempt to parse ASN.1 when it appears, such as in
|
|
certificates and DNs.
|
|
|
|
<B>-p</B> Use <I>password</I> as the SSL keyfile password default is
|
|
"password".
|
|
|
|
<B>-q</B> Don't decode any record fields beyond a single sum-
|
|
mary line. (quiet mode).
|
|
|
|
<B>-x</B> Print each record in hex, as well as decoding it.
|
|
|
|
<B>-X</B> When the -d option is used, binary data is automat-
|
|
ically printed in two columns with a hex dump on
|
|
the left and the printable characters on the right.
|
|
-X suppresses the display of the printable charac-
|
|
ters, thus making it easier to cut and paste the
|
|
hext data into some other program. <B>-y</B> Decorate the
|
|
output for processing with troff. Not very useful
|
|
for the average user.
|
|
|
|
|
|
<I>expression</I>
|
|
Selects what packets ssldump will examine. Techni-
|
|
cally speaking, ssldump supports the full expres-
|
|
sion syntax from PCAP and tcpdump. In fact, the
|
|
description here is cribbed from the tcpdump man
|
|
page. However, since ssldump needs to examine full
|
|
TCP streams, most of the tcpdump expressions will
|
|
select traffic mixes that ssldump will simply
|
|
ignore. Only the expressions which don't result in
|
|
incomplete TCP streams are listed here.
|
|
|
|
The <I>expression</I> consists of one or more <I>primitives.</I>
|
|
Primitives usually consist of an <I>id</I> (name or num-
|
|
ber) preceded by one or more qualifiers. There are
|
|
three different kinds of qualifier:
|
|
|
|
are <B>host</B>, <B>net</B> and <B>port</B>. E.g., `host foo',
|
|
`net 128.3', `port 20'. If there is no type
|
|
qualifier, <B>host</B> is assumed.
|
|
|
|
<I>dir</I> qualifiers specify a particular transfer
|
|
direction to and/or from <I>id.</I> Possible
|
|
directions are <B>src</B>, <B>dst</B>, <B>src</B> <B>or</B> <B>dst</B> and <B>src</B>
|
|
<B>and</B> <B>dst</B>. E.g., `src foo', `dst net 128.3',
|
|
`src or dst port ftp-data'. If there is no
|
|
dir qualifier, <B>src</B> <B>or</B> <B>dst</B> is assumed. For
|
|
`null' link layers (i.e. point to point pro-
|
|
tocols such as slip) the <B>inbound</B> and <B>out-</B>
|
|
<B>bound</B> qualifiers can be used to specify a
|
|
desired direction.
|
|
|
|
More complex filter expressions are built up by
|
|
using the words <B>and</B>, <B>or</B> and <B>not</B> to combine primi-
|
|
tives. E.g., `host foo and not port ftp and not
|
|
port ftp-data'. To save typing, identical quali-
|
|
fier lists can be omitted. E.g., `tcp dst port ftp
|
|
or ftp-data or domain' is exactly the same as `tcp
|
|
dst port ftp or tcp dst port ftp-data or tcp dst
|
|
port domain'.
|
|
|
|
Allowable primitives are:
|
|
|
|
<B>dst</B> <B>host</B> <I>host</I>
|
|
True if the IPv4/v6 destination field of the
|
|
packet is <I>host</I>, which may be either an
|
|
address or a name.
|
|
|
|
<B>src</B> <B>host</B> <I>host</I>
|
|
True if the IPv4/v6 source field of the
|
|
packet is <I>host</I>.
|
|
|
|
<B>host</B> <I>host</I>
|
|
True if either the IPv4/v6 source or desti-
|
|
nation of the packet is <I>host</I>. Any of the
|
|
above host expressions can be prepended with
|
|
the keywords, <B>ip</B>, <B>arp</B>, <B>rarp</B>, or <B>ip6</B> as in:
|
|
<B>ip</B> <B>host</B> <I>host</I>
|
|
which is equivalent to:
|
|
<B>ether</B> <B>proto</B> <I>\ip</I> <B>and</B> <B>host</B> <I>host</I>
|
|
If <I>host</I> is a name with multiple IP
|
|
addresses, each address will be checked for
|
|
a match.
|
|
|
|
<B>ether</B> <B>dst</B> <I>ehost</I>
|
|
True if the ethernet destination address is
|
|
<I>ehost</I>. <I>Ehost</I> may be either a name from
|
|
/etc/ethers or a number (see <B>ethers(3N)</B> for
|
|
numeric format).
|
|
True if the ethernet source address is
|
|
<I>ehost</I>.
|
|
|
|
<B>ether</B> <B>host</B> <I>ehost</I>
|
|
True if either the ethernet source or desti-
|
|
nation address is <I>ehost</I>.
|
|
|
|
<B>gateway</B> <I>host</I>
|
|
True if the packet used <I>host</I> as a gateway.
|
|
I.e., the ethernet source or destination
|
|
address was <I>host</I> but neither the IP source
|
|
nor the IP destination was <I>host</I>. <I>Host</I> must
|
|
be a name and must be found in both
|
|
/etc/hosts and /etc/ethers. (An equivalent
|
|
expression is
|
|
<B>ether</B> <B>host</B> <I>ehost</I> <B>and</B> <B>not</B> <B>host</B> <I>host</I>
|
|
which can be used with either names or num-
|
|
bers for <I>host</I> <I>/</I> <I>ehost</I>.) This syntax does
|
|
not work in IPv6-enabled configuration at
|
|
this moment.
|
|
|
|
<B>dst</B> <B>net</B> <I>net</I>
|
|
True if the IPv4/v6 destination address of
|
|
the packet has a network number of <I>net</I>. <I>Net</I>
|
|
may be either a name from /etc/networks or a
|
|
network number (see <I>networks(4)</I> for
|
|
details).
|
|
|
|
<B>src</B> <B>net</B> <I>net</I>
|
|
True if the IPv4/v6 source address of the
|
|
packet has a network number of <I>net</I>.
|
|
|
|
<B>net</B> <I>net</I>
|
|
True if either the IPv4/v6 source or desti-
|
|
nation address of the packet has a network
|
|
number of <I>net</I>.
|
|
|
|
<B>net</B> <I>net</I> <B>mask</B> <I>mask</I>
|
|
True if the IP address matches <I>net</I> with the
|
|
specific netmask. May be qualified with <B>src</B>
|
|
or <B>dst</B>. Note that this syntax is not valid
|
|
for IPv6 <I>net</I>.
|
|
|
|
<B>net</B> <I>net</I>/<I>len</I>
|
|
True if the IPv4/v6 address matches <I>net</I> a
|
|
netmask <I>len</I> bits wide. May be qualified
|
|
with <B>src</B> or <B>dst</B>.
|
|
|
|
<B>dst</B> <B>port</B> <I>port</I>
|
|
True if the packet is ip/tcp, ip/udp,
|
|
ip6/tcp or ip6/udp and has a destination
|
|
port value of <I>port</I>. The <I>port</I> can be a num-
|
|
both the port number and protocol are
|
|
checked. If a number or ambiguous name is
|
|
used, only the port number is checked (e.g.,
|
|
<B>dst</B> <B>port</B> <B>513</B> will print both tcp/login traf-
|
|
fic and udp/who traffic, and <B>port</B> <B>domain</B>
|
|
will print both tcp/domain and udp/domain
|
|
traffic).
|
|
|
|
<B>src</B> <B>port</B> <I>port</I>
|
|
True if the packet has a source port value
|
|
of <I>port</I>.
|
|
|
|
<B>port</B> <I>port</I>
|
|
True if either the source or destination
|
|
port of the packet is <I>port</I>. Any of the
|
|
above port expressions can be prepended with
|
|
the keywords, <B>tcp</B> or <B>udp</B>, as in:
|
|
<B>tcp</B> <B>src</B> <B>port</B> <I>port</I>
|
|
which matches only tcp packets whose source
|
|
port is <I>port</I>.
|
|
|
|
Primitives may be combined using:
|
|
|
|
A parenthesized group of primitives and
|
|
operators (parentheses are special to the
|
|
Shell and must be escaped).
|
|
|
|
Negation (`<B>!</B>' or `<B>not</B>').
|
|
|
|
Concatenation (`<B>&&</B>' or `<B>and</B>').
|
|
|
|
Alternation (`<B>||</B>' or `<B>or</B>').
|
|
|
|
Negation has highest precedence. Alternation and
|
|
concatenation have equal precedence and associate
|
|
left to right. Note that explicit <B>and</B> tokens, not
|
|
juxtaposition, are now required for concatenation.
|
|
|
|
If an identifier is given without a keyword, the
|
|
most recent keyword is assumed. For example,
|
|
<B>not</B> <B>host</B> <B>vs</B> <B>and</B> <B>ace</B>
|
|
is short for
|
|
<B>not</B> <B>host</B> <B>vs</B> <B>and</B> <B>host</B> <B>ace</B>
|
|
which should not be confused with
|
|
<B>not</B> <B>(</B> <B>host</B> <B>vs</B> <B>or</B> <B>ace</B> <B>)</B>
|
|
|
|
Expression arguments can be passed to ssldump as
|
|
either a single argument or as multiple arguments,
|
|
whichever is more convenient. Generally, if the
|
|
expression contains Shell metacharacters, it is
|
|
easier to pass it as a single, quoted argument.
|
|
Multiple arguments are concatenated with spaces
|
|
|
|
To listen to traffic on interface <I>le0</I> port <I>443</I>
|
|
<B>ssldump</B> <B>-i</B> <B>le0</B> <B>port</B> <B>443</B>
|
|
|
|
To listen to traffic to the server <I>romeo</I> on port <I>443</I>.
|
|
<B>ssldump</B> <B>-i</B> <B>le0</B> <B>port</B> <B>443</B> <B>and</B> <B>host</B> <B>romeo</B>
|
|
|
|
To decrypt traffic to to host <I>romeo</I> <I>server.pem</I> and the
|
|
password <I>foobar</I>
|
|
<B>ssldump</B> <B>-Ad</B> <B>-k</B> <B>~/server.pem</B> <B>-p</B> <B>foobar</B> <B>-i</B> <B>le0</B> <B>host</B> <B>romeo</B>
|
|
|
|
|
|
</PRE>
|
|
<H2>OUTPUT FORMAT</H2><PRE>
|
|
All output is printed to standard out.
|
|
|
|
ssldump prints an indication of every new TCP connection
|
|
using a line like the following
|
|
|
|
<B>New</B> <B>TCP</B> <B>connection</B> <B>#2:</B> <B>iromeo.rtfm.com(2302)</B> <B><-></B> <B>sr1.rtfm.com(4433)</B>
|
|
|
|
The host which send the first SYN is printed on the left
|
|
and the host which responded is printed on the right.
|
|
Ordinarily, this means that the SSL client will be printed
|
|
on the left with the SSL server on the right. In this case
|
|
we have a connection from <I>iromeo.rtfm.com</I> (port <I>2303</I>) to
|
|
<I>sr1.rtfm.com</I> (port <I>4433</I>). To allow the user to disentangle
|
|
traffic from different connections, each connection is
|
|
numbered. This is connection <I>2</I>.
|
|
|
|
The printout of each SSL record begins with a record line.
|
|
This line contains the connection and record number, a
|
|
timestamp, and the record type, as in the following:
|
|
|
|
<B>2</B> <B>3</B> <B>0.2001</B> <B>(0.0749)</B> <B>S>C</B> <B>Handshake</B> <B>Certificate</B>
|
|
|
|
This is record <I>3</I> on connection <I>2</I>. The first timestamp is
|
|
the time since the beginning of the connection. The second
|
|
is the time since the previous record. Both are in sec-
|
|
onds.
|
|
|
|
The next field in the record line is the direction that
|
|
the record was going. <I>C>S</I> indicates records transmitted
|
|
from client to server and <I>S>C</I> indicates records transmit-
|
|
ted from server to client. ssldump assumes that the host
|
|
to transmit the first SYN is the SSL client (this is
|
|
nearly always correct).
|
|
|
|
The next field is the record type, one of <I>Handshake</I>,
|
|
<I>IAlert</I>, <I>ChangeCipherSpec</I>, or <I>application</I><B>_</B><I>data</I>. Finally,
|
|
ssldump may print record-specific data on the rest of the
|
|
line. For <I>Handshake</I> records, it prints the handshake mes-
|
|
sage. Thus, this record is a <I>Certificate</I> message.
|
|
|
|
ssldump chooses certain record types for further decoding.
|
|
|
|
<I>ClientHello</I> - version, offered cipher suites, session id
|
|
if provided)
|
|
<I>ServerHello</I> - version, session_id, chosen cipher suite,
|
|
compression method
|
|
<I>Alert</I> - type and level (if obtainable)
|
|
|
|
Fuller decoding of the various records can be obtained by
|
|
using the <B>-A</B> , <B>-d</B> , <B>-k</B> and <B>-p</B> flags.
|
|
|
|
|
|
|
|
</PRE>
|
|
<H2>DECRYPTION</H2><PRE>
|
|
ssldump can decrypt traffic between two hosts if the fol-
|
|
lowing two conditions are met:
|
|
1. ssldump has the keys.
|
|
2. Static RSA was used.
|
|
In any other case, once encryption starts, ssldump will
|
|
only be able to determine the record type. Consider the
|
|
following section of a trace.
|
|
|
|
<B>1</B> <B>5</B> <B>0.4129</B> <B>(0.1983)</B> <B>C>S</B> <B>Handshake</B> <B>ClientKeyExchange</B>
|
|
<B>1</B> <B>6</B> <B>0.4129</B> <B>(0.0000)</B> <B>C>S</B> <B>ChangeCipherSpec</B>
|
|
<B>1</B> <B>7</B> <B>0.4129</B> <B>(0.0000)</B> <B>C>S</B> <B>Handshake</B>
|
|
<B>1</B> <B>8</B> <B>0.5585</B> <B>(0.1456)</B> <B>S>C</B> <B>ChangeCipherSpec</B>
|
|
<B>1</B> <B>9</B> <B>0.6135</B> <B>(0.0550)</B> <B>S>C</B> <B>Handshake</B>
|
|
<B>1</B> <B>10</B> <B>2.3121</B> <B>(1.6986)</B> <B>C>S</B> <B>application_data</B>
|
|
<B>1</B> <B>11</B> <B>2.5336</B> <B>(0.2214)</B> <B>C>S</B> <B>application_data</B>
|
|
<B>1</B> <B>12</B> <B>2.5545</B> <B>(0.0209)</B> <B>S>C</B> <B>application_data</B>
|
|
<B>1</B> <B>13</B> <B>2.5592</B> <B>(0.0046)</B> <B>S>C</B> <B>application_data</B>
|
|
<B>1</B> <B>14</B> <B>2.5592</B> <B>(0.0000)</B> <B>S>C</B> <B>Alert</B>
|
|
|
|
Note that the <I>ClientKeyExchange</I> message type is printed
|
|
but the rest of the <I>Handshake</I> messages do not have types.
|
|
These are the <I>Finished</I> messages, but because they are
|
|
encrypted ssldump only knows that they are of type <I>Hand-</I>
|
|
<I>shake</I>. Similarly, had the <I>Alert</I> in record 14 happened
|
|
during the handshake, it's type and level would have been
|
|
printed. However, since it is encrypted we can only tell
|
|
that it is an alert.
|
|
|
|
|
|
|
|
</PRE>
|
|
<H2>BUGS</H2><PRE>
|
|
Please send bug reports to ssldump@rtfm.com.
|
|
|
|
The TCP reassembler is not perfect. No attempt is made to
|
|
reassemble IP fragments and the 3-way handshake and close
|
|
handshake are imperfectly implemented. In practice, this
|
|
turns out not to be much of a problem.
|
|
|
|
Support is provided for only for Ethernet and loopback
|
|
interfaces because that's all that I have. If you have
|
|
another kind of network you will need to modify pcap_cb in
|
|
base/pcap-snoop.c. If you have direct experience with ssldump
|
|
on other networks, please send me patches.
|
|
|
|
ssldump doesn't implement session caching and therefore
|
|
can't decrypt resumed sessions.
|
|
|
|
|
|
</PRE>
|
|
<HR>
|
|
<ADDRESS>
|
|
Man(1) output converted with
|
|
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
|
|
</ADDRESS>
|
|
</BODY>
|
|
</HTML>
|