Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SSLDUMP(1)		    General Commands Manual		    SSLDUMP(1)

NAME
       ssldump - dump SSL traffic on a network

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

DESCRIPTION
       ssldump is an SSL/TLS network protocol analyzer.	It identifies TCP con-
       nections	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	trans-
       mission	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 behavior)

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

       -d     Display the application data traffic.  This  usually  means  de-
	      crypting it, but when -d is used ssldump will also decode	appli-
	      cation data traffic before the SSL session initiates.  This  al-
	      lows 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.  non-ASCII  data  is
	      displayed	as hex dumps. See also -X.

       -e     Print absolute timestamps	instead	of relative timestamps

       -H     Print the	full SSL packet	header.

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

       -P     Don't put	the interface into promiscuous mode.

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

       -T     Print the	TCP headers.

       -v     Display version and copyright information.

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

       -X     When the -d option is used, binary data is automatically printed
	      in two columns with a hex	dump on	the  left  and	the  printable
	      characters on the	right. -X suppresses the display of the	print-
	      able characters, thus making it easier to	cut and	paste the  hex
	      data into	some other program.

       -y     Decorate	the  output  for processing with nroff/troff. Not very
	      useful for the average user.

       -i interface
	      Use interface as the network interface on	which to sniff SSL/TLS
	      traffic.

       -k keyfile
	      Use  keyfile as the location of the SSL keyfile (OpenSSL format)
	      Previous	 versions   of	 ssldump   automatically   looked   in
	      ./server.pem.  Now you must specify your keyfile every time.

       -p password
	      Use password as the SSL keyfile password.

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

       -S [ crypto | d | ht | H	]
	      Specify SSL flags	to ssldump.  These flags include:

	      crypto Print cryptographic information.

	      d	     Print fields as decoded.

	      ht     Print the handshake type.

	      H	     Print handshake type and highlights.

       expression
	      Selects what packets ssldump will	examine. Technically speaking,
	      ssldump supports the full	expression syntax from PCAP  and  tcp-
	      dump.  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	number)	 preceded  by  one  or
	      more qualifiers.	There are three	different kinds	of qualifier:

	      type   qualifiers	 say  what kind	of thing the id	name or	number
		     refers to.	 Possible types	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	quali-
		     fier, src or dst is  assumed.   For  `null'  link	layers
		     (i.e.  point to point protocols such as slip) the inbound
		     and outbound 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 primitives.  E.g., `host foo and  not
	      port  ftp	 and  not  port	 ftp-data'.  To	save typing, identical
	      qualifier	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 destination	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 ad-
		     dress 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).

	      ether src	ehost
		     True if the ethernet source address is ehost.

	      ether host ehost
		     True if either the	ethernet source	or destination 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  nei-
		     ther 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 numbers for	host /
		     ehost.)  This syntax does not work	in  IPv6-enabled  con-
		     figuration	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 destination address
		     of	the packet has a network number	of net.

	      net net mask mask
		     True if the IP address matches net	with the specific net-
		     mask.   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 number or a name used in /etc/services (see tcp(4P)
		     and udp(4P)).  If a name is used, 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 traffic and udp/who traf-
		     fic, 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 (paren-
		     theses 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 ar-
	      guments are concatenated with spaces before being	parsed.

EXAMPLES
       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  pre-
       vious record. Both are in seconds.

       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  transmitted 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, ChangeCi-
       pherSpec, or application_data. Finally, ssldump may  print  record-spe-
       cific  data  on	the rest of the	line. For Handshake records, it	prints
       the handshake message. Thus, this record	is a Certificate message.

       ssldump chooses certain record types for	further	 decoding.  These  are
       the ones	that have proven to be most useful for debugging:

       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 following two con-
       ditions 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 mes-
       sages, but because they are encrypted ssldump only knows	that they  are
       of type Handshake.  Similarly, had the Alert in record 14 happened dur-
       ing the handshake, it's type and	level would have  been	printed.  How-
       ever, 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 be-
       cause 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.

SEE ALSO
       tcpdump(1)

AUTHOR
       ssldump was written by Eric Rescorla <ekr@rtfm.com>.

			       28 September 2001		    SSLDUMP(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | OUTPUT FORMAT | DECRYPTION | BUGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ssldump&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help