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