Skip to content

TLS Client

Jump to bottom
Robert Merget edited this page Sep 30, 2024 · 5 revisions

Simple TLS Client

If you want to connect to a server, you can use the TLS-Attacker client application which is located in the "apps" folder. You can connect to a server by running:

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

The client allows you to define various parameters. For a full list of currently available parameters run:

$ java -jar TLS-Client.jar

This includes for example:

  • max_fragment_length: Maximum fragment length definition for the max fragment length TLS extension (possible byte values 1,2,3, or 4)
  • named_curve: Named curves to be used, divided by a comma, e.g. SECP192R1, SECP256R1, SECP384R1, SECP521R1
  • server_name: Servername used in the SNI TLS extension.
  • timeout: This indicates the maximum number in milliseconds the client waits for the server TLS message response. The default value is 1000, which is pretty high for localhost tests, but can be too low for network tests. Play with this value to speed up your tests and use e.g. 30 for OpenSSL running on localhost or 50 for JSSE on localhost.

WorkflowTrace Types

TLS-Attacker has multiple often used WorkflowTrace's integrated which allow you to execute and to create specific message flows very fast. You can execute those Traces with the parameter: -workflow_trace_type

The following WorkflowTrace Types are currently support:

  • SHORT_HELLO: A Workflow with only a Client- and ServerHello Message
  • HELLO: A Workflow which ends after the ServerHelloDone Message
  • HANDSHAKE: A Workflow which ends after the Finished messages have been exchanged
  • FULL: A Workflow which executes a Handshake and then sends an ApplicationData message.
  • RESUMPTION: A Workflow which resumes a connection. This workflow only works if you specify a SessionID
  • FULL_RESUMPTION: A Workflow which executes a Handshake, resets the connection and then resumes the previous handshake
  • CLIENT_RENEGOTIATION: A Workflow which executes a handshake with client initiated renegotiation (no resumption)
  • SERVER_RENEGOTIATION: A Workflow which executes a handshake with server initiated renegotiation (no resumption)
  • HTTPS: A Workflow which executes a handshake and a HttpsRequest/HttpsResponse in the end. This workflow only works if you enable https in the config (default not enabled).
  • SSL2_HELLO: A Workflow which contains a Client- and Server SSL2 Message with a Blobrecord.

Example:

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

Custom Protocol Flows

You can use TLS-Attacker to execute customized protocol flows. You can define them in an XML message and then execute (given the file is called workflow.xml):

$ java -jar TLS-Client.jar -connect localhost:4433 -workflow_input workflow.xml

A simple ECDHE RSA protocol flow definition would look like this:

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

If you want to duplicate a specific insert specific message, for example insert a second ECDHClientKeyExchange message, just modify the XML protocol flow like this:

<workflowTrace>
    <Send>
        <messages>
            <ClientHello>
                <extensions>
                    <ECPointFormat/>
                    <EllipticCurves/>
                </extensions>
            </ClientHello>
        </messages>
    </Send>
    <Receive>
        <expectedMessages>
            <ServerHello>
                <extensions>
                    <ECPointFormat/>
                </extensions>
            </ServerHello>
            <Certificate/>
            <ECDHEServerKeyExchange/>
            <ServerHelloDone/>
        </expectedMessages>
    </Receive>
    <Send>
        <messages>
            <ECDHClientKeyExchange/>
            <ECDHClientKeyExchange/>
            <ChangeCipherSpec/>
            <Finished/>
        </messages>
    </Send>
    <Receive>
        <expectedMessages>
            <ChangeCipherSpec/>
            <Finished/>
        </expectedMessages>
    </Receive>
    <Send>
        <messages>
            <Application/>
        </messages>
    </Send>
</workflowTrace>

When running the client with this configuration, you can see it issues two ECDHClientKeyExchange messages and sends them to the server.

To have a good template for TLS protocol flows, you can use the provided TraceUtil. You can run with the the following command to generate the same WorkflowTrace:

