TLS-Attacker is a Java-based framework for analyzing TLS libraries. It is developed by the Ruhr University Bochum (http://nds.rub.de/) and the Hackmanit GmbH (http://hackmanit.de/).
Java Other
Clone or download
ic0ns Merge pull request #448 from RUB-NDS/new_modvarversion
Updated the Version of the ModifiableVariable Package
Latest commit 6d4de77 Jun 1, 2018
Permalink
Failed to load latest commit information.
.mvn/wrapper Add Maven Wrapper Apr 21, 2016
Attacks Fixed false positives with double alerts in padding oracle and bleich… May 30, 2018
TLS-Client Updated default values in config, removed unsupported tests from clie… May 3, 2018
TLS-Core ConfigIO now also uses the pretty xml printer, reformatted default_co… Jun 1, 2018
TLS-Forensics Updated version to 2.5 Mar 8, 2018
TLS-Mitm Merge origin/master into docker_it_remove Apr 10, 2018
TLS-Server Added starttls delegate to client and server Apr 13, 2018
TraceTool Updated version to 2.5 Mar 8, 2018
Transport Merge origin/secp256r1tls13 into testcontainers Mar 19, 2018
Utils Removed DockerTests from this repo and move them to "TLS-Attacker-IT-… Apr 10, 2018
resources Moved newly added configs to new resource/configs folder Mar 19, 2018
.gitignore DH_ANON cipher suite now working not accidentally :-) Apr 17, 2018
.travis.yml Update .travis.yml Nov 21, 2017
LICENSE Initial commit Mar 26, 2015
README.md Update README.md Dec 12, 2017
checkstyle.xml Removed author tags Feb 9, 2018
license_header.txt Changed the lincense header and updated it in every class. May 8, 2017
license_header_plain.txt Changed the lincense header and updated it in every class. May 8, 2017
maven-eclipse-codestyle.xml Fixed formatting Nov 6, 2017
mvnw Added MockedRandom and formatted Nov 18, 2016
mvnw.cmd Big merge, tried to get everything working as good as possible, but i… Nov 2, 2016
nb-configuration.xml Merge origin/master into STARTTLS Apr 11, 2018
nbactions.xml Bugfixes and refacoting Sep 27, 2017
pom.xml Updated ModifiableVariable Version Jun 1, 2018

README.md

TLS-Attacker

release licence travis

TLS-Attacker is a Java-based framework for analyzing TLS libraries. It is able to send arbitrary protocol messages in an arbitrary order to the TLS peer, and define their modifications using a provided interface. This gives the developer an opportunity to easily define a custom TLS protocol flow and test it against his TLS library.

Please note: TLS-Attacker is a research tool intended for TLS developers and pentesters. There is no GUI and no green/red lights.

Compiling and Running

In order to compile and use TLS-Attacker, you need to have Java installed. Run the maven command from the TLS-Attacker directory:

$ cd TLS-Attacker
$ ./mvnw clean package

Alternatively, if you are in hurry, you can skip the tests by using:

$ ./mvnw clean package -DskipTests=true

TLS-Attacker ships with demo applications which provide you easy access to TLS-Attacker functionality.

You can run TLS-Attacker as a client with the following command:

$ java -jar TLS-Client.jar -connect [host:port]

or as a server with:

$ java -jar TLS-Server.jar -port [port]

TLS-Attacker also ships with some example attacks on TLS to show you how easy it is to implement an attack with TLS-Attacker. You can run those examples with the following command:

$ java -jar Attacks.jar [Attack] -connect [host:port]

Although these example applications are very powerful in itself, TLS-Attacker unleashes its full potential when used as a programming library.

Code Structure

TLS-Attacker consists of several (maven) projects:

  • TLS-Core: The protocol stack and heart of TLS-Attacker
  • Transport: Transport utilities for lower layers
  • Utils: A collection of utility classes
  • TLS-Client: The client example application
  • TLS-Server: The server example application
  • Attacks: Implementation of some well-known attacks and vulnerability tests.
  • TLS-Mitm: A prototype for MitM workflows TLS-Attacker design

