1SSLTAP(1)                     NSS Security Tools                     SSLTAP(1)
2
3
4

NAME

6       ssltap - Tap into SSL connections and display the data going by
7

SYNOPSIS

9       ssltap [-fhlsvx] [-p port] [hostname:port]
10

STATUS

12       This documentation is still work in progress. Please contribute to the
13       initial review in Mozilla NSS bug 836477[1]
14

DESCRIPTION

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

OPTIONS

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
29       -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
36       -l prefix
37           Turn on looping; that is, continue to accept connections rather
38           than stopping after the first connection is complete.
39
40       -p port
41           Change the default rendezvous port (1924) to another port.
42
43           The following are well-known port numbers:
44
45           * HTTP 80
46
47           * HTTPS 443
48
49           * SMTP 25
50
51           * FTP 21
52
53           * IMAP 143
54
55           * IMAPS 993 (IMAP over SSL)
56
57           * NNTP 119
58
59           * NNTPS 563 (NNTP over SSL)
60
61       -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
66           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
70           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
74       -v
75           Print a version string for the tool.
76
77       -x
78           Turn on extra SSL hex dumps.
79

USAGE AND EXAMPLES

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
89           $ ssltap www.netscape.com
90
91       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
111       Example 1
112
113           $ ssltap.exe -sx -p 444 interzone.mcom.com:443 > sx.txt
114
115       Output
116
117           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
127                           (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
144           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
164           \.uC§L.Ç.d<PAHO.
165                             session ID = {
166                             length = 32
167
168                           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
224           }
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
243           }
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
262           }
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
272           }
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
283       Example 2
284
285       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
289           $ ssltap -s  -p 444 interzone.mcom.com:443 > s.txt
290
291       Output
292
293           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
425       Example 3
426
427       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
430           $ ssltap -h  -p 444 interzone.mcom.com:443 > h.txt
431
432       Output
433
434           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
464       Example 4
465
466       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
470           $ ssltap -hs -p 444 interzone.mcom.com:443 > hs.txt
471
472       Output
473
474           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
503           0xcfe9 }
504           }
505           ]
506           <additional records in same formats>
507           Server socket closed.
508

USAGE TIPS

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
514       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

SEE ALSO

522       The NSS Security Tools are also documented at
523       http://www.mozilla.org/projects/security/pki/nss/[2].
524

ADDITIONAL RESOURCES

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
531       Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto
532
533       IRC: Freenode at #dogtag-pki
534

AUTHORS

536       The NSS tools were written and maintained by developers with Netscape,
537       Red Hat, Sun, Oracle, Mozilla, and Google.
538
539       Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey
540       <dlackey@redhat.com>.
541

LICENSE

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

NOTES

548        1. Mozilla NSS bug 836477
549           https://bugzilla.mozilla.org/show_bug.cgi?id=836477
550
551        2. http://www.mozilla.org/projects/security/pki/nss/
552           http://www.mozilla.org/projects/security/pki/nss/tools
553
554
555
556nss-tools                         5 June 2014                        SSLTAP(1)
Impressum