JarCasting
JarCasting JarCasting

Extract SSL Master Secret

Decrypt HTTPS/SSL/TLS connections on-the-fly with Wireshark. Extracts the shared master key used in secure connections (SSL & TLS) for use with Wireshark. Works with connections established with the (Java provided) javax.net.ssl.SSLSocket API.

License

License
GroupId

GroupId

name.neykov
ArtifactId

ArtifactId

extract-ssl-secrets
Last Version

Last Version

3.0.0
Release Date

Release Date
Type

Type

jar
Description

Description

Extract SSL Master Secret
Decrypt HTTPS/SSL/TLS connections on-the-fly with Wireshark. Extracts the shared master key used in secure connections (SSL & TLS) for use with Wireshark. Works with connections established with the (Java provided) javax.net.ssl.SSLSocket API.
Project URL

Project URL

https://github.com/neykov/extract-ssl-secrets
Source Code Management

Source Code Management

http://github.com/neykov/extract-ssl-secrets

Download extract-ssl-secrets

Filename Size
extract-ssl-secrets-3.0.0.pom
extract-ssl-secrets-3.0.0.jar 813 KB
extract-ssl-secrets-3.0.0-sources.jar 11 KB
extract-ssl-secrets-3.0.0-javadoc.jar 413 KB
Browse

How to add to project

<!-- https://jarcasting.com/artifacts/name.neykov/extract-ssl-secrets/ -->
<dependency>
    <groupId>name.neykov</groupId>
    <artifactId>extract-ssl-secrets</artifactId>
    <version>3.0.0</version>
</dependency>
// https://jarcasting.com/artifacts/name.neykov/extract-ssl-secrets/
implementation 'name.neykov:extract-ssl-secrets:3.0.0'
// https://jarcasting.com/artifacts/name.neykov/extract-ssl-secrets/
implementation ("name.neykov:extract-ssl-secrets:3.0.0")
'name.neykov:extract-ssl-secrets:jar:3.0.0'
<dependency org="name.neykov" name="extract-ssl-secrets" rev="3.0.0">
  <artifact name="extract-ssl-secrets" type="jar" />
</dependency>
@Grapes(
@Grab(group='name.neykov', module='extract-ssl-secrets', version='3.0.0')
)
libraryDependencies += "name.neykov" % "extract-ssl-secrets" % "3.0.0"
[name.neykov/extract-ssl-secrets "3.0.0"]

Dependencies

There are no dependencies for this project. It is a standalone project that does not depend on any other jars.

Project Modules

There are no modules declared in this project.

extract-tls-secrets

Decrypt HTTPS/TLS connections on-the-fly. Extract the shared secrets from secure TLS connections for use with Wireshark. Attach to a Java process on either side of the connection to start decrypting.

Usage

Download from extract-tls-secrets-4.0.0.jar. Then attach to a Java process in one of two ways:

Attach on startup

Add a startup argument to the JVM options: -javaagent:<path to jar>/extract-tls-secrets-4.0.0.jar=<path to secrets log file>

For example to launch an application from a jar file run:

java -javaagent:~/Downloads/extract-tls-secrets-4.0.0.jar=/tmp/secrets.log -jar MyApp.jar

To launch in Tomcat add the parameter to CATALINA_OPTS:

CATALINA_OPTS=-javaagent:~/Downloads/extract-tls-secrets-4.0.0.jar=/tmp/secrets.log bin/catalina.sh run

Attach to a runing process

Attaching to an existing Java process requires a JDK install with JAVA_HOME pointing to it.

To list the available process IDs run:

java -jar ~/Downloads/extract-tls-secrets-4.0.0.jar list

Next attach to the process by executing:

java -jar ~/Downloads/extract-tls-secrets-4.0.0.jar <pid> /tmp/secrets.log

Decrypt the capture in Wireshark

To decrypt the capture you need to let Wireshark know where the secrets file is. Configure the path in Preferences > Protocols > TLS (SSL for older versions) > (Pre)-Master-Secret log filename.

Alternatively start Wireshark with:

wireshark -o tls.keylog_file:/tmp/secrets.log

The packets will be decrypted in real-time.

For a step by step tutorial of using the secrets log file (SSLKEYLOGFILE as referenced usually) refer to the Peter Wu's Debugging TLS issues with Wireshark presentation. Even more information can be found at the Wireshark TLS page.

Requirements

Requires at least Java 6.

Building

git clone https://github.com/neykov/extract-tls-secrets.git
cd extract-tls-secrets
mvn clean package

Running the integration tests requires Docker to be installed on the system:

mvn verify

Troubleshooting

If you get an empty window after selecting "Follow/TLS Stream" from the context menu or are not seeing HTTP protocol packets in the packet list then you can fix this by either:

  • Save the capture as a file and open it again
  • In the Wireshark settings in "Procotols/TLS" toggle "Reassemble TLS Application Data spanning multiple SSL records". The exact state of the checkbox doesn't matter, but it will force a reload which will force proper decryption of the packets.

The bug seems to be related to the UI side of wireshark as the TLS debug logs show the message successfully being decrypted.

Reports of the problem:

If "Follow/TLS Stream" is not enabled the server is probably on a non-standard port so Wireshark can't infer that the packets contain TLS traffic. To hint it that it should be decoding the packets as TLS right click on any of the packets to open the context menu, select "Decode As" and add the server port, select "TLS" protocol in the "Current" column. If it's still not able to decrypt try the same by saving the capture in a file and re-opening it.

Versions

Version
3.0.0
2.0.0
1.0.0