nss/doc/html/ssltap.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>SSLTAP</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="SSLTAP"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">SSLTAP</th></tr></table><hr></div><div class="refentry"><a name="ssltap"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ssltap — Tap into SSL connections and display the data going by </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">libssltap</code>  [-vhfsxl] [-p port] [hostname:port]</p></div></div><div class="refsection"><a name="idm224680842512"></a><h2>STATUS</h2><p>This documentation is still work in progress. Please contribute to the initial review in <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=836477" target="_top">Mozilla NSS bug 836477</a>
   2     </p></div><div class="refsection"><a name="description"></a><h2>Description</h2><p>The SSL Debugging Tool <span class="command"><strong>ssltap</strong></span> is an SSL-aware command-line proxy. It watches TCP connections and displays the data going by. If a connection is SSL, the data display includes interpreted SSL records and handshaking</p></div><div class="refsection"><a name="options"></a><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term">-v </span></dt><dd><p>Print a version string for the tool.</p></dd><dt><span class="term">-h </span></dt><dd><p>
   3 Turn on hex/ASCII printing. Instead of outputting raw data, the command interprets each record as a numbered line of hex values, followed by the same data as ASCII characters. The two parts are separated by a vertical bar. Nonprinting characters are replaced by dots.
   4         </p></dd><dt><span class="term">-f </span></dt><dd><p>
   5 Turn on fancy printing. Output is printed in colored HTML. Data sent from the client to the server is in blue; the server's reply is in red. When used with looping mode, the different connections are separated with horizontal lines. You can use this option to upload the output into a browser.
   6         </p></dd><dt><span class="term">-s </span></dt><dd><p>
   7 Turn on SSL parsing and decoding. The tool does not automatically detect SSL sessions. If you are intercepting an SSL connection, use this option so that the tool can detect and decode SSL structures.
   8           </p><p>
   9 If the tool detects a certificate chain, it saves the DER-encoded certificates into files in the current directory. The files are named cert.0x, where x is the sequence number of the certificate.
  10           </p><p>
  11 If the -s option is used with -h, two separate parts are printed for each record: the plain hex/ASCII output, and the parsed SSL output.
  12           </p></dd><dt><span class="term">-x  </span></dt><dd><p>
  13 Turn on hex/ASCII printing of undecoded data inside parsed SSL records. Used only with the -s option.
  14 This option uses the same output format as the -h option.
  15             </p></dd><dt><span class="term">-l  prefix</span></dt><dd><p>
  16 Turn on looping; that is, continue to accept connections rather than stopping after the first connection is complete.
  17           </p></dd><dt><span class="term">-p  port</span></dt><dd><p>Change the default rendezvous port (1924) to another port.</p><p>The following are well-known port numbers:</p><p>
  18           * HTTP   80
  19           </p><p>
  20               * HTTPS  443
  21               </p><p>
  22           * SMTP   25
  23           </p><p>
  24           * FTP    21
  25           </p><p>
  26           * IMAP   143
  27           </p><p>
  28           * IMAPS  993 (IMAP over SSL)
  29           </p><p>
  30           * NNTP   119
  31           </p><p>
  32           * NNTPS  563 (NNTP over SSL)
  33           </p></dd></dl></div></div><div class="refsection"><a name="basic-usage"></a><h2>Usage and Examples</h2><p>
  34 You can use the SSL Debugging Tool to intercept any connection information. Although you can run the tool at its most basic by issuing the ssltap command with no options other than hostname:port, the information you get in this way is not very useful. For example, assume your development machine is called intercept. The simplest way to use the debugging tool is to execute the following command from a command shell:
  35       </p><pre class="programlisting">$ ssltap www.netscape.com</pre><p>
  36 The program waits for an incoming connection on the default port 1924. In your browser window, enter the URL http://intercept:1924. The browser retrieves the requested page from the server at www.netscape.com, but the page is intercepted and passed on to the browser by the debugging tool on intercept. On its way to the browser, the data is printed to the command shell from which you issued the command. Data sent from the client to the server is surrounded by the following symbols: --&gt; [ data ] Data sent from the server to the client is surrounded by the following symbols:
  37 "left arrow"-- [ data ] The raw data stream is sent to standard output and is not interpreted in any way. This can result in peculiar effects, such as sounds, flashes, and even crashes of the command shell window. To output a basic, printable interpretation of the data, use the -h option, or, if you are looking at an SSL connection, the -s option. You will notice that the page you retrieved looks incomplete in the browser. This is because, by default, the tool closes down after the first connection is complete, so the browser is not able to load images. To make the tool
  38 continue to accept connections, switch on looping mode with the -l option. The following examples show the output from commonly used combinations of options.
  39       </p><p>Example 1 </p><pre class="programlisting">$ ssltap.exe -sx -p 444 interzone.mcom.com:443 &gt; sx.txt</pre><p>Output </p><pre class="programlisting">
  40 Connected to interzone.mcom.com:443
  41 --&gt;; [
  42 alloclen = 66 bytes
  43    [ssl2]  ClientHelloV2 {
  44             version = {0x03, 0x00}
  45             cipher-specs-length = 39 (0x27)
  46             sid-length = 0 (0x00)
  47             challenge-length = 16 (0x10)
  48             cipher-suites = {
  49
  50                 (0x010080) SSL2/RSA/RC4-128/MD5
  51                   (0x020080) SSL2/RSA/RC4-40/MD5
  52                   (0x030080) SSL2/RSA/RC2CBC128/MD5
  53                   (0x040080) SSL2/RSA/RC2CBC40/MD5
  54                   (0x060040) SSL2/RSA/DES64CBC/MD5
  55                   (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5
  56                   (0x000004) SSL3/RSA/RC4-128/MD5
  57                   (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA
  58                   (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA
  59                   (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA
  60                   (0x000009) SSL3/RSA/DES64CBC/SHA
  61                   (0x000003) SSL3/RSA/RC4-40/MD5
  62                   (0x000006) SSL3/RSA/RC2CBC40/MD5
  63                   }
  64             session-id = { }
  65             challenge = { 0xec5d 0x8edb 0x37c9 0xb5c9 0x7b70 0x8fe9 0xd1d3
  66
  67 0x2592 }
  68 }
  69 ]
  70 &lt;-- [
  71 SSLRecord {
  72    0: 16 03 00 03  e5                                   |.....
  73    type    = 22 (handshake)
  74    version = { 3,0 }
  75    length  = 997 (0x3e5)
  76    handshake {
  77    0: 02 00 00 46                                      |...F
  78       type = 2 (server_hello)
  79       length = 70 (0x000046)
  80             ServerHello {
  81             server_version = {3, 0}
  82             random = {...}
  83    0: 77 8c 6e 26  6c 0c ec c0  d9 58 4f 47  d3 2d 01 45  |
  84 wn&amp;l.ì..XOG.-.E
  85    10: 5c 17 75 43  a7 4c 88 c7  88 64 3c 50  41 48 4f 7f  |
  86
  87 \.uC§L.Ç.d&lt;PAHO.
  88                   session ID = {
  89                   length = 32
  90
  91                 contents = {..}
  92    0: 14 11 07 a8  2a 31 91 29  11 94 40 37  57 10 a7 32  | ...¨*1.)..@7W.§2
  93    10: 56 6f 52 62  fe 3d b3 65  b1 e4 13 0f  52 a3 c8 f6  | VoRbþ=³e±...R£È.
  94          }
  95                cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5
  96          }
  97    0: 0b 00 02 c5                                      |...Å
  98       type = 11 (certificate)
  99       length = 709 (0x0002c5)
 100             CertificateChain {
 101             chainlength = 706 (0x02c2)
 102                Certificate {
 103             size = 703 (0x02bf)
 104                data = { saved in file 'cert.001' }
 105             }
 106          }
 107    0: 0c 00 00 ca                                      |....
 108          type = 12 (server_key_exchange)
 109          length = 202 (0x0000ca)
 110    0: 0e 00 00 00                                      |....
 111          type = 14 (server_hello_done)
 112          length = 0 (0x000000)
 113    }
 114 }
 115 ]
 116 --&gt; [
 117 SSLRecord {
 118    0: 16 03 00 00  44                                   |....D
 119    type    = 22 (handshake)
 120    version = { 3,0 }
 121    length  = 68 (0x44)
 122    handshake {
 123    0: 10 00 00 40                                      |...@
 124    type = 16 (client_key_exchange)
 125    length = 64 (0x000040)
 126          ClientKeyExchange {
 127             message = {...}
 128          }
 129    }
 130 }
 131 ]
 132 --&gt; [
 133 SSLRecord {
 134    0: 14 03 00 00  01                                   |.....
 135    type    = 20 (change_cipher_spec)
 136    version = { 3,0 }
 137    length  = 1 (0x1)
 138    0: 01                                               |.
 139 }
 140 SSLRecord {
 141    0: 16 03 00 00  38                                   |....8
 142    type    = 22 (handshake)
 143    version = { 3,0 }
 144    length  = 56 (0x38)
 145                &lt; encrypted &gt;
 146
 147 }
 148 ]
 149 &lt;-- [
 150 SSLRecord {
 151    0: 14 03 00 00  01                                   |.....
 152    type    = 20 (change_cipher_spec)
 153    version = { 3,0 }
 154    length  = 1 (0x1)
 155    0: 01                                               |.
 156 }
 157 ]
 158 &lt;-- [
 159 SSLRecord {
 160    0: 16 03 00 00  38                                   |....8
 161    type    = 22 (handshake)
 162    version = { 3,0 }
 163    length  = 56 (0x38)
 164                   &lt; encrypted &gt;
 165
 166 }
 167 ]
 168 --&gt; [
 169 SSLRecord {
 170    0: 17 03 00 01  1f                                   |.....
 171    type    = 23 (application_data)
 172    version = { 3,0 }
 173    length  = 287 (0x11f)
 174                &lt; encrypted &gt;
 175 }
 176 ]
 177 &lt;-- [
 178 SSLRecord {
 179    0: 17 03 00 00  a0                                   |....
 180    type    = 23 (application_data)
 181    version = { 3,0 }
 182    length  = 160 (0xa0)
 183                &lt; encrypted &gt;
 184
 185 }
 186 ]
 187 &lt;-- [
 188 SSLRecord {
 189 0: 17 03 00 00  df                                   |....ß
 190    type    = 23 (application_data)
 191    version = { 3,0 }
 192    length  = 223 (0xdf)
 193                &lt; encrypted &gt;
 194
 195 }
 196 SSLRecord {
 197    0: 15 03 00 00  12                                   |.....
 198    type    = 21 (alert)
 199    version = { 3,0 }
 200    length  = 18 (0x12)
 201                &lt; encrypted &gt;
 202 }
 203 ]
 204 Server socket closed.
 205 </pre><p>Example 2</p><p>
 206 The -s option turns on SSL parsing. Because the -x option is not used in this example, undecoded values are output as raw data. The output is routed to a text file.
 207     </p><pre class="programlisting">$ ssltap -s  -p 444 interzone.mcom.com:443 &gt; s.txt</pre><p>Output </p><pre class="programlisting">
 208 Connected to interzone.mcom.com:443
 209 --&gt; [
 210 alloclen = 63 bytes
 211    [ssl2]  ClientHelloV2 {
 212             version = {0x03, 0x00}
 213             cipher-specs-length = 36 (0x24)
 214             sid-length = 0 (0x00)
 215             challenge-length = 16 (0x10)
 216             cipher-suites = {
 217                   (0x010080) SSL2/RSA/RC4-128/MD5
 218                   (0x020080) SSL2/RSA/RC4-40/MD5
 219                   (0x030080) SSL2/RSA/RC2CBC128/MD5
 220                   (0x060040) SSL2/RSA/DES64CBC/MD5
 221                   (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5
 222                   (0x000004) SSL3/RSA/RC4-128/MD5
 223                   (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA
 224                   (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA
 225                   (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA
 226                   (0x000009) SSL3/RSA/DES64CBC/SHA
 227                   (0x000003) SSL3/RSA/RC4-40/MD5
 228                   }
 229                session-id = { }
 230             challenge = { 0x713c 0x9338 0x30e1 0xf8d6 0xb934 0x7351 0x200c
 231 0x3fd0 }
 232 ]
 233 &gt;-- [
 234 SSLRecord {
 235    type    = 22 (handshake)
 236    version = { 3,0 }
 237    length  = 997 (0x3e5)
 238    handshake {
 239          type = 2 (server_hello)
 240          length = 70 (0x000046)
 241             ServerHello {
 242             server_version = {3, 0}
 243             random = {...}
 244             session ID = {
 245                length = 32
 246                contents = {..}
 247                }
 248                cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5
 249             }
 250          type = 11 (certificate)
 251          length = 709 (0x0002c5)
 252             CertificateChain {
 253                chainlength = 706 (0x02c2)
 254                Certificate {
 255                   size = 703 (0x02bf)
 256                   data = { saved in file 'cert.001' }
 257                }
 258             }
 259          type = 12 (server_key_exchange)
 260          length = 202 (0x0000ca)
 261          type = 14 (server_hello_done)
 262          length = 0 (0x000000)
 263    }
 264 }
 265 ]
 266 --&gt; [
 267 SSLRecord {
 268    type    = 22 (handshake)
 269    version = { 3,0 }
 270    length  = 68 (0x44)
 271    handshake {
 272          type = 16 (client_key_exchange)
 273          length = 64 (0x000040)
 274             ClientKeyExchange {
 275                message = {...}
 276             }
 277    }
 278 }
 279 ]
 280 --&gt; [
 281 SSLRecord {
 282    type    = 20 (change_cipher_spec)
 283    version = { 3,0 }
 284    length  = 1 (0x1)
 285 }
 286 SSLRecord {
 287    type    = 22 (handshake)
 288    version = { 3,0 }
 289    length  = 56 (0x38)
 290                &gt; encrypted &gt;
 291 }
 292 ]
 293 &gt;-- [
 294 SSLRecord {
 295    type    = 20 (change_cipher_spec)
 296    version = { 3,0 }
 297    length  = 1 (0x1)
 298 }
 299 ]
 300 &gt;-- [
 301 SSLRecord {
 302    type    = 22 (handshake)
 303    version = { 3,0 }
 304    length  = 56 (0x38)
 305                &gt; encrypted &gt;
 306 }
 307 ]
 308 --&gt; [
 309 SSLRecord {
 310    type    = 23 (application_data)
 311    version = { 3,0 }
 312    length  = 287 (0x11f)
 313                &gt; encrypted &gt;
 314 }
 315 ]
 316 [
 317 SSLRecord {
 318    type    = 23 (application_data)
 319    version = { 3,0 }
 320    length  = 160 (0xa0)
 321                &gt; encrypted &gt;
 322 }
 323 ]
 324 &gt;-- [
 325 SSLRecord {
 326    type    = 23 (application_data)
 327    version = { 3,0 }
 328    length  = 223 (0xdf)
 329                &gt; encrypted &gt;
 330 }
 331 SSLRecord {
 332    type    = 21 (alert)
 333    version = { 3,0 }
 334    length  = 18 (0x12)
 335                &gt; encrypted &gt;
 336 }
 337 ]
 338 Server socket closed.
 339 </pre><p>Example 3</p><p>
 340 In this example, the -h option turns hex/ASCII format. There is no SSL parsing or decoding. The output is routed to a text file.
 341     </p><pre class="programlisting">$ ssltap -h  -p 444 interzone.mcom.com:443 &gt; h.txt</pre><p>Output </p><pre class="programlisting">
 342 Connected to interzone.mcom.com:443
 343 --&gt; [
 344    0: 80 40 01 03  00 00 27 00  00 00 10 01  00 80 02 00  | .@....'.........
 345    10: 80 03 00 80  04 00 80 06  00 40 07 00  c0 00 00 04  | .........@......
 346    20: 00 ff e0 00  00 0a 00 ff  e1 00 00 09  00 00 03 00  | ........á.......
 347    30: 00 06 9b fe  5b 56 96 49  1f 9f ca dd  d5 ba b9 52  | ..þ[V.I.\xd9 ...º¹R
 348    40: 6f 2d                                            |o-
 349 ]
 350 &lt;-- [
 351    0: 16 03 00 03  e5 02 00 00  46 03 00 7f  e5 0d 1b 1d  | ........F.......
 352    10: 68 7f 3a 79  60 d5 17 3c  1d 9c 96 b3  88 d2 69 3b  | h.:y`..&lt;..³.Òi;
 353    20: 78 e2 4b 8b  a6 52 12 4b  46 e8 c2 20  14 11 89 05  | x.K.¦R.KFè. ...
 354    30: 4d 52 91 fd  93 e0 51 48  91 90 08 96  c1 b6 76 77  | MR.ý..QH.....¶vw
 355    40: 2a f4 00 08  a1 06 61 a2  64 1f 2e 9b  00 03 00 0b  | *ô..¡.a¢d......
 356    50: 00 02 c5 00  02 c2 00 02  bf 30 82 02  bb 30 82 02  | ..Å......0...0..
 357    60: 24 a0 03 02  01 02 02 02  01 36 30 0d  06 09 2a 86  | $ .......60...*.
 358    70: 48 86 f7 0d  01 01 04 05  00 30 77 31  0b 30 09 06  | H.÷......0w1.0..
 359    80: 03 55 04 06  13 02 55 53  31 2c 30 2a  06 03 55 04  | .U....US1,0*..U.
 360    90: 0a 13 23 4e  65 74 73 63  61 70 65 20  43 6f 6d 6d  | ..#Netscape Comm
 361    a0: 75 6e 69 63  61 74 69 6f  6e 73 20 43  6f 72 70 6f  | unications Corpo
 362    b0: 72 61 74 69  6f 6e 31 11  30 0f 06 03  55 04 0b 13  | ration1.0...U...
 363    c0: 08 48 61 72  64 63 6f 72  65 31 27 30  25 06 03 55  | .Hardcore1'0%..U
 364    d0: 04 03 13 1e  48 61 72 64  63 6f 72 65  20 43 65 72  | ....Hardcore Cer
 365    e0: 74 69 66 69  63 61 74 65  20 53 65 72  76 65 72 20  | tificate Server
 366    f0: 49 49 30 1e  17 0d 39 38  30 35 31 36  30 31 30 33  | II0...9805160103
 367 &lt;additional data lines&gt;
 368 ]
 369 &lt;additional records in same format&gt;
 370 Server socket closed.
 371 </pre><p>Example 4</p><p>
 372 In this example, the -s option turns on SSL parsing, and the -h option turns on hex/ASCII format.
 373 Both formats are shown for each record. The output is routed to a text file.
 374       </p><pre class="programlisting">$ ssltap -hs -p 444 interzone.mcom.com:443 &gt; hs.txt</pre><p>Output </p><pre class="programlisting">
 375 Connected to interzone.mcom.com:443
 376 --&gt; [
 377    0: 80 3d 01 03  00 00 24 00  00 00 10 01  00 80 02 00  | .=....$.........
 378    10: 80 03 00 80  04 00 80 06  00 40 07 00  c0 00 00 04  | .........@......
 379    20: 00 ff e0 00  00 0a 00 ff  e1 00 00 09  00 00 03 03  | ........á.......
 380    30: 55 e6 e4 99  79 c7 d7 2c  86 78 96 5d  b5 cf e9     |U..yÇ\xb0 ,.x.]µÏé
 381 alloclen = 63 bytes
 382    [ssl2]  ClientHelloV2 {
 383             version = {0x03, 0x00}
 384             cipher-specs-length = 36 (0x24)
 385             sid-length = 0 (0x00)
 386             challenge-length = 16 (0x10)
 387             cipher-suites = {
 388                   (0x010080) SSL2/RSA/RC4-128/MD5
 389                   (0x020080) SSL2/RSA/RC4-40/MD5
 390                   (0x030080) SSL2/RSA/RC2CBC128/MD5
 391                   (0x040080) SSL2/RSA/RC2CBC40/MD5
 392                   (0x060040) SSL2/RSA/DES64CBC/MD5
 393                   (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5
 394                   (0x000004) SSL3/RSA/RC4-128/MD5
 395                   (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA
 396                   (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA
 397                   (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA
 398                   (0x000009) SSL3/RSA/DES64CBC/SHA
 399                   (0x000003) SSL3/RSA/RC4-40/MD5
 400                   }
 401             session-id = { }
 402             challenge = { 0x0355 0xe6e4 0x9979 0xc7d7 0x2c86 0x7896 0x5db
 403
 404 0xcfe9 }
 405 }
 406 ]
 407 &lt;additional records in same formats&gt;
 408 Server socket closed.
 409 </pre></div><div class="refsection"><a name="usage-tips"></a><h2>Usage Tips</h2><p>
 410 When SSL restarts a previous session, it makes use of cached information to do a partial handshake.
 411 If you wish to capture a full SSL handshake, restart the browser to clear the session id cache.
 412       </p><p>
 413 If you run the tool on a machine other than the SSL server to which you are trying to connect,
 414 the browser will complain that the host name you are trying to connect to is different from the certificate.
 415 If you are using the default BadCert callback, you can still connect through a dialog. If you are not using
 416 the default BadCert callback, the one you supply must allow for this possibility.
 417       </p></div><div class="refsection"><a name="seealso"></a><h2>See Also</h2><p>The NSS Security Tools are also documented at <a class="ulink" href="http://www.mozilla.org/projects/security/pki/nss/tools" target="_top">http://www.mozilla.org/projects/security/pki/nss/</a>.</p></div><div class="refsection"><a name="resources"></a><h2>Additional Resources</h2><p>For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at <a class="ulink" href="http://www.mozilla.org/projects/security/pki/nss/" target="_top">http://www.mozilla.org/projects/security/pki/nss/</a>. The NSS site relates directly to NSS code changes and releases.</p><p>Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto</p><p>IRC: Freenode at #dogtag-pki</p></div><div class="refsection"><a name="authors"></a><h2>Authors</h2><p>The NSS tools were written and maintained by developers with Netscape, Red Hat,  Sun, Oracle, Mozilla, and Google.</p><p>
 418         Authors: Elio Maldonado &lt;emaldona@redhat.com&gt;, Deon Lackey &lt;dlackey@redhat.com&gt;.
 419     </p></div><div class="refsection"><a name="license"></a><h2>LICENSE</h2><p>Licensed under the Mozilla Public License, v. 2.0.  If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
 420     </p></div></div><div class="navfooter"><hr></div></body></html>