You can find more information about these modules in the Wiki.

Features

Currently, the following features are supported:

  • SSL 3, TLS versions 1.0 (RFC-2246), 1.1 (RFC-4346), 1.2 (RFC-5246), and 1.3 (draft-ietf-tls-tls13-21)
  • DTLS 1.2 (RFC-6347)(Currently under development)
  • SSL 2 (Client/Server Hello)
  • (EC)DH and RSA key exchange algorithms
  • CBC, AEAD and Streamciphers
  • TLS client and server
  • HTTPS
  • MitM (experimental)
  • Lots of extensions
  • Tokenbinding (EC) and Tokenbinding over HTTP
  • Sockets
  • PSK (All modes)
  • SRP
  • TLS 1.3 0-RTT

Usage

Here we present some very simple examples on using TLS-Attacker.

First, you need to start a TLS server (please do not use public servers). For example, you can use an OpenSSL test server:

$ cd TLS-Attacker/resources
$ openssl s_server -key rsa1024key.pem -cert rsa1024cert.pem

This command starts a TLS server on a port 4433 (please run the keygen.sh script if not done before).

If you want to connect to a server, you can use this command:

$ java -jar TLS-Client.jar -connect localhost:4433

Note: If this Handshake fails, it is probably because you did not specify a concrete cipher suite. TLS-Attacker will not completely respect server selected cipher suites.

You can use a different cipher suite, TLS version, or connect to a different port with the following parameters:

$ java -jar TLS-Client.jar -connect localhost:4433 -cipher TLS_RSA_WITH_AES_256_CBC_SHA -version TLS11

The Attacks module contains some attacks, you can for example test for the padding oracle vulnerabilities:

$ java -jar Attacks.jar padding_oracle -connect localhost:4433 

In case you are a more experienced developer, you can create your own TLS message flow. By writing Java code. For example:

Config config = Config.createConfig();
WorkflowTrace trace = new WorkflowTrace();
trace.addTlsAction(new SendAction(new ClientHelloMessage()));
trace.addTlsAction(new ReceiveAction(new ServerHelloMessage()));
State state = new State(config, trace);
DefaultWorkflowExecutor executor = new
DefaultWorkflowExecutor(state);
executor.executeWorkflow();

TLS-Attacker uses the concept of WorkflowTraces to define a "TLS message flow". A WorkflowTrace consists of a List of Actions which are then executed one after the other. Although for a typical "TLS message flow" only SendAction's and ReceiveAction's are needed, the Framework does not stop here and implements alot of different other Actions which can be used to execute even more Arbitrary message flows. A list of currently implemented Actions with explanations can be found in the Wiki.

We know many of you hate Java. Therefore, you can also use an XML structure and run your customized TLS protocol from XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<workflowTrace>
    <Send>
        <messages>
            <ClientHello>
                <extensions>
                    <ECPointFormat/>#
                    <HeartbeatExtension/>
                    <EllipticCurves/>
                </extensions>
            </ClientHello>
        </messages>
    </Send>
    <Receive>
        <expectedMessages>
            <ServerHello>
                <extensions>
                    <ECPointFormat/>
                </extensions>
            </ServerHello>
            <Certificate/>
            <ServerHelloDone/>
        </expectedMessages>
    </Receive>
    <Send>
        <messages>
            <RSAClientKeyExchange>
                <computations/>
            </RSAClientKeyExchange>
            <ChangeCipherSpec/>
            <Finished/>
        </messages>
    </Send>
    <Receive>
        <expectedMessages>
            <ChangeCipherSpec/>
            <Finished/>
        </expectedMessages>
    </Receive>
</workflowTrace>

Given this XML structure is located in workflow.xml, you would just need to execute:

$ java -jar TLS-Client.jar -connect [host]:[port] -workflow_input workflow.xml

Modifiable Variables

TLS-Attacker uses the concept of Modifiable variables to allow runtime Modifications to predefined Workflows. Modifiable variables allow one to set modifications to basic types after or before their values are actually set. When their actual values are determined and one tries to access the value via getters the original value will be returned in a modified form accordingly. More details on this concept can be found at https://github.com/RUB-NDS/ModifiableVariable.

