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