security/nss/doc/html/ssltap.html@b8a032363ba2
security/nss/doc/html/ssltap.html
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
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">ssltap</code> [-fhlsvx] [-p port] [hostname:port]</p></div></div><div class="refsection"><a name="idm233258230400"></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">-f </span></dt><dd><p>
3 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.
4 </p></dd><dt><span class="term">-h </span></dt><dd><p>
5 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.
6 </p></dd><dt><span class="term">-l prefix</span></dt><dd><p>
7 Turn on looping; that is, continue to accept connections rather than stopping after the first connection is complete.
8 </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>
9 * HTTP 80
10 </p><p>
11 * HTTPS 443
12 </p><p>
13 * SMTP 25
14 </p><p>
15 * FTP 21
16 </p><p>
17 * IMAP 143
18 </p><p>
19 * IMAPS 993 (IMAP over SSL)
20 </p><p>
21 * NNTP 119
22 </p><p>
23 * NNTPS 563 (NNTP over SSL)
24 </p></dd><dt><span class="term">-s </span></dt><dd><p>
25 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.
26 </p><p>
27 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.
28 </p><p>
29 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.
30 </p></dd><dt><span class="term">-v </span></dt><dd><p>Print a version string for the tool.</p></dd><dt><span class="term">-x </span></dt><dd><p>Turn on extra SSL hex dumps.</p></dd></dl></div></div><div class="refsection"><a name="basic-usage"></a><h2>Usage and Examples</h2><p>
31 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:
32 </p><pre class="programlisting">$ ssltap www.netscape.com</pre><p>
33 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:
34 "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
35 continue to accept connections, switch on looping mode with the -l option. The following examples show the output from commonly used combinations of options.
36 </p><p>Example 1 </p><pre class="programlisting">$ ssltap.exe -sx -p 444 interzone.mcom.com:443 > sx.txt</pre><p>Output </p><pre class="programlisting">
37 Connected to interzone.mcom.com:443
38 -->; [
39 alloclen = 66 bytes
40 [ssl2] ClientHelloV2 {
41 version = {0x03, 0x00}
42 cipher-specs-length = 39 (0x27)
43 sid-length = 0 (0x00)
44 challenge-length = 16 (0x10)
45 cipher-suites = {
47 (0x010080) SSL2/RSA/RC4-128/MD5
48 (0x020080) SSL2/RSA/RC4-40/MD5
49 (0x030080) SSL2/RSA/RC2CBC128/MD5
50 (0x040080) SSL2/RSA/RC2CBC40/MD5
51 (0x060040) SSL2/RSA/DES64CBC/MD5
52 (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5
53 (0x000004) SSL3/RSA/RC4-128/MD5
54 (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA
55 (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA
56 (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA
57 (0x000009) SSL3/RSA/DES64CBC/SHA
58 (0x000003) SSL3/RSA/RC4-40/MD5
59 (0x000006) SSL3/RSA/RC2CBC40/MD5
60 }
61 session-id = { }
62 challenge = { 0xec5d 0x8edb 0x37c9 0xb5c9 0x7b70 0x8fe9 0xd1d3
64 0x2592 }
65 }
66 ]
67 <-- [
68 SSLRecord {
69 0: 16 03 00 03 e5 |.....
70 type = 22 (handshake)
71 version = { 3,0 }
72 length = 997 (0x3e5)
73 handshake {
74 0: 02 00 00 46 |...F
75 type = 2 (server_hello)
76 length = 70 (0x000046)
77 ServerHello {
78 server_version = {3, 0}
79 random = {...}
80 0: 77 8c 6e 26 6c 0c ec c0 d9 58 4f 47 d3 2d 01 45 |
81 wn&l.ì..XOG.-.E
82 10: 5c 17 75 43 a7 4c 88 c7 88 64 3c 50 41 48 4f 7f |
84 \.uC§L.Ç.d<PAHO.
85 session ID = {
86 length = 32
88 contents = {..}
89 0: 14 11 07 a8 2a 31 91 29 11 94 40 37 57 10 a7 32 | ...¨*1.)..@7W.§2
90 10: 56 6f 52 62 fe 3d b3 65 b1 e4 13 0f 52 a3 c8 f6 | VoRbþ=³e±...R£È.
91 }
92 cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5
93 }
94 0: 0b 00 02 c5 |...Å
95 type = 11 (certificate)
96 length = 709 (0x0002c5)
97 CertificateChain {
98 chainlength = 706 (0x02c2)
99 Certificate {
100 size = 703 (0x02bf)
101 data = { saved in file 'cert.001' }
102 }
103 }
104 0: 0c 00 00 ca |....
105 type = 12 (server_key_exchange)
106 length = 202 (0x0000ca)
107 0: 0e 00 00 00 |....
108 type = 14 (server_hello_done)
109 length = 0 (0x000000)
110 }
111 }
112 ]
113 --> [
114 SSLRecord {
115 0: 16 03 00 00 44 |....D
116 type = 22 (handshake)
117 version = { 3,0 }
118 length = 68 (0x44)
119 handshake {
120 0: 10 00 00 40 |...@
121 type = 16 (client_key_exchange)
122 length = 64 (0x000040)
123 ClientKeyExchange {
124 message = {...}
125 }
126 }
127 }
128 ]
129 --> [
130 SSLRecord {
131 0: 14 03 00 00 01 |.....
132 type = 20 (change_cipher_spec)
133 version = { 3,0 }
134 length = 1 (0x1)
135 0: 01 |.
136 }
137 SSLRecord {
138 0: 16 03 00 00 38 |....8
139 type = 22 (handshake)
140 version = { 3,0 }
141 length = 56 (0x38)
142 < encrypted >
144 }
145 ]
146 <-- [
147 SSLRecord {
148 0: 14 03 00 00 01 |.....
149 type = 20 (change_cipher_spec)
150 version = { 3,0 }
151 length = 1 (0x1)
152 0: 01 |.
153 }
154 ]
155 <-- [
156 SSLRecord {
157 0: 16 03 00 00 38 |....8
158 type = 22 (handshake)
159 version = { 3,0 }
160 length = 56 (0x38)
161 < encrypted >
163 }
164 ]
165 --> [
166 SSLRecord {
167 0: 17 03 00 01 1f |.....
168 type = 23 (application_data)
169 version = { 3,0 }
170 length = 287 (0x11f)
171 < encrypted >
172 }
173 ]
174 <-- [
175 SSLRecord {
176 0: 17 03 00 00 a0 |....
177 type = 23 (application_data)
178 version = { 3,0 }
179 length = 160 (0xa0)
180 < encrypted >
182 }
183 ]
184 <-- [
185 SSLRecord {
186 0: 17 03 00 00 df |....ß
187 type = 23 (application_data)
188 version = { 3,0 }
189 length = 223 (0xdf)
190 < encrypted >
192 }
193 SSLRecord {
194 0: 15 03 00 00 12 |.....
195 type = 21 (alert)
196 version = { 3,0 }
197 length = 18 (0x12)
198 < encrypted >
199 }
200 ]
201 Server socket closed.
202 </pre><p>Example 2</p><p>
203 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.
204 </p><pre class="programlisting">$ ssltap -s -p 444 interzone.mcom.com:443 > s.txt</pre><p>Output </p><pre class="programlisting">
205 Connected to interzone.mcom.com:443
206 --> [
207 alloclen = 63 bytes
208 [ssl2] ClientHelloV2 {
209 version = {0x03, 0x00}
210 cipher-specs-length = 36 (0x24)
211 sid-length = 0 (0x00)
212 challenge-length = 16 (0x10)
213 cipher-suites = {
214 (0x010080) SSL2/RSA/RC4-128/MD5
215 (0x020080) SSL2/RSA/RC4-40/MD5
216 (0x030080) SSL2/RSA/RC2CBC128/MD5
217 (0x060040) SSL2/RSA/DES64CBC/MD5
218 (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5
219 (0x000004) SSL3/RSA/RC4-128/MD5
220 (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA
221 (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA
222 (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA
223 (0x000009) SSL3/RSA/DES64CBC/SHA
224 (0x000003) SSL3/RSA/RC4-40/MD5
225 }
226 session-id = { }
227 challenge = { 0x713c 0x9338 0x30e1 0xf8d6 0xb934 0x7351 0x200c
228 0x3fd0 }
229 ]
230 >-- [
231 SSLRecord {
232 type = 22 (handshake)
233 version = { 3,0 }
234 length = 997 (0x3e5)
235 handshake {
236 type = 2 (server_hello)
237 length = 70 (0x000046)
238 ServerHello {
239 server_version = {3, 0}
240 random = {...}
241 session ID = {
242 length = 32
243 contents = {..}
244 }
245 cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5
246 }
247 type = 11 (certificate)
248 length = 709 (0x0002c5)
249 CertificateChain {
250 chainlength = 706 (0x02c2)
251 Certificate {
252 size = 703 (0x02bf)
253 data = { saved in file 'cert.001' }
254 }
255 }
256 type = 12 (server_key_exchange)
257 length = 202 (0x0000ca)
258 type = 14 (server_hello_done)
259 length = 0 (0x000000)
260 }
261 }
262 ]
263 --> [
264 SSLRecord {
265 type = 22 (handshake)
266 version = { 3,0 }
267 length = 68 (0x44)
268 handshake {
269 type = 16 (client_key_exchange)
270 length = 64 (0x000040)
271 ClientKeyExchange {
272 message = {...}
273 }
274 }
275 }
276 ]
277 --> [
278 SSLRecord {
279 type = 20 (change_cipher_spec)
280 version = { 3,0 }
281 length = 1 (0x1)
282 }
283 SSLRecord {
284 type = 22 (handshake)
285 version = { 3,0 }
286 length = 56 (0x38)
287 > encrypted >
288 }
289 ]
290 >-- [
291 SSLRecord {
292 type = 20 (change_cipher_spec)
293 version = { 3,0 }
294 length = 1 (0x1)
295 }
296 ]
297 >-- [
298 SSLRecord {
299 type = 22 (handshake)
300 version = { 3,0 }
301 length = 56 (0x38)
302 > encrypted >
303 }
304 ]
305 --> [
306 SSLRecord {
307 type = 23 (application_data)
308 version = { 3,0 }
309 length = 287 (0x11f)
310 > encrypted >
311 }
312 ]
313 [
314 SSLRecord {
315 type = 23 (application_data)
316 version = { 3,0 }
317 length = 160 (0xa0)
318 > encrypted >
319 }
320 ]
321 >-- [
322 SSLRecord {
323 type = 23 (application_data)
324 version = { 3,0 }
325 length = 223 (0xdf)
326 > encrypted >
327 }
328 SSLRecord {
329 type = 21 (alert)
330 version = { 3,0 }
331 length = 18 (0x12)
332 > encrypted >
333 }
334 ]
335 Server socket closed.
336 </pre><p>Example 3</p><p>
337 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.
338 </p><pre class="programlisting">$ ssltap -h -p 444 interzone.mcom.com:443 > h.txt</pre><p>Output </p><pre class="programlisting">
339 Connected to interzone.mcom.com:443
340 --> [
341 0: 80 40 01 03 00 00 27 00 00 00 10 01 00 80 02 00 | .@....'.........
342 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 | .........@......
343 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 00 | ........á.......
344 30: 00 06 9b fe 5b 56 96 49 1f 9f ca dd d5 ba b9 52 | ..þ[V.I.\xd9 ...º¹R
345 40: 6f 2d |o-
346 ]
347 <-- [
348 0: 16 03 00 03 e5 02 00 00 46 03 00 7f e5 0d 1b 1d | ........F.......
349 10: 68 7f 3a 79 60 d5 17 3c 1d 9c 96 b3 88 d2 69 3b | h.:y`..<..³.Òi;
350 20: 78 e2 4b 8b a6 52 12 4b 46 e8 c2 20 14 11 89 05 | x.K.¦R.KFè. ...
351 30: 4d 52 91 fd 93 e0 51 48 91 90 08 96 c1 b6 76 77 | MR.ý..QH.....¶vw
352 40: 2a f4 00 08 a1 06 61 a2 64 1f 2e 9b 00 03 00 0b | *ô..¡.a¢d......
353 50: 00 02 c5 00 02 c2 00 02 bf 30 82 02 bb 30 82 02 | ..Å......0...0..
354 60: 24 a0 03 02 01 02 02 02 01 36 30 0d 06 09 2a 86 | $ .......60...*.
355 70: 48 86 f7 0d 01 01 04 05 00 30 77 31 0b 30 09 06 | H.÷......0w1.0..
356 80: 03 55 04 06 13 02 55 53 31 2c 30 2a 06 03 55 04 | .U....US1,0*..U.
357 90: 0a 13 23 4e 65 74 73 63 61 70 65 20 43 6f 6d 6d | ..#Netscape Comm
358 a0: 75 6e 69 63 61 74 69 6f 6e 73 20 43 6f 72 70 6f | unications Corpo
359 b0: 72 61 74 69 6f 6e 31 11 30 0f 06 03 55 04 0b 13 | ration1.0...U...
360 c0: 08 48 61 72 64 63 6f 72 65 31 27 30 25 06 03 55 | .Hardcore1'0%..U
361 d0: 04 03 13 1e 48 61 72 64 63 6f 72 65 20 43 65 72 | ....Hardcore Cer
362 e0: 74 69 66 69 63 61 74 65 20 53 65 72 76 65 72 20 | tificate Server
363 f0: 49 49 30 1e 17 0d 39 38 30 35 31 36 30 31 30 33 | II0...9805160103
364 <additional data lines>
365 ]
366 <additional records in same format>
367 Server socket closed.
368 </pre><p>Example 4</p><p>
369 In this example, the -s option turns on SSL parsing, and the -h option turns on hex/ASCII format.
370 Both formats are shown for each record. The output is routed to a text file.
371 </p><pre class="programlisting">$ ssltap -hs -p 444 interzone.mcom.com:443 > hs.txt</pre><p>Output </p><pre class="programlisting">
372 Connected to interzone.mcom.com:443
373 --> [
374 0: 80 3d 01 03 00 00 24 00 00 00 10 01 00 80 02 00 | .=....$.........
375 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 | .........@......
376 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 03 | ........á.......
377 30: 55 e6 e4 99 79 c7 d7 2c 86 78 96 5d b5 cf e9 |U..yÇ\xb0 ,.x.]µÏé
378 alloclen = 63 bytes
379 [ssl2] ClientHelloV2 {
380 version = {0x03, 0x00}
381 cipher-specs-length = 36 (0x24)
382 sid-length = 0 (0x00)
383 challenge-length = 16 (0x10)
384 cipher-suites = {
385 (0x010080) SSL2/RSA/RC4-128/MD5
386 (0x020080) SSL2/RSA/RC4-40/MD5
387 (0x030080) SSL2/RSA/RC2CBC128/MD5
388 (0x040080) SSL2/RSA/RC2CBC40/MD5
389 (0x060040) SSL2/RSA/DES64CBC/MD5
390 (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5
391 (0x000004) SSL3/RSA/RC4-128/MD5
392 (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA
393 (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA
394 (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA
395 (0x000009) SSL3/RSA/DES64CBC/SHA
396 (0x000003) SSL3/RSA/RC4-40/MD5
397 }
398 session-id = { }
399 challenge = { 0x0355 0xe6e4 0x9979 0xc7d7 0x2c86 0x7896 0x5db
401 0xcfe9 }
402 }
403 ]
404 <additional records in same formats>
405 Server socket closed.
406 </pre></div><div class="refsection"><a name="usage-tips"></a><h2>Usage Tips</h2><p>
407 When SSL restarts a previous session, it makes use of cached information to do a partial handshake.
408 If you wish to capture a full SSL handshake, restart the browser to clear the session id cache.
409 </p><p>
410 If you run the tool on a machine other than the SSL server to which you are trying to connect,
411 the browser will complain that the host name you are trying to connect to is different from the certificate.
412 If you are using the default BadCert callback, you can still connect through a dialog. If you are not using
413 the default BadCert callback, the one you supply must allow for this possibility.
414 </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>
415 Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey <dlackey@redhat.com>.
416 </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/.
417 </p></div></div><div class="navfooter"><hr></div></body></html>
