Differences between revisions 95 and 96
Revision 95 as of 2018-12-20 23:22:11
Size: 12169
Editor: GuyHarris
Comment: Current name for Apple's UNIX-for-Macs.
Revision 96 as of 2019-06-10 17:08:52
Size: 15
Editor: PeterWu
Comment: SSL is dead
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:

= Secure Socket Layer (SSL) =
Transport Layer Security (TLS) provides security in the communication between two hosts. It provides integrity, authentication and confidentiality. It is used most commonly in web browsers, but can be used with any protocol that uses TCP as the transport layer.

SSL is the former version of the TLS protocol. These names are often used interchangeably which can lead to some confusion:
 * A configuration that uses the ''SSL protocol'' (SSLv2/SSLv3) is insecure. The ''TLS protocol'' should be used instead.
 * X.509 certificates for authentication are sometimes also called ''SSL Certificates''.
 * Some applications (such as email) use a single port for both unencrypted and encrypted sessions. To change from unencrypted to encrypted, ''(START)TLS'' is used. When a single port directly uses the TLS protocol, it is often referred to as ''SSL''.
 * For historical reasons, software (Wireshark included) refer to SSL or SSL/TLS while it actually means the TLS protocol since that is nowadays what everyone uses.

== Protocol dependencies ==
 * [[TCP]]: Typically, TLS uses [[TCP]] as its transport protocol.

Some well known TCP ports for TLS traffic are

 * 443 https
 * 636 ldaps
 * 989 ftps-data
 * 990 ftps
 * 992 telnets
 * 993 imaps
 * 994 ircs
 * 995 pop3s
 * 5061 sips

== SSL dissection in Wireshark ==
The SSL/TLS dissector is fully functional and even supports advanced features such as decryption of TLS if appropriate secrets are provided. TLS decryption requires Wireshark to be built with Libgcrypt (mandatory since Wireshark 2.4). Support for RSA private key files requires GnuTLS. The official Wireshark binaries have both dependencies.

== Preference Settings ==
Go to ''Edit'' -> ''Preferences''. Open the ''Protocols'' tree and select ''SSL''.
Alternatively, select a SSL/TLS packet in the packet list, right-click on the ''SSL'' layer in the packet details view and open the ''Protocol preferences'' menu.

