           ssldump - dump SSL traffic on a network

## SYNOPSIS

           ssldump [ -vtaTnsAxXhHVNdq ] [ -r dumpfile ]
           [ -i interface ] [ -k keyfile ] [ -p password ] [ expression ]

## DESCRIPTION

           ssldump 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.   Under
           SunOS  with  nit or bpf: To run tcpdump you must have read
           access to /dev/nit or /dev/bpf*.  Under Solaris with dlpi:
           You  must  have  read access to the network pseudo device,
           e.g.  /dev/le.  Under HP-UX with dlpi: You must be root or
           it  must  be  installed  setuid  to root.  Under IRIX with
           snoop: You must be root or it must be installed setuid  to
           root.   Under  Linux:  You  must  be  root  or  it must be
           installed setuid to root.  Under Ultrix and Digital  UNIX:
           Once the super-user has enabled promiscuous-mode operation
           using pfconfig(8), any user may run ssldump Under BSD: You
           must have read access to /dev/bpf*.

## OPTIONS

           -a     Print bare TCP ACKs (useful for observing Nagle behav-
                  ior)

           -A     Print all record fields (by default ssldump chooses
                  the most interesting fields)

           -d     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.

           -e     Print   absolute  timestamps  instead  of  relative
                  timestamps

           -r     Read data from file instead of  from  the  network.
                  The old -f option still works but is deprecated and
                  will probably be removed with the next version.

           -H
                  Print the full SSL packet header.

           -k     Use  keyfile  as  the  location  of the SSL keyfile
                  (OpenSSL format)  ssldump  automatically  looks  in
                  ./server.pem.

           -n     Don't try to resolve host names from IP addresses

           -N     Attempt  to parse ASN.1 when it appears, such as in
                  certificates and DNs.

           -p     Use password as the SSL keyfile password default is
                  "password".

           -q     Don't decode any record fields beyond a single sum-
                  mary line. (quiet mode).

           -x     Print each record in hex, as well as decoding it.

           -X     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.  -y Decorate the
                  output for processing with troff. Not  very  useful
                  for the average user.

            expression
                  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  expression consists of one or more primitives.
                  Primitives usually consist of an id (name  or  num-
                  ber) preceded by one or more qualifiers.  There are
                  three different kinds of qualifier:

                         are host, net and port.  E.g.,  `host  foo',
                         `net 128.3', `port 20'.  If there is no type
                         qualifier, host is assumed.

                  dir    qualifiers  specify  a  particular  transfer
                         direction   to  and/or  from  id.   Possible
                         directions are src, dst, src or dst and  src
                         and  dst.  E.g., `src foo', `dst net 128.3',
                         `src or dst port ftp-data'.  If there is  no
                         dir  qualifier,  src or dst is assumed.  For
                         `null' link layers (i.e. point to point pro-
                         tocols  such  as  slip) the inbound and out-
                         bound qualifiers can be used  to  specify  a
                         desired direction.

                  More  complex  filter  expressions  are built up by
                  using the words and, or and not 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:

                  dst host host
                         True if the IPv4/v6 destination field of the
                         packet  is  host,  which  may  be  either an
                         address or a name.

                  src host host
                         True if the  IPv4/v6  source  field  of  the
                         packet is host.

                  host host
                         True  if either the IPv4/v6 source or desti-
                         nation of the packet is host.   Any  of  the
                         above host expressions can be prepended with
                         the keywords, ip, arp, rarp, or ip6 as in:
                              ip host host
                         which is equivalent to:
                              ether proto \ip and host host
                         If  host  is  a  name   with   multiple   IP
                         addresses,  each address will be checked for
                         a match.

                  ether dst ehost
                         True if the ethernet destination address  is
                         ehost.   Ehost  may  be  either  a name from
                         /etc/ethers or a number (see ethers(3N)  for
                         numeric format).
                         True  if  the  ethernet  source  address  is
                         ehost.

                  ether host ehost
                         True if either the ethernet source or desti-
                         nation address is ehost.

                  gateway host
                         True  if  the packet used host as a gateway.
                         I.e., the  ethernet  source  or  destination
                         address  was  host but neither the IP source
                         nor the IP destination was host.  Host  must
                         be   a  name  and  must  be  found  in  both
                         /etc/hosts and /etc/ethers.  (An  equivalent
                         expression is
                              ether host ehost and not host host
                         which  can be used with either names or num-
                         bers for host / ehost.)   This  syntax  does
                         not  work  in  IPv6-enabled configuration at
                         this moment.

                  dst net net
                         True if the IPv4/v6 destination  address  of
                         the  packet has a network number of net. Net
                         may be either a name from /etc/networks or a
                         network    number   (see   networks(4)   for
                         details).

                  src net net
                         True if the IPv4/v6 source  address  of  the
                         packet has a network number of net.

                  net net
                         True  if either the IPv4/v6 source or desti-
                         nation address of the packet has  a  network
                         number of net.

                  net net mask mask
                         True  if the IP address matches net with the
                         specific netmask.  May be qualified with src
                         or  dst.  Note that this syntax is not valid
                         for IPv6 net.

                  net net/len
                         True if the IPv4/v6 address  matches  net  a
                         netmask  len  bits  wide.   May be qualified
                         with src or dst.

                  dst port port
                         True  if  the  packet  is  ip/tcp,   ip/udp,
                         ip6/tcp  or  ip6/udp  and  has a destination
                         port value of port.  The port 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.,
                         dst port 513 will print both tcp/login traf-
                         fic  and  udp/who  traffic,  and port domain
                         will print both  tcp/domain  and  udp/domain
                         traffic).

                  src port port
                         True  if  the packet has a source port value
                         of port.

                  port port
                         True if either  the  source  or  destination
                         port  of  the  packet  is  port.  Any of the
                         above port expressions can be prepended with
                         the keywords, tcp or udp, as in:
                              tcp src port port
                         which  matches only tcp packets whose source
                         port is port.

                  Primitives may be combined using:

                         A  parenthesized  group  of  primitives  and
                         operators  (parentheses  are  special to the
                         Shell and must be escaped).

                         Negation (`!' or `not').

                         Concatenation (`&&' or `and').

                         Alternation (`||' or `or').

                  Negation has highest precedence.   Alternation  and
                  concatenation  have  equal precedence and associate
                  left to right.  Note that explicit and tokens,  not
                  juxtaposition,  are now required for concatenation.

                  If an identifier is given without  a  keyword,  the
                  most recent keyword is assumed.  For example,
                       not host vs and ace
                  is short for
                       not host vs and host ace
                  which should not be confused with
                       not ( host vs or ace )

                  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 le0 port 443
                  ssldump -i le0 port 443

           To listen to traffic to the server romeo on port 443.
                  ssldump -i le0 port 443 and host romeo

           To  decrypt  traffic  to  to host romeo server.pem and the
           password foobar
                  ssldump -Ad -k ~/server.pem -p foobar -i le0 host romeo

## OUTPUT FORMAT

           All output is printed to standard out.

           ssldump prints an indication of every new  TCP  connection
           using a line like the following

           New TCP connection #2: iromeo.rtfm.com(2302) <-> sr1.rtfm.com(4433)

           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 iromeo.rtfm.com (port 2303) to
           sr1.rtfm.com (port 4433). To allow the user to disentangle
           traffic  from  different  connections,  each connection is
           numbered. This is connection 2.

           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:

           2 3  0.2001 (0.0749)  S>C  Handshake      Certificate

           This is record 3 on connection 2. 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. C>S  indicates  records  transmitted
           from  client to server and S>C 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  Handshake,
           IAlert,  ChangeCipherSpec,  or  application_data. Finally,
           ssldump may print record-specific data on the rest of  the
           line.  For Handshake records, it prints the handshake mes-
           sage. Thus, this record is a Certificate message.

           ssldump chooses certain record types for further decoding.

           ClientHello - version, offered cipher suites, session id
                                if provided)
           ServerHello - version, session_id, chosen cipher suite,
                          compression method
           Alert - type and level (if obtainable)

           Fuller decoding of the various records can be obtained  by
           using the -A , -d , -k and -p flags.

## DECRYPTION

           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.

           1 5  0.4129 (0.1983)  C>S  Handshake      ClientKeyExchange
           1 6  0.4129 (0.0000)  C>S  ChangeCipherSpec
           1 7  0.4129 (0.0000)  C>S  Handshake
           1 8  0.5585 (0.1456)  S>C  ChangeCipherSpec
           1 9  0.6135 (0.0550)  S>C  Handshake
           1 10 2.3121 (1.6986)  C>S  application_data
           1 11 2.5336 (0.2214)  C>S  application_data
           1 12 2.5545 (0.0209)  S>C  application_data
           1 13 2.5592 (0.0046)  S>C  application_data
           1 14 2.5592 (0.0000)  S>C  Alert

           Note that the ClientKeyExchange message  type  is  printed
           but  the rest of the Handshake messages do not have types.
           These are the Finished  messages,  but  because  they  are
           encrypted  ssldump  only knows that they are of type Hand-
           shake.  Similarly, had the Alert  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.

## BUGS

           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.