$ java -jar TraceTool.jar -running_mode CLIENT -cipher TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA -workflow_trace_type FULL

Custom Protocol Messages

The above given protocol modification just inserts a new ECDHClientKeyExchange message. It is however also possible to execute arbitrary modifications on message variables.

Imagine that the previous command resulted in a TLS workflow including the following ClientKeyExchange message:

        <ECDHClientKeyExchange>
                <completeResultingMessage>
                    <originalValue>
10 00 00 86 85 04 00 05  5B A5 66 32 FB 58 83 32
2E C3 01 2C FA E4 30 2D  8B 13 FF C8 64 B0 01 2F
1D B1 33 D6 0F A7 03 C0  73 77 5C F1 45 37 31 51
65 7E B5 CA 7F 3E 3A B4  54 BE A7 79 90 3B 72 25
74 26 A6 3A CA 0A C2 9B  01 27 D1 A7 29 40 A2 05
D1 11 FD 8D 54 F1 A3 05  98 6D AD 78 6A 51 F9 CC
23 E0 9B E5 34 05 A3 1B  61 41 5A 58 64 71 0F 18
26 69 29 56 71 8B 6E 10  EA 91 C6 E9 CC 97 94 EF
41 D3 CC 92 5C 21 02 1C  50 6E
</originalValue>
                </completeResultingMessage>
                <type>
                    <originalValue>16</originalValue>
                </type>
                <length>
                    <originalValue>134</originalValue>
                </length>
                <publicKeyLength>
                    <originalValue>133</originalValue>
                </publicKeyLength>
                <publicKey>
                    <originalValue>
04 00 05 5B A5 66 32 FB  58 83 32 2E C3 01 2C FA
E4 30 2D 8B 13 FF C8 64  B0 01 2F 1D B1 33 D6 0F
A7 03 C0 73 77 5C F1 45  37 31 51 65 7E B5 CA 7F
3E 3A B4 54 BE A7 79 90  3B 72 25 74 26 A6 3A CA
0A C2 9B 01 27 D1 A7 29  40 A2 05 D1 11 FD 8D 54
F1 A3 05 98 6D AD 78 6A  51 F9 CC 23 E0 9B E5 34
05 A3 1B 61 41 5A 58 64  71 0F 18 26 69 29 56 71
8B 6E 10 EA 91 C6 E9 CC  97 94 EF 41 D3 CC 92 5C
21 02 1C 50 6E
</originalValue>
                </publicKey>
                <publicKeyBaseX>
                    <originalValue>1456936434122493942418011681936820442015704987159136108509572635979950505600687705798358428174082524670368071707664670093497074411368372794510091941314882428</originalValue>
                </publicKeyBaseX>
                <publicKeyBaseY>
                    <originalValue>3467445345950316520579270284240642967012134532844517962882091496017802335193702029648462908148666206167300599729559241447601571304408888882988603361461762653</originalValue>
                </publicKeyBaseY>
                <ecPointFormat>
                    <originalValue>4</originalValue>
                </ecPointFormat>
                <ecPointEncoded>
                    <originalValue>
00 05 5B A5 66 32 FB 58  83 32 2E C3 01 2C FA E4
30 2D 8B 13 FF C8 64 B0  01 2F 1D B1 33 D6 0F A7
03 C0 73 77 5C F1 45 37  31 51 65 7E B5 CA 7F 3E
3A B4 54 BE A7 79 90 3B  72 25 74 26 A6 3A CA 0A
C2 9B 01 27 D1 A7 29 40  A2 05 D1 11 FD 8D 54 F1
A3 05 98 6D AD 78 6A 51  F9 CC 23 E0 9B E5 34 05
A3 1B 61 41 5A 58 64 71  0F 18 26 69 29 56 71 8B
6E 10 EA 91 C6 E9 CC 97  94 EF 41 D3 CC 92 5C 21
02 1C 50 6E
</originalValue>
                </ecPointEncoded>
                <computations>
                    <clientRandom>
                        <originalValue>