ModifiableInteger i = new ModifiableInteger();
i.setOriginalValue(30);
i.setModification(new AddModification(20));
System.out.println(i.getValue());  // 50

In this example, we defined a new ModifiableInteger and set its value to 30. Next, we defined a new modification AddModification which simply returns a sum of two integers. We set its value to 20. If we execute the above program, the result 50 is printed.

We can of course use this concept by constructing our TLS workflows. Imagine you want to test a server for a heartbleed vulnerability. For this purpose, you need to increase the payload length in the heartbeat request. With TLS-Attacker, you can do this as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<workflowTrace>
    <Send>
        <messages>
            <ClientHello>
                <extensions>
                    <ECPointFormat/>#
                    <HeartbeatExtension/>
                    <EllipticCurves/>
                </extensions>
            </ClientHello>
        </messages>
    </Send>
    <Receive>
        <expectedMessages>
            <ServerHello>
                <extensions>
                    <ECPointFormat/>
                </extensions>
            </ServerHello>
            <Certificate/>
            <ServerHelloDone/>
        </expectedMessages>
    </Receive>
    <Send>
        <messages>
            <RSAClientKeyExchange>
                <computations/>
            </RSAClientKeyExchange>
            <ChangeCipherSpec/>
            <Finished/>
        </messages>
    </Send>
    <Receive>
        <expectedMessages>
            <ChangeCipherSpec/>
            <Finished/>
        </expectedMessages>
    </Receive>
    <Send>
        <messages>
            <Heartbeat>
                <payloadLength>
                <integerExplicitValueModification>
                    <explicitValue>20000</explicitValue>
                    </integerExplicitValueModification>
                </payloadLength>
            </Heartbeat>
	</messages>
    </Send>
    <Receive>
		<Heartbeat/>
    </Receive>
</workflowTrace>

As you can see, we explicitly increased the payload length of the Heartbeat message by 20000. If you run the attack against the vulnerable server (e.g., OpenSSL 1.0.1f), you should see a valid Heartbeat response.

Further examples on attacks and further explanations on TLS-Attacker can be found in the Wiki.

Advanced Features

Some Actions require context, or configuration to be executed correctly. For exmaple, if TLS-Attacker tries to send a ClientHello message, it needs to know which values to put into the message, e.g., which Ciphersuites or which protocol version to use. TLS-Attacker draws this information from a configuration file (default located in TLS-Core/src/main/resources/default_config.xml). Values which are determined at runtime are stored in the TlsContext. When a value which is normally selected from the context is missing (because a message was not yet received), the default value from the Config is selected. You can specify your own configuration file from command line with the "-config" parameter. Note that if you do not explicitly define a default value in the config file, TLS-Attacker fills this gap with hardcoded values (which are equal to the provided default config). More details on how to customize TLS-Attacker can be found in the wiki.

Acknowledgements

The following people have contributed code to the TLS-Attacker project:

  • Florian Pfützenreuter: DTLS 1.2
  • Felix Lange: EAP-TLS
  • Philip Riese: Server implementation, TLS Man-in-the-Middle prototype
  • Christian Mainka: Design support and many implementation suggestions
  • Matthias Terlinde: More TLS-Extensions
  • Nurullah Erinola: TLS 1.3 Support
  • Lucas Hartmann: TLS-MitM Workflows
  • Florian Linsner: PSK, SRP
  • Pierre Tilhaus: Code quality improvements
  • Felix Kleine-Wilde: SSL 3 Support
  • Marcel Maehren: 0-RTT Support Additionally we would like to thank all the other people who have contributed code to the project.

Further contributions and pull requests are welcome.

TLS-Attacker Projects

The basic concepts behind TLS-Attacker and several attacks are described in the following paper:

TLS-Attacker was furthermore used in the following scientific papers and projects:

If you have any research ideas or need support by using TLS-Attacker (e.g. you want to include it in your test suite), feel free to contact http://www.hackmanit.de/.

If TLS-Attacker helps you to find a bug in a TLS implementation, please acknowledge this tool. Thank you!