| blob | 32b9e2f51d645137ef8ee1e4194adfaf9e1816f3 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY date SYSTEM "date.xml">
5 <!ENTITY version SYSTEM "version.xml">
6 ]>
8 <refentry id="ssltap">
10 <refentryinfo>
11 <date>&date;</date>
12 <title>NSS Security Tools</title>
13 <productname>nss-tools</productname>
14 <productnumber>&version;</productnumber>
15 </refentryinfo>
17 <refmeta>
18 <refentrytitle>SSLTAP</refentrytitle>
19 <manvolnum>1</manvolnum>
20 </refmeta>
22 <refnamediv>
23 <refname>ssltap</refname>
24 <refpurpose>Tap into SSL connections and display the data going by </refpurpose>
25 </refnamediv>
27 <refsynopsisdiv>
28 <cmdsynopsis>
29 <command>ssltap</command>
30 <arg choice="opt">-fhlsvx</arg>
31 <arg choice="opt">-p port</arg>
32 <arg choice="opt">hostname:port</arg>
33 </cmdsynopsis>
34 </refsynopsisdiv>
36 <refsection>
37 <title>STATUS</title>
38 <para>This documentation is still work in progress. Please contribute to the initial review in <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=836477">Mozilla NSS bug 836477</ulink>
39 </para>
40 </refsection>
42 <refsection id="description">
43 <title>Description</title>
44 <para>The SSL Debugging Tool <command>ssltap</command> 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</para>
45 </refsection>
47 <refsection id="options">
48 <title>Options</title>
49 <variablelist>
50 <varlistentry>
51 <term>-f </term>
52 <listitem><para>
53 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.
54 </para></listitem>
55 </varlistentry>
56 <varlistentry>
57 <term>-h </term>
58 <listitem><para>
59 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.
60 </para></listitem>
61 </varlistentry>
62 <varlistentry>
63 <term>-l prefix</term>
64 <listitem>
65 <para>
66 Turn on looping; that is, continue to accept connections rather than stopping after the first connection is complete.
67 </para>
68 </listitem>
69 </varlistentry>
70 <varlistentry>
71 <term>-p port</term>
72 <listitem>
73 <para>Change the default rendezvous port (1924) to another port.</para>
74 <para>The following are well-known port numbers:</para>
75 <para>
76 * HTTP 80
77 </para>
78 <para>
79 * HTTPS 443
80 </para>
81 <para>
82 * SMTP 25
83 </para>
84 <para>
85 * FTP 21
86 </para>
87 <para>
88 * IMAP 143
89 </para>
90 <para>
91 * IMAPS 993 (IMAP over SSL)
92 </para>
93 <para>
94 * NNTP 119
95 </para>
96 <para>
97 * NNTPS 563 (NNTP over SSL)
98 </para>
99 </listitem>
100 </varlistentry>
101 <varlistentry>
102 <term>-s </term>
103 <listitem>
104 <para>
105 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.
106 </para>
107 <para>
108 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.
109 </para>
110 <para>
111 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.
112 </para>
113 </listitem>
114 </varlistentry>
115 <varlistentry>
116 <term>-v </term>
117 <listitem><para>Print a version string for the tool.</para></listitem>
118 </varlistentry>
119 <varlistentry>
120 <term>-x </term>
121 <listitem><para>Turn on extra SSL hex dumps.</para></listitem>
122 </varlistentry>
123 </variablelist>
124 </refsection>
126 <refsection id="basic-usage">
127 <title>Usage and Examples</title>
128 <para>
129 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:
130 </para>
131 <programlisting>$ ssltap www.netscape.com</programlisting>
132 <para>
133 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: --> [ data ] Data sent from the server to the client is surrounded by the following symbols:
134 "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
135 continue to accept connections, switch on looping mode with the -l option. The following examples show the output from commonly used combinations of options.
136 </para>
138 <para>Example 1 </para>
139 <programlisting>$ ssltap.exe -sx -p 444 interzone.mcom.com:443 > sx.txt</programlisting>
140 <para>Output </para>
141 <programlisting>
142 Connected to interzone.mcom.com:443
143 -->; [
144 alloclen = 66 bytes
145 [ssl2] ClientHelloV2 {
146 version = {0x03, 0x00}
147 cipher-specs-length = 39 (0x27)
148 sid-length = 0 (0x00)
149 challenge-length = 16 (0x10)
150 cipher-suites = {
152 (0x010080) SSL2/RSA/RC4-128/MD5
153 (0x020080) SSL2/RSA/RC4-40/MD5
154 (0x030080) SSL2/RSA/RC2CBC128/MD5
155 (0x040080) SSL2/RSA/RC2CBC40/MD5
156 (0x060040) SSL2/RSA/DES64CBC/MD5
157 (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5
158 (0x000004) SSL3/RSA/RC4-128/MD5
159 (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA
160 (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA
161 (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA
162 (0x000009) SSL3/RSA/DES64CBC/SHA
163 (0x000003) SSL3/RSA/RC4-40/MD5
164 (0x000006) SSL3/RSA/RC2CBC40/MD5
165 }
166 session-id = { }
167 challenge = { 0xec5d 0x8edb 0x37c9 0xb5c9 0x7b70 0x8fe9 0xd1d3
169 0x2592 }
170 }
171 ]
172 <-- [
173 SSLRecord {
174 0: 16 03 00 03 e5 |.....
175 type = 22 (handshake)
176 version = { 3,0 }
177 length = 997 (0x3e5)
178 handshake {
179 0: 02 00 00 46 |...F
180 type = 2 (server_hello)
181 length = 70 (0x000046)
182 ServerHello {
183 server_version = {3, 0}
184 random = {...}
185 0: 77 8c 6e 26 6c 0c ec c0 d9 58 4f 47 d3 2d 01 45 |
186 wn&l.ì..XOG.-.E
187 10: 5c 17 75 43 a7 4c 88 c7 88 64 3c 50 41 48 4f 7f |
189 \.uC§L.Ç.d<PAHO.
190 session ID = {
191 length = 32
193 contents = {..}
194 0: 14 11 07 a8 2a 31 91 29 11 94 40 37 57 10 a7 32 | ...¨*1.)..@7W.§2
195 10: 56 6f 52 62 fe 3d b3 65 b1 e4 13 0f 52 a3 c8 f6 | VoRbþ=³e±...R£È.
196 }
197 cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5
198 }
199 0: 0b 00 02 c5 |...Å
200 type = 11 (certificate)
201 length = 709 (0x0002c5)
202 CertificateChain {
203 chainlength = 706 (0x02c2)
204 Certificate {
205 size = 703 (0x02bf)
206 data = { saved in file 'cert.001' }
207 }
208 }
209 0: 0c 00 00 ca |....
210 type = 12 (server_key_exchange)
211 length = 202 (0x0000ca)
212 0: 0e 00 00 00 |....
213 type = 14 (server_hello_done)
214 length = 0 (0x000000)
215 }
216 }
217 ]
218 --> [
219 SSLRecord {
220 0: 16 03 00 00 44 |....D
221 type = 22 (handshake)
222 version = { 3,0 }
223 length = 68 (0x44)
224 handshake {
225 0: 10 00 00 40 |...@
226 type = 16 (client_key_exchange)
227 length = 64 (0x000040)
228 ClientKeyExchange {
229 message = {...}
230 }
231 }
232 }
233 ]
234 --> [
235 SSLRecord {
236 0: 14 03 00 00 01 |.....
237 type = 20 (change_cipher_spec)
238 version = { 3,0 }
239 length = 1 (0x1)
240 0: 01 |.
241 }
242 SSLRecord {
243 0: 16 03 00 00 38 |....8
244 type = 22 (handshake)
245 version = { 3,0 }
246 length = 56 (0x38)
247 < encrypted >
249 }
250 ]
251 <-- [
252 SSLRecord {
253 0: 14 03 00 00 01 |.....
254 type = 20 (change_cipher_spec)
255 version = { 3,0 }
256 length = 1 (0x1)
257 0: 01 |.
258 }
259 ]
260 <-- [
261 SSLRecord {
262 0: 16 03 00 00 38 |....8
263 type = 22 (handshake)
264 version = { 3,0 }
265 length = 56 (0x38)
266 < encrypted >
268 }
269 ]
270 --> [
271 SSLRecord {
272 0: 17 03 00 01 1f |.....
273 type = 23 (application_data)
274 version = { 3,0 }
275 length = 287 (0x11f)
276 < encrypted >
277 }
278 ]
279 <-- [
280 SSLRecord {
281 0: 17 03 00 00 a0 |....
282 type = 23 (application_data)
283 version = { 3,0 }
284 length = 160 (0xa0)
285 < encrypted >
287 }
288 ]
289 <-- [
290 SSLRecord {
291 0: 17 03 00 00 df |....ß
292 type = 23 (application_data)
293 version = { 3,0 }
294 length = 223 (0xdf)
295 < encrypted >
297 }
298 SSLRecord {
299 0: 15 03 00 00 12 |.....
300 type = 21 (alert)
301 version = { 3,0 }
302 length = 18 (0x12)
303 < encrypted >
304 }
305 ]
306 Server socket closed.
307 </programlisting>
310 <para>Example 2</para>
311 <para>
312 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.
313 </para>
314 <programlisting>$ ssltap -s -p 444 interzone.mcom.com:443 > s.txt</programlisting>
315 <para>Output </para>
316 <programlisting>
317 Connected to interzone.mcom.com:443
318 --> [
319 alloclen = 63 bytes
320 [ssl2] ClientHelloV2 {
321 version = {0x03, 0x00}
322 cipher-specs-length = 36 (0x24)
323 sid-length = 0 (0x00)
324 challenge-length = 16 (0x10)
325 cipher-suites = {
326 (0x010080) SSL2/RSA/RC4-128/MD5
327 (0x020080) SSL2/RSA/RC4-40/MD5
328 (0x030080) SSL2/RSA/RC2CBC128/MD5
329 (0x060040) SSL2/RSA/DES64CBC/MD5
330 (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5
331 (0x000004) SSL3/RSA/RC4-128/MD5
332 (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA
333 (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA
334 (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA
335 (0x000009) SSL3/RSA/DES64CBC/SHA
336 (0x000003) SSL3/RSA/RC4-40/MD5
337 }
338 session-id = { }
339 challenge = { 0x713c 0x9338 0x30e1 0xf8d6 0xb934 0x7351 0x200c
340 0x3fd0 }
341 ]
342 >-- [
343 SSLRecord {
344 type = 22 (handshake)
345 version = { 3,0 }
346 length = 997 (0x3e5)
347 handshake {
348 type = 2 (server_hello)
349 length = 70 (0x000046)
350 ServerHello {
351 server_version = {3, 0}
352 random = {...}
353 session ID = {
354 length = 32
355 contents = {..}
356 }
357 cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5
358 }
359 type = 11 (certificate)
360 length = 709 (0x0002c5)
361 CertificateChain {
362 chainlength = 706 (0x02c2)
363 Certificate {
364 size = 703 (0x02bf)
365 data = { saved in file 'cert.001' }
366 }
367 }
368 type = 12 (server_key_exchange)
369 length = 202 (0x0000ca)
370 type = 14 (server_hello_done)
371 length = 0 (0x000000)
372 }
373 }
374 ]
375 --> [
376 SSLRecord {
377 type = 22 (handshake)
378 version = { 3,0 }
379 length = 68 (0x44)
380 handshake {
381 type = 16 (client_key_exchange)
382 length = 64 (0x000040)
383 ClientKeyExchange {
384 message = {...}
385 }
386 }
387 }
388 ]
389 --> [
390 SSLRecord {
391 type = 20 (change_cipher_spec)
392 version = { 3,0 }
393 length = 1 (0x1)
394 }
395 SSLRecord {
396 type = 22 (handshake)
397 version = { 3,0 }
398 length = 56 (0x38)
399 > encrypted >
400 }
401 ]
402 >-- [
403 SSLRecord {
404 type = 20 (change_cipher_spec)
405 version = { 3,0 }
406 length = 1 (0x1)
407 }
408 ]
409 >-- [
410 SSLRecord {
411 type = 22 (handshake)
412 version = { 3,0 }
413 length = 56 (0x38)
414 > encrypted >
415 }
416 ]
417 --> [
418 SSLRecord {
419 type = 23 (application_data)
420 version = { 3,0 }
421 length = 287 (0x11f)
422 > encrypted >
423 }
424 ]
425 [
426 SSLRecord {
427 type = 23 (application_data)
428 version = { 3,0 }
429 length = 160 (0xa0)
430 > encrypted >
431 }
432 ]
433 >-- [
434 SSLRecord {
435 type = 23 (application_data)
436 version = { 3,0 }
437 length = 223 (0xdf)
438 > encrypted >
439 }
440 SSLRecord {
441 type = 21 (alert)
442 version = { 3,0 }
443 length = 18 (0x12)
444 > encrypted >
445 }
446 ]
447 Server socket closed.
448 </programlisting>
450 <para>Example 3</para>
451 <para>
452 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.
453 </para>
454 <programlisting>$ ssltap -h -p 444 interzone.mcom.com:443 > h.txt</programlisting>
455 <para>Output </para>
456 <programlisting>
457 Connected to interzone.mcom.com:443
458 --> [
459 0: 80 40 01 03 00 00 27 00 00 00 10 01 00 80 02 00 | .@....'.........
460 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 | .........@......
461 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 00 | ........á.......
462 30: 00 06 9b fe 5b 56 96 49 1f 9f ca dd d5 ba b9 52 | ..þ[V.I.\xd9 ...º¹R
463 40: 6f 2d |o-
464 ]
465 <-- [
466 0: 16 03 00 03 e5 02 00 00 46 03 00 7f e5 0d 1b 1d | ........F.......
467 10: 68 7f 3a 79 60 d5 17 3c 1d 9c 96 b3 88 d2 69 3b | h.:y`..<..³.Òi;
468 20: 78 e2 4b 8b a6 52 12 4b 46 e8 c2 20 14 11 89 05 | x.K.¦R.KFè. ...
469 30: 4d 52 91 fd 93 e0 51 48 91 90 08 96 c1 b6 76 77 | MR.ý..QH.....¶vw
470 40: 2a f4 00 08 a1 06 61 a2 64 1f 2e 9b 00 03 00 0b | *ô..¡.a¢d......
471 50: 00 02 c5 00 02 c2 00 02 bf 30 82 02 bb 30 82 02 | ..Å......0...0..
472 60: 24 a0 03 02 01 02 02 02 01 36 30 0d 06 09 2a 86 | $ .......60...*.
473 70: 48 86 f7 0d 01 01 04 05 00 30 77 31 0b 30 09 06 | H.÷......0w1.0..
474 80: 03 55 04 06 13 02 55 53 31 2c 30 2a 06 03 55 04 | .U....US1,0*..U.
475 90: 0a 13 23 4e 65 74 73 63 61 70 65 20 43 6f 6d 6d | ..#Netscape Comm
476 a0: 75 6e 69 63 61 74 69 6f 6e 73 20 43 6f 72 70 6f | unications Corpo
477 b0: 72 61 74 69 6f 6e 31 11 30 0f 06 03 55 04 0b 13 | ration1.0...U...
478 c0: 08 48 61 72 64 63 6f 72 65 31 27 30 25 06 03 55 | .Hardcore1'0%..U
479 d0: 04 03 13 1e 48 61 72 64 63 6f 72 65 20 43 65 72 | ....Hardcore Cer
480 e0: 74 69 66 69 63 61 74 65 20 53 65 72 76 65 72 20 | tificate Server
481 f0: 49 49 30 1e 17 0d 39 38 30 35 31 36 30 31 30 33 | II0...9805160103
482 <additional data lines>
483 ]
484 <additional records in same format>
485 Server socket closed.
486 </programlisting>
488 <para>Example 4</para>
489 <para>
490 In this example, the -s option turns on SSL parsing, and the -h option turns on hex/ASCII format.
491 Both formats are shown for each record. The output is routed to a text file.
492 </para>
493 <programlisting>$ ssltap -hs -p 444 interzone.mcom.com:443 > hs.txt</programlisting>
494 <para>Output </para>
495 <programlisting>
496 Connected to interzone.mcom.com:443
497 --> [
498 0: 80 3d 01 03 00 00 24 00 00 00 10 01 00 80 02 00 | .=....$.........
499 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 | .........@......
500 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 03 | ........á.......
501 30: 55 e6 e4 99 79 c7 d7 2c 86 78 96 5d b5 cf e9 |U..yÇ\xb0 ,.x.]µÏé
502 alloclen = 63 bytes
503 [ssl2] ClientHelloV2 {
504 version = {0x03, 0x00}
505 cipher-specs-length = 36 (0x24)
506 sid-length = 0 (0x00)
507 challenge-length = 16 (0x10)
508 cipher-suites = {
509 (0x010080) SSL2/RSA/RC4-128/MD5
510 (0x020080) SSL2/RSA/RC4-40/MD5
511 (0x030080) SSL2/RSA/RC2CBC128/MD5
512 (0x040080) SSL2/RSA/RC2CBC40/MD5
513 (0x060040) SSL2/RSA/DES64CBC/MD5
514 (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5
515 (0x000004) SSL3/RSA/RC4-128/MD5
516 (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA
517 (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA
518 (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA
519 (0x000009) SSL3/RSA/DES64CBC/SHA
520 (0x000003) SSL3/RSA/RC4-40/MD5
521 }
522 session-id = { }
523 challenge = { 0x0355 0xe6e4 0x9979 0xc7d7 0x2c86 0x7896 0x5db
525 0xcfe9 }
526 }
527 ]
528 <additional records in same formats>
529 Server socket closed.
530 </programlisting>
534 </refsection>
536 <refsection id="usage-tips">
537 <title>Usage Tips</title>
538 <para>
539 When SSL restarts a previous session, it makes use of cached information to do a partial handshake.
540 If you wish to capture a full SSL handshake, restart the browser to clear the session id cache.
541 </para>
542 <para>
543 If you run the tool on a machine other than the SSL server to which you are trying to connect,
544 the browser will complain that the host name you are trying to connect to is different from the certificate.
545 If you are using the default BadCert callback, you can still connect through a dialog. If you are not using
546 the default BadCert callback, the one you supply must allow for this possibility.
547 </para>
548 </refsection>
550 <refsection id="seealso">
551 <title>See Also</title>
552 <para>The NSS Security Tools are also documented at <ulink url="http://www.mozilla.org/projects/security/pki/nss/tools">http://www.mozilla.org/projects/security/pki/nss/</ulink>.</para>
553 </refsection>
555 <!-- don't change -->
556 <refsection id="resources">
557 <title>Additional Resources</title>
558 <para>For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at <ulink url="http://www.mozilla.org/projects/security/pki/nss/">http://www.mozilla.org/projects/security/pki/nss/</ulink>. The NSS site relates directly to NSS code changes and releases.</para>
559 <para>Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto</para>
560 <para>IRC: Freenode at #dogtag-pki</para>
561 </refsection>
563 <!-- fill in your name first; keep the other names for reference -->
564 <refsection id="authors">
565 <title>Authors</title>
566 <para>The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google.</para>
567 <para>
568 Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey <dlackey@redhat.com>.
569 </para>
570 </refsection>
572 <!-- don't change -->
573 <refsection id="license">
574 <title>LICENSE</title>
575 <para>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/.
576 </para>
577 </refsection>
579 </refentry>