57 2C 67 76 60 B4 20 BB  38 51 D9 D4 7A CB 93 3D
BE 70 39 9B F6 C9 2D A3  3A F0 1D 4F B7 70 E9 8C
59 AF EA 99 B7 B2 1B 57  E9 0E E8 DE 3F 83 4C FF
40 5E 44 16 0D BF D2 0C  0A AA 98 F7 AE 50 E3 E6
</originalValue>
                    </clientRandom>
                    <premasterSecret>
                        <originalValue>
01 E2 C3 8C 30 EE 28 D2  B8 73 FE F9 B5 00 CB 71
98 3A B8 09 CA 7F 31 91  32 8F EC FA 1E 35 4B D3
28 74 2C D5 6B 08 06 6B  6B EF 51 53 DB A2 89 6C
EA DE EA 53 63 D6 C2 95  F9 95 B3 F9 5C A3 57 31
E0 58
</originalValue>
                    </premasterSecret>
                    <clientPrivateKey>
                        <originalValue>191991257030464195512760799659436374116556484140110877679395918219072292938297573720808302564562486757422301181089761</originalValue>
                    </clientPrivateKey>
                    <clientPublicKey>
                        <x>1456936434122493942418011681936820442015704987159136108509572635979950505600687705798358428174082524670368071707664670093497074411368372794510091941314882428</x>
                        <y>3467445345950316520579270284240642967012134532844517962882091496017802335193702029648462908148666206167300599729559241447601571304408888882988603361461762653</y>
                    </clientPublicKey>
                    <serverPublicKeyX>
                        <originalValue>491203895040108745449226294243745455741227764348020347601261500169716128115592349437974135304912558309930853019224526710623014608159863752395772072678677659</originalValue>
                    </serverPublicKeyX>
                    <serverPublicKeyY>
                        <originalValue>6467812673939715228041063957432911043592064608152961403699846371346953482430810509368682787908186918214113595824022393714707946058455767927416547714727359253</originalValue>
                    </serverPublicKeyY>
                </computations>
            </ECDHClientKeyExchange>

This protocol message contains all information related to it. In order to execute the protocol flow with a modified message, for example a message with an invalid publicKeyLength, you can define this value as follows:

<publicKeyLength>
    <integerExplicitValueModification>
        <explicitValue>70</explicitValue>
    </integerExplicitValueModification>
</publicKeyLength>

When using this value in the protocol flow, the publicKeyLength value will be explicitly set to 70 during the message processing, independently of the real public key length. The resulting ClientKeyExchange message would simply look like this (you do not have to preserve all the values and fields):

        <ECDHClientKeyExchange>
            <messageIssuer>CLIENT</messageIssuer>
            <publicKeyLength>
                <integerExplicitValueModification>
                     <explicitValue>70</explicitValue>
                </integerExplicitValueModification>
            </publicKeyLength>
        </ECDHClientKeyExchange>

IMPORTANT: Do not try to insert your Modifications into the originalValue's you see in the Handshake. TLS-Attacker will overwrite your values and you will see no effekt. You should modify the Handshake exclusively by adding Modifications or by add/removing things. **

Similar modifications can be performed for other fields in the ClientKeyExchange message, like fragmentLength or length. Note that serverPublicKeyX and serverPublicKeyY are of type BigInteger and thus need other modifications, e.g.:

<publicKeyBaseX>
    <bigIntegerAddModification>
        <summand>1</summand>
    </bigIntegerAddModification>
</publicKeyBaseX>

If you want to edit byte arrays, use for example the following modification:

<premasterSecret>
    <byteArrayExplicitValueModification>
        <explicitValue>
            4F 3F 8C FC 17 8E 66 0A  
        </explicitValue>
    </byteArrayExplicitValueModification>
</premasterSecret>

More examples on modifications can be found in: Modifiable-Variables

If you want to execute custom TLS workflows from Java, you can take a look at the implementation of some attacks here: https://github.com/tls-attacker/tls-breaker

Clone this wiki locally