ssltap.xml (20752B)
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 ]> 7 8 <refentry id="ssltap"> 9 10 <refentryinfo> 11 <date>&date;</date> 12 <title>NSS Security Tools</title> 13 <productname>nss-tools</productname> 14 <productnumber>&version;</productnumber> 15 </refentryinfo> 16 17 <refmeta> 18 <refentrytitle>SSLTAP</refentrytitle> 19 <manvolnum>1</manvolnum> 20 </refmeta> 21 22 <refnamediv> 23 <refname>ssltap</refname> 24 <refpurpose>Tap into SSL connections and display the data going by </refpurpose> 25 </refnamediv> 26 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> 35 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> 41 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> 46 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> 125 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> 137 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 = { 151 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 168 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 | 188 189 \.uC§L.Ç.d<PAHO. 190 session ID = { 191 length = 32 192 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 > 248 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 > 267 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 > 286 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 > 296 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> 308 309 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> 449 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> 487 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 524 525 0xcfe9 } 526 } 527 ] 528 <additional records in same formats> 529 Server socket closed. 530 </programlisting> 531 532 533 534 </refsection> 535 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> 549 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> 554 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> 562 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> 571 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> 578 579 </refentry>