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