1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/cmd/ssltap/ssltap-manual.html Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,170 @@
1.4 +<HTML>
1.5 +<!-- This Source Code Form is subject to the terms of the Mozilla Public
1.6 + - License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
1.8 +<HEAD>
1.9 + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
1.10 + <META NAME="GENERATOR" CONTENT="Mozilla/4.05 [en] (WinNT; U) [Netscape]">
1.11 + <META NAME="Author" CONTENT="Steve Parkinson">
1.12 + <TITLE>SSLTap - manual</TITLE>
1.13 +</HEAD>
1.14 +<BODY>
1.15 +
1.16 +<H1>
1.17 +SSLTap Manual page</H1>
1.18 +
1.19 +<H3>
1.20 +Summary</H3>
1.21 +A command-line proxy which is SSL-aware. It snoops on TCP connections,
1.22 +and displays the data going by, including SSL records and handshaking
1.23 +if the connection is SSL.
1.24 +<H3>
1.25 +Synopsis</H3>
1.26 +<TT>ssltap [-vhfsxl] [-p port] hostname:port</TT>
1.27 +
1.28 +<P><TT> -v [prints version string]</TT>
1.29 +<BR><TT> -h [outputs hex instead
1.30 +of ASCII]</TT>
1.31 +<BR><TT> -f [turn on Fancy HTML
1.32 +coloring]</TT>
1.33 +<BR><TT> -s [turn on SSL decoding]</TT>
1.34 +<BR><TT> -x [turn on extra SSL
1.35 +hex dumps]</TT>
1.36 +<BR><TT> -p port [specify rendezvous port (default 1924)]</TT>
1.37 +<BR><TT> -l [loop - continue
1.38 +to wait for more connections]</TT>
1.39 +<H3>
1.40 +Description</H3>
1.41 +SSLTap opens a socket on a rendezvous port, and waits for an incoming connection
1.42 +(client side). Once this connection arrives, SSLTap makes another connection
1.43 +to hostname:port (server side). It passes any data sent by the client to
1.44 +the server, and vice versa. However, SSLTap will also display the data
1.45 +to the console. It can do this for plain HTTP connections, or any TCP protocol.
1.46 +However, SSLTap can also work with SSL streams, as detailed below.
1.47 +
1.48 +<P>Let's assume your development machine is called 'intercept'. The simplest
1.49 +usage of SSLTap is to run the command <TT>'ssltap www.netscape.com:80'</TT>
1.50 +on intercept. The program will wait for an incoming connection on port
1.51 +1924. Next you would want to go to your browser, and enter the URL http://intercept:1924.
1.52 +The page retrieved by the browser will actually be gotten from the server
1.53 +at www.netscape.com, but will go via SSLTap.
1.54 +
1.55 +<P>Data sent from the client to the server is surrounded by a '--> [ ]'
1.56 +symbol, and data sent from the server to the client, a '<---[
1.57 +]' symbol.
1.58 +
1.59 +<P>You'll notice that the page retrieved with this example looks incomplete.
1.60 +This is because SSLTap by default closes down after the first connection
1.61 +is complete, so the browser is not able to load images. To make the SSLTap
1.62 +continue to accept connections, switch on looping mode with the -l option.
1.63 +
1.64 +<P>You can change the default rendezvous port to something else with the
1.65 +-p option.
1.66 +
1.67 +<P>The remaining options change the way the output is produced.
1.68 +
1.69 +<P>The -f option prints 'fancy' output - in colored HTML. Data sent from
1.70 +the client to the server is in blue. The server's reply is in red. This
1.71 +is designed so you can load the output up into a browser. When used with
1.72 +looping mode, the different connections are separated with horizontal lines.
1.73 +
1.74 +<P>-x will turn on HEX printing. Instead of being output as ascii, the
1.75 +data is shown as Hex, like this:
1.76 +<UL><TT><-- [</TT>
1.77 +<BR><TT> 0: 56 d5 16 3e a1 6b b1 4a 8f 67 c4 d7
1.78 +21 2f 6f dd | V..>.k.J.g..!/o.</TT>
1.79 +<BR><TT> 10: bb 22 c4 75 8c f4 ce 28 16 a6 20 aa
1.80 +fb 9a 59 a1 | .".u...(.. ...Y.</TT>
1.81 +<BR><TT> 20: 51 91 14 d2 fc 9f a7 ea 4d 9c f7 3a
1.82 +9d 83 62 4a | Q.......M..:..bJ</TT>
1.83 +<BR><TT>]</TT>
1.84 +<BR> </UL>
1.85 +
1.86 +<H4>
1.87 +SSL Parse mode</H4>
1.88 +The following options deal with SSL connections.
1.89 +<UL>-s will turn on SSL parsing. (SSLTap doesn't automatically detect SSL
1.90 +sessions.)
1.91 +<BR>-x will turn on extra SSL hexdumps. Mostly, if SSL can decode the data,
1.92 +it doesn't display the hex.</UL>
1.93 +The following SSL3 Data structures are parsed: Handshake, ClientHello,
1.94 +ServerHello, CertificateChain, Certificate. In addition, SSL2 ClientHello,
1.95 +ServerHello, ClientMasterKey are also partly parsed. NO DECRYPTION IS PERFORMED
1.96 +ON THE DATA. SSLTAP CANNOT DECRYPT the data.
1.97 +
1.98 +<P>If a certificate chain is detected, DER-encoded certificates will be
1.99 +saved into files in the current directory called 'cert.0x' where x is the
1.100 +sequence number of the certificate.
1.101 +<BR>
1.102 +<H3>
1.103 +Operation Hints</H3>
1.104 +Often, you'll find that the server certificate does not get transferred,
1.105 +or other parts of the handshake do not happen. This is because the browser
1.106 +is taking advantage of session-id-reuse (using the handshake results from
1.107 +a previous session). If you restart the browser, it'll clear the session
1.108 +id cache.
1.109 +
1.110 +<P>If you run the ssltap on a different machine that the ssl server you're
1.111 +trying to connect to, the browser will complain that the host name you're
1.112 +trying to connect to is different to the certificate, but it will still
1.113 +let you connect, after showing you a dialog.
1.114 +<H3>
1.115 +Bugs</H3>
1.116 +Please contact <A HREF="mailto:ssltap-support@netscape.com">ssltap-support@netscape.com</A>
1.117 +for bug reports.
1.118 +<H3>
1.119 +History</H3>
1.120 +2.1 - First public release (March 1998)
1.121 +<BR>
1.122 +<H3>
1.123 +Other</H3>
1.124 +For reference, here is a table of some well-known port numbers:
1.125 +<BR>
1.126 +<TABLE BORDER=2 >
1.127 +<TR>
1.128 +<TD>HTTP</TD>
1.129 +
1.130 +<TD>80</TD>
1.131 +</TR>
1.132 +
1.133 +<TR>
1.134 +<TD>SMTP</TD>
1.135 +
1.136 +<TD>25</TD>
1.137 +</TR>
1.138 +
1.139 +<TR>
1.140 +<TD>HTTPS</TD>
1.141 +
1.142 +<TD>443</TD>
1.143 +</TR>
1.144 +
1.145 +<TR>
1.146 +<TD>FTP</TD>
1.147 +
1.148 +<TD>21</TD>
1.149 +</TR>
1.150 +
1.151 +<TR>
1.152 +<TD>IMAPS</TD>
1.153 +
1.154 +<TD>993</TD>
1.155 +</TR>
1.156 +
1.157 +<TR>
1.158 +<TD>NNTP</TD>
1.159 +
1.160 +<TD>119</TD>
1.161 +</TR>
1.162 +
1.163 +<TR>
1.164 +<TD>NNTPS</TD>
1.165 +
1.166 +<TD>563</TD>
1.167 +</TR>
1.168 +</TABLE>
1.169 +
1.170 +
1.171 +<P>
1.172 +</BODY>
1.173 +</HTML>