=== RSA keys list ===
The ''RSA keys list'' button opens a new dialog with the following fields:
||IP address ||The IP address of the SSL server in IPv4 or IPv6 format, or the following special values: ''any'', ''anyipv4'', ''anyipv6'', '''' (this field is ignored since Wireshark 2.0) ||
||Port ||The port number, the special value ''start_tls'' or 0. Ignores since Wireshark 2.0. ||
||Protocol ||A protocol name for the decrypted network data. Popular choices are ''http'' or ''data''. If you enter an invalid protocol name an error message will show you the valid values. ||
||Key File ||path to the RSA private key. ||
||Password ||Leave it empty for PEM-encoded private key files or provide it for encrypted PKCS#12 key files. ||

The RSA key file can either be a ''PEM'' format private key or a PKCS#12 keystore. If the file is a PKCS#12 keystore (typically a file with a .pfx or .p12 extension), the password for the keystore must be specified in the ''Password'' field.

Starting with Wireshark 2.0, the RSA key file is automatically matched against the public key as found in the Certificate handshake message. Before Wireshark 2.0, it relied on the user to enter a valid Address and Port value. Note that only RSA key exchanges can be decrypted using this RSA private key, Diffie-Hellman key exchanges cannot be decrypted using a RSA key file! (See "SSLKEYLOGFILE" if you have such a capture.)

==== Key File format conversion ====
The file format needed is 'PEM'. Note that it is common practice on webservers to combine the public key (or certificate) and the private key in a single PEM file.
In that case - locate this PEM file and cut and paste the section headed by 'PRIVATE KEY' (including header and footer) into a new 'file.key' file which should look like:
....... some 20-100 lines of base64 encoded data ...............

If the PEM file is encrypted, it will appear as:
Proc-Type: 4,ENCRYPTED

Such key files are currently not supported by Wireshark, so they have to be decrypted first:
openssl rsa -in encrypted.key -out new.key

On Windows keys are often stored in PKCS7/DER format (locally) or in NET format (from any directory server). Use the following to convert:

# for PKCS7/DER keys (as held on disk)
openssl pkcs8 -nocrypt -in derfile.key -inform DER -out key.pem -outform PEM
# for NET keys (from the directory server)
openssl pkcs8 -nocrypt -in file.ick -inform NET -out key.pem -outform PEM
On macOS and Solaris, around Oracle and various other systems the file format used is often PKCS#12. Convert with:

openssl pkcs12 -nodes -in file.p12 -out key.pem -nocerts

== Example capture file ==
See also [[SampleCaptures#SSL_with_decryption_keys]].

[[https://bugs.wireshark.org/bugzilla/attachment.cgi?id=11612|dump.pcapng]] TLSv1.2 capture with 73 cipher suites, you need this [[https://bugs.wireshark.org/bugzilla/attachment.cgi?id=11616|premaster.txt]] file for decrypting the traffic. (linked from https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=9144)

== Display Filter ==
A complete list of SSL display filter fields can be found in the [[https://www.wireshark.org/docs/dfref/s/ssl.html|display filter reference]]

Show only the SSL based traffic:

 . {{{

== Capture Filter ==
You cannot directly filter SSL protocols while capturing. However, if you know the [[TCP]] port used (see above), you can filter on that one, for example using {{{tcp port 443}}}.

= Complete SSL decryption walk through =
Ensure you have a version of Wireshark with GnuTLS support:

$ wireshark --version
wireshark 1.0.0

Copyright 1998-2008 Gerald Combs <gerald@wireshark.org> and contributors.
This is free software; see the source for copying conditions. There is NO

Compiled with GTK+ 2.12.9, with GLib 2.16.3, with libpcap 0.9.8, with libz
1.2.3, without POSIX capabilities, with libpcre 7.4, with SMI 0.4.7, with ADNS,
without Lua, with GnuTLS 2.2.2, with Gcrypt 1.4.0, with Heimdal Kerberos,
without PortAudio, without AirPcap.

Running on FreeBSD 7.0-RELEASE, with libpcap version 0.9.8.

Built using gcc 4.2.1 20070719 [FreeBSD].
Specifically check for the '''with GnuTLS 2.2.2''' in the output.

Next create an RSA key and certificate pair with:

openssl req -new -x509 -out server.crt -nodes -keyout server.pem -subj /CN=localhost
Now run a server using above:

openssl s_server -www -cipher AES256-SHA -key server.pem -cert server.crt
and test that the server works by going to https://localhost:4433/ (use the flag {{{-accept 443}}} to bind above to the normal https port).

Now start Wireshark - add above privkey.pem in the SSL preference pane:


This should result in a config snipped in the file ~/.wireshark/preferences

ssl.desegment_ssl_records: TRUE
ssl.desegment_ssl_application_data: TRUE
ssl.debug_file: /home/dirkx/.wireshark-log
and configure the capturing:


and then do a test request; for example with the command

printf 'GET / HTTP/1.0\r\n\r\n' | openssl s_client -ign_eof
Then stop your capture. The screen should look like attached:


And the TCP connection like


and analyze the SSL shows you:


Or if you want to observe authentication with a client cert; try the following:

# Generate self signed cert
openssl req -new -x509 -nodes -out client.crt -keyout client.key -subj /CN=Moi/O=Foo/C=NL
# Start a server
openssl s_server -cipher AES256-SHA -accept 4443 -www -CAfile client.crt -verify 1 -key server.pem -cert server.cert
# And test
printf 'GET / HTTP/1.0\r\n\r\n' | openssl s_client -connect localhost:4443 -ssl3 -cert client.pem -key client.key -ign_eof
# tshark commands
tshark -o "ssl.desegment_ssl_records: TRUE" -o "ssl.desegment_ssl_application_data: TRUE" -o "ssl.keys_list:,4443,http,/home/dirkx/xx/privkey.pem" -o "ssl.debug_file: /home/dirkx/.wireshark-log" -i eth0 -R "tcp.port == 4443"
The log should look like http://people.apache.org/~dirkx/wireshark.log. Or, a more realistic example with Firefox is at http://people.apache.org/~dirkx/wireshark-firefox.log (from>, port 4433).

== Using the (Pre)-Master-Secret ==
Decoding an SSL connection requires either knowledge of the (asymmetric) secret server key and a handshake that does not use DH or the (base of) the symmetric keys used to run the actual encryption. Support was added to Wireshark with SVN revision 37401 to do this, so it became available with Wireshark 1.6. For instructions look at [[http://ask.wireshark.org/questions/4229/follow-ssl-stream-using-master-key-and-session-id|this question on ask.wireshark.org]]

Since SVN revision 36876, it is also possible to decrypt traffic when you do not possess the server key but have access to the pre-master secret. For more details, see [[http://security.stackexchange.com/a/42350/2630|this security.stackexchange.com answer]] or this [[https://jimshaver.net/2015/02/11/decrypting-tls-browser-traffic-with-wireshark-the-easy-way/|step-by-step walkthrough]]. That answer also contains some suggestions on finding out why SSL/TLS sessions do not get decrypted. In short, it should be possible to log the pre-master secret to a file with a current version of Firefox, Chromium or Chrome by setting an environment variable (SSLKEYLOGFILE=</path/to/private/directory/with/logfile>).

Applications using OpenSSL could use a [[https://security.stackexchange.com/q/80158/2630|GDB or a LD_PRELOAD trick]] to extract the secrets. If you do not mind recompiling Qt4/Qt5 with a patch, then see this [[http://www.peter.hartmann.tk/#!How-to-decrypt-SSL-traffic-of-Qt-programs-in-Wireshark/cmzt/555a4a860cf21fee139afdd1|blog with details]]. For Java programs, pre-master secrets can be extracted from the SSL debug log, or output directly in the format Wireshark requires via [[http://jsslkeylog.sourceforge.net/|this agent]]. Python scripts can be [[https://github.com/joernheissler/SslMasterKey|edited]] to dump keys as well.

= External links =
 * https://en.wikipedia.org/wiki/Transport_Layer_Security Wikipedia article for TLS
 * https://sharkfesteurope.wireshark.org/assets/presentations16eu/07.pdf SharkFest'16 EU presentation by Sake Blok on troubleshooting SSL with Wireshark/Tshark (or watch the video of the presentation at https://youtu.be/oDaDY9QCnXk)
 * https://sharkfesteurope.wireshark.org/assets/presentations17eu/15.pdf SharkFest'17 EU presentation by Peter Wu on TLS decryption (not recorded on video)
 * [[http://www.moserware.com/2009/06/first-few-milliseconds-of-https.html|The First Few Milliseconds of an HTTPS Connection]]
 * [[https://isc.sans.edu/forums/diary/Psst+Your+Browser+Knows+All+Your+Secrets/16415/|Psst. Your Browser Knows All Your Secrets.]]
  * Full paper: [[http://www.sans.org/reading-room/whitepapers/authentication/ssl-tls-whats-hood-34297|SSL/TLS:What's under the Hood]], written by Sally Vandeven
 * [[https://blog.cloudflare.com/keyless-ssl-the-nitty-gritty-technical-details/|Keyless SSL: The Nitty Gritty Technical Details]] with a good introduction in TLS

 . CategoryHowTo

SSL (last edited 2019-06-10 17:08:52 by PeterWu)