In the last two years, we changed the TLS-Attacker Project quite a lot but kept silent about most changes we implemented. Since we do not have so much time to keep up with the documentation (we are researchers and not developers in the end), we thought about creating a small series on some of our recent changes to the project on this blog.
We hope this gives you an idea on how to use the most recent version (TLS-Attacker 2.8). If you feel like you found a bug, don't hesitate to contact me via GitHub/Mail/Twitter. This post assumes that you have some idea what this is all about. If you have no idea, checkout the original paper from Juraj or our project on GitHub.
TLDR: TLS-Attacker is a framework which allows you to send arbitrary protocol flows.
Quickstart:
# Install & Use Java JDK 8
$ sudo apt-get install maven
$ git clone https://github.com/RUB-NDS/TLS-Attacker
$ cd TLS-Attacker
$ mvn clean package
So, what changed since the release of the original paper in 2016? Quite a lot! We discovered that we could make the framework much more powerful by adding some new concepts to the code which I want to show you now.
Although this design looks straight forward, it lacks flexibility. In this design, a WorkflowTrace is basically a list of messages. Each message is annotated with a <messageIssuer>, to tell TLS-Attacker that it should either try to receive this message or send it itself. If you now want to support more advanced workflows, for example for renegotiation or session resumption, TLS-Attacker will soon reach its limits. There is also a missing angle for fuzzing purposes. TLS-Attacker will by default try to use the correct parameters for the message creation, and then apply the modifications afterward. But what if we want to manipulate parameters of the connection which influence the creation of messages? This was not possible in the old version, therefore, we created our action system. With this action system, a WorkflowTrace does not only consist of a list of messages but a list of actions. The most basic actions are the Send- and ReceiveAction. These actions allow you to basically recreate the previous behavior of TLS-Attacker 1.x . Here is an example to show how the same workflow would look like in the newest TLS-Attacker version:
As you can see, the <messageIssuer> tags are gone. Instead, you now indicate with the type of action how you want to deal with the message. Another important thing: TLS-Attacker uses WorkflowTraces as an input as well as an output format. In the old version, once a WorkflowTrace was executed it was hard to see what actually happened. Especially, if you specify what messages you expect to receive. In the old version, your WorkflowTrace could change during execution. This was very confusing and we, therefore, changed the way the receiving of messages works. The ReceiveAction has a list of <expectedMessages>. You can specify what you expect the other party to do. This is mostly interesting for performance tricks (more on that in another post), but can also be used to validate that your workflow executedAsPlanned. Once you execute your ReceiveAction an additional <messages> tag will pop up in the ReceiveAction to show you what has actually been observed. Your original WorkflowTrace stays intact.
During the execution, TLS-Attacker will execute the actions one after the other. There are specific configuration options with which you can control what TLS-Attacker should do in the case of an error. By default, TLS-Attacker will never stop, and just execute whatever is next.
Usually, the RSAClientKeyExchange message is constructed with the public key from the received certificate message. But in this WorkflowTrace, we did not receive a certificate message yet. So what public key are we supposed to use? The previous version had "some" key hardcoded. The new version does not have these default values hardcoded but allows you as the user to define the default values for missing values, or how our own messages should be created. For this purpose, we introduced the new concept of Configs. A Config is a file/class which you can provide to TLS-Attacker in addition to a WorkflowTrace, to define how TLS-Attacker should behave, and how TLS-Attacker should create its messages (even in the absence of needed parameters). For this purpose, TLS-Attacker has a default Config, with all the known hardcoded values. It is basically a long list of possible parameters and configuration options. We chose sane values for most things, but you might have other ideas on how to do things. You can execute a WorkflowTrace with a specific config. The provided Config will then overwrite all existing default values with your specified values. If you do not specify a certain value, the default value will be used. I will get back to how Configs work, once we played a little bit with TLS-Attacker.
TLS-Attacker ships with a few example applications (found in the "apps/" folder after you built the project). While TLS-Attacker 1.x was mostly a standalone tool, we currently see TLS-Attacker more as a library which we can use by our more sophisticated projects. The current example applications are:
The most trivial command you can start it with is:
Note: The example tool does not like "https://" or other protocol information. Just provide a hostname and port
Depending on the host you chose your output might look like this:
or like this:
So what is going on here? Let's start with the first execution. As I already mentioned. TLS-Attacker constructs the default WorkflowTrace based on the default selected cipher suite. When you run the client, the WorkflowExecutor (part of TLS-Attacker which is responsible for the execution of a WorkflowTrace) will try to execute the handshake. For this purpose, it will first start the TCP connection.
This is what you see here:
After that, it will execute the actions specified in the default WorkflowTrace. The default WorkflowTrace looks something like this:
This is basically what you see in the console output. The first action which gets executed is the SendAction with the ClientHello.
Then, we expect to receive messages. Since we want to be an RSA handshake, we do not expect a ServerKeyExchange message, but only want a ServerHello, Certificate and a ServerHelloDone message.
We then execute the second SendAction:
and finally, we want to receive a ChangeCipherSpec and Finished Message:
In the first execution, these steps all seem to have worked. But why did they fail in the second execution? The reason is that our default Config does not only allow specify RSA cipher suites but creates ClientHello messages which also contain elliptic curve cipher suites. Depending on the server you are testing with, the server will either select and RSA cipher suite, or an elliptic curve one. This means, that the WorkflowTrace will not executeAsPlanned. The server will send an additional ECDHEServerKeyExchange. If we would look at the details of the ServerHello message we would also see that an (ephemeral) elliptic curve cipher suite is selected:
Since our WorkflowTrace is configured to send an RSAClientKeyExchange message next, it will just do that:
Note: ClientKeyExchangeMessage all have the same type field, but are implemented inside of TLS-Attacker as different messages
Since this RSAClientKeyExchange does not make a lot of sense for the server, it rejects this message with a DECODE_ERROR alert:
If we would change the Config of TLS-Attacker, we could change the way our ClientHello is constructed. If we specify only RSA cipher suites, the server has no choice but to select an RSA one (or immediately terminate the connection). We added command line flags for the most common Config changes. Let's try to change the default cipher suite to TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA:
As you can see, we now executed a complete ephemeral elliptic curve handshake. This is, because the -cipher flag changed the <defaultSelectedCiphersuite> parameter (among others) in the Config. Based on this parameter the default WorkflowTrace is constructed. If you want, you can specify multiple cipher suites at once, by seperating them with a comma.
We can do the same change by supplying TLS-Attacker with a custom Config via XML. To this we need to create a new file (I will name it config.xml) like this:
You can then load the Config with the -config flag:
For a complete reference of the supported Config options, you can check out the default_config.xml. Most Config options should be self-explanatory, for others, you might want to check where and how they are used in the code (sorry).
Now let's try to execute an arbitrary WorkflowTrace. To do this, we need to store our WorkflowTrace in a file and load it with the -workflow_input parameter. I just created the following WorkflowTrace:
As you can see I just send a ServerHello message instead of a ClientHello message at the beginning of the handshake. This should obviously never happen but let's see how the tested server reacts to this.
We can execute the workflow with the following command:
The server (correctly) responded with an UNEXPECTED_MESSAGE alert. Great!
Let's try to execute our last created WorkflowTrace, and store the output WorkflowTrace in the file out.xml:
The resulting WorkflowTrace looks like this:
As you can see, although the input WorkflowTrace was very short, the output trace is quite noisy. TLS-Attacker will display all its intermediate values and modification points (this is where the modifiable variable concept becomes interesting). You can also execute the output workflow again.
Note that at this point there is a common misunderstanding: TLS-Attacker will reset the WorkflowTrace before it executes it again. This means, it will delete all intermediate values you see in the WorkflowTrace and recompute them dynamically. This means that if you change a value within <originalValue> tags, your changes will just be ignored. If you want to influence the values TLS-Attacker uses, you either have to manipulate the Config (as already shown) or apply modifications to TLS-Attackers ModifiableVariables. The concept of ModifiableVariables is mostly unchanged to the previous version, but we will show you how to do this real quick anyway.
So let us imagine we want to manipulate a value in the WorkflowTrace using a ModifiableVariable via XML. First, we have to select a field which we want to manipulate. I will choose the protocol version field in the ServerHello message we sent. In the WorkflowTrace this looked like this:
For historical reasons, 0x0303 means TLS 1.2. 0x0300 was SSL 3. When they introduced TLS 1.0 they chose 0x0301 and since then they just upgraded the minor version.
In order to manipulate this ModifiableVariable, we first need to know its type. In some cases it is currently non-trivial to determine the exact type, this is mostly undocumented (sorry). If you don't know the exact type of a field you currently have to look at the code. The following types and modifications are defined:
Once you have found your type you have to select a modification to apply to it. For manual analysis, the most common modifications are the XOR modification and the explicit value modification. However, during fuzzing other modifications might be useful as well. Often times you just want to flip a bit and see how the server responds, or you want to directly overwrite a value. In this example, we want to overwrite a value.
Let us force TLS-Attacker to send the version 0x3A3A. To do this I consult the ModifiableVariable README.md for the exact syntax. Since <protocolVersion> is a ModifiableByteArray I search in the ByteArray section.
I find the following snippet:
If I now want to change the value to 0x3A3A I modify my WorkflowTrace like this:
You can then execute the WorkflowTrace with:
With Wireshark you can now observe that the protocol version got actually changed. You would also see the change if you would specify a -workflow_output or if you start the TLS-Client with the -debug flag.
As you might have already seen there is so much more to talk about in TLS-Attacker. But this should give you a rough idea of what is going on.
If you have any research ideas or need support feel free to contact us on Twitter (@ic0nz1, @jurajsomorovsky ) or at https://www.hackmanit.de/.
If TLS-Attacker helps you to find a bug in a TLS implementation, please acknowledge our tool(s). If you want to learn more about TLS, Juraj and I are also giving a Training about TLS at Ruhrsec (27.05.2019).
We hope this gives you an idea on how to use the most recent version (TLS-Attacker 2.8). If you feel like you found a bug, don't hesitate to contact me via GitHub/Mail/Twitter. This post assumes that you have some idea what this is all about. If you have no idea, checkout the original paper from Juraj or our project on GitHub.
TLDR: TLS-Attacker is a framework which allows you to send arbitrary protocol flows.
Quickstart:
# Install & Use Java JDK 8
$ sudo apt-get install maven
$ git clone https://github.com/RUB-NDS/TLS-Attacker
$ cd TLS-Attacker
$ mvn clean package
So, what changed since the release of the original paper in 2016? Quite a lot! We discovered that we could make the framework much more powerful by adding some new concepts to the code which I want to show you now.
Action System
In the first Version of TLS-Attacker (1.x), WorkflowTraces looked like this:Although this design looks straight forward, it lacks flexibility. In this design, a WorkflowTrace is basically a list of messages. Each message is annotated with a <messageIssuer>, to tell TLS-Attacker that it should either try to receive this message or send it itself. If you now want to support more advanced workflows, for example for renegotiation or session resumption, TLS-Attacker will soon reach its limits. There is also a missing angle for fuzzing purposes. TLS-Attacker will by default try to use the correct parameters for the message creation, and then apply the modifications afterward. But what if we want to manipulate parameters of the connection which influence the creation of messages? This was not possible in the old version, therefore, we created our action system. With this action system, a WorkflowTrace does not only consist of a list of messages but a list of actions. The most basic actions are the Send- and ReceiveAction. These actions allow you to basically recreate the previous behavior of TLS-Attacker 1.x . Here is an example to show how the same workflow would look like in the newest TLS-Attacker version:
As you can see, the <messageIssuer> tags are gone. Instead, you now indicate with the type of action how you want to deal with the message. Another important thing: TLS-Attacker uses WorkflowTraces as an input as well as an output format. In the old version, once a WorkflowTrace was executed it was hard to see what actually happened. Especially, if you specify what messages you expect to receive. In the old version, your WorkflowTrace could change during execution. This was very confusing and we, therefore, changed the way the receiving of messages works. The ReceiveAction has a list of <expectedMessages>. You can specify what you expect the other party to do. This is mostly interesting for performance tricks (more on that in another post), but can also be used to validate that your workflow executedAsPlanned. Once you execute your ReceiveAction an additional <messages> tag will pop up in the ReceiveAction to show you what has actually been observed. Your original WorkflowTrace stays intact.
During the execution, TLS-Attacker will execute the actions one after the other. There are specific configuration options with which you can control what TLS-Attacker should do in the case of an error. By default, TLS-Attacker will never stop, and just execute whatever is next.
Configs
As you might have seen the <messageIssuer> tags are not the only thing which is missing. Additionally, the cipher suites, compression algorithms, point formats, and supported curves are missing. This is no coincidence. A big change in TLS-Attacker 2.x is the separation of the WorkflowTrace from the parameter configuration and the context. To explain how this works I have to talk about how the new TLS-Attacker version creates messages. Per default, the WorkflowTrace does not contain the actual contents of the messages. But let us step into TLS-Attackers point of view. For example, what should TLS-Attacker do with the following WorkflowTrace:Usually, the RSAClientKeyExchange message is constructed with the public key from the received certificate message. But in this WorkflowTrace, we did not receive a certificate message yet. So what public key are we supposed to use? The previous version had "some" key hardcoded. The new version does not have these default values hardcoded but allows you as the user to define the default values for missing values, or how our own messages should be created. For this purpose, we introduced the new concept of Configs. A Config is a file/class which you can provide to TLS-Attacker in addition to a WorkflowTrace, to define how TLS-Attacker should behave, and how TLS-Attacker should create its messages (even in the absence of needed parameters). For this purpose, TLS-Attacker has a default Config, with all the known hardcoded values. It is basically a long list of possible parameters and configuration options. We chose sane values for most things, but you might have other ideas on how to do things. You can execute a WorkflowTrace with a specific config. The provided Config will then overwrite all existing default values with your specified values. If you do not specify a certain value, the default value will be used. I will get back to how Configs work, once we played a little bit with TLS-Attacker.
TLS-Attacker ships with a few example applications (found in the "apps/" folder after you built the project). While TLS-Attacker 1.x was mostly a standalone tool, we currently see TLS-Attacker more as a library which we can use by our more sophisticated projects. The current example applications are:
- TLS-Client (A TLS-Client to execute WorkflowTraces with)
- TLS-Server (A TLS-Server to execute WorkflowTraces with)
- Attacks (We'll talk about this in another blog post)
- TLS-Forensics (We'll talk about this in another blog post)
- TLS-Mitm (We'll talk about this in another blog post)
- TraceTool (We'll talk about this in another blog post)
TLS-Client
The TLS-Client is a simple TLS-Client. Per default, it executes a handshake for the default selected cipher suite (RSA). The only mandatory parameter is the server you want to connect to (-connect).The most trivial command you can start it with is:
Note: The example tool does not like "https://" or other protocol information. Just provide a hostname and port
Depending on the host you chose your output might look like this:
or like this:
So what is going on here? Let's start with the first execution. As I already mentioned. TLS-Attacker constructs the default WorkflowTrace based on the default selected cipher suite. When you run the client, the WorkflowExecutor (part of TLS-Attacker which is responsible for the execution of a WorkflowTrace) will try to execute the handshake. For this purpose, it will first start the TCP connection.
This is what you see here:
After that, it will execute the actions specified in the default WorkflowTrace. The default WorkflowTrace looks something like this:
This is basically what you see in the console output. The first action which gets executed is the SendAction with the ClientHello.
Then, we expect to receive messages. Since we want to be an RSA handshake, we do not expect a ServerKeyExchange message, but only want a ServerHello, Certificate and a ServerHelloDone message.
We then execute the second SendAction:
and finally, we want to receive a ChangeCipherSpec and Finished Message:
In the first execution, these steps all seem to have worked. But why did they fail in the second execution? The reason is that our default Config does not only allow specify RSA cipher suites but creates ClientHello messages which also contain elliptic curve cipher suites. Depending on the server you are testing with, the server will either select and RSA cipher suite, or an elliptic curve one. This means, that the WorkflowTrace will not executeAsPlanned. The server will send an additional ECDHEServerKeyExchange. If we would look at the details of the ServerHello message we would also see that an (ephemeral) elliptic curve cipher suite is selected:
Since our WorkflowTrace is configured to send an RSAClientKeyExchange message next, it will just do that:
Note: ClientKeyExchangeMessage all have the same type field, but are implemented inside of TLS-Attacker as different messages
Since this RSAClientKeyExchange does not make a lot of sense for the server, it rejects this message with a DECODE_ERROR alert:
If we would change the Config of TLS-Attacker, we could change the way our ClientHello is constructed. If we specify only RSA cipher suites, the server has no choice but to select an RSA one (or immediately terminate the connection). We added command line flags for the most common Config changes. Let's try to change the default cipher suite to TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA:
As you can see, we now executed a complete ephemeral elliptic curve handshake. This is, because the -cipher flag changed the <defaultSelectedCiphersuite> parameter (among others) in the Config. Based on this parameter the default WorkflowTrace is constructed. If you want, you can specify multiple cipher suites at once, by seperating them with a comma.
We can do the same change by supplying TLS-Attacker with a custom Config via XML. To this we need to create a new file (I will name it config.xml) like this:
You can then load the Config with the -config flag:
For a complete reference of the supported Config options, you can check out the default_config.xml. Most Config options should be self-explanatory, for others, you might want to check where and how they are used in the code (sorry).
Now let's try to execute an arbitrary WorkflowTrace. To do this, we need to store our WorkflowTrace in a file and load it with the -workflow_input parameter. I just created the following WorkflowTrace:
As you can see I just send a ServerHello message instead of a ClientHello message at the beginning of the handshake. This should obviously never happen but let's see how the tested server reacts to this.
We can execute the workflow with the following command:
The server (correctly) responded with an UNEXPECTED_MESSAGE alert. Great!
Output parameters & Modifications
You are now familiar with the most basic concepts of TLS-Attacker, so let's dive into other things TLS-Attacker can do for you. As a TLS-Attacker user, you are sometimes interested in the actual values which are used during a WorkflowTrace execution. For this purpose, we introduced the -workflow_output flag. With this parameter, you can ask TLS-Attacker to store the executed WorkflowTrace with all its values in a file.Let's try to execute our last created WorkflowTrace, and store the output WorkflowTrace in the file out.xml:
The resulting WorkflowTrace looks like this:
As you can see, although the input WorkflowTrace was very short, the output trace is quite noisy. TLS-Attacker will display all its intermediate values and modification points (this is where the modifiable variable concept becomes interesting). You can also execute the output workflow again.
Note that at this point there is a common misunderstanding: TLS-Attacker will reset the WorkflowTrace before it executes it again. This means, it will delete all intermediate values you see in the WorkflowTrace and recompute them dynamically. This means that if you change a value within <originalValue> tags, your changes will just be ignored. If you want to influence the values TLS-Attacker uses, you either have to manipulate the Config (as already shown) or apply modifications to TLS-Attackers ModifiableVariables. The concept of ModifiableVariables is mostly unchanged to the previous version, but we will show you how to do this real quick anyway.
So let us imagine we want to manipulate a value in the WorkflowTrace using a ModifiableVariable via XML. First, we have to select a field which we want to manipulate. I will choose the protocol version field in the ServerHello message we sent. In the WorkflowTrace this looked like this:
For historical reasons, 0x0303 means TLS 1.2. 0x0300 was SSL 3. When they introduced TLS 1.0 they chose 0x0301 and since then they just upgraded the minor version.
In order to manipulate this ModifiableVariable, we first need to know its type. In some cases it is currently non-trivial to determine the exact type, this is mostly undocumented (sorry). If you don't know the exact type of a field you currently have to look at the code. The following types and modifications are defined:
- ModifiableBigInteger: add, explicitValue, shiftLeft, shiftRight, subtract, xor
- ModifiableBoolean: explicitValue, toggle
- ModifiableByteArray: delete, duplicate, explicitValue, insert, shuffle, xor
- ModifiableInteger: add, explicitValue, shiftLeft, shiftRight, subtract, xor
- ModifiableLong: add, explicitValue, subtract, xor
- ModifiableByte: add, explicitValue, subtract, xor
- ModifiableString: explicitValue
Once you have found your type you have to select a modification to apply to it. For manual analysis, the most common modifications are the XOR modification and the explicit value modification. However, during fuzzing other modifications might be useful as well. Often times you just want to flip a bit and see how the server responds, or you want to directly overwrite a value. In this example, we want to overwrite a value.
Let us force TLS-Attacker to send the version 0x3A3A. To do this I consult the ModifiableVariable README.md for the exact syntax. Since <protocolVersion> is a ModifiableByteArray I search in the ByteArray section.
I find the following snippet:
If I now want to change the value to 0x3A3A I modify my WorkflowTrace like this:
You can then execute the WorkflowTrace with:
With Wireshark you can now observe that the protocol version got actually changed. You would also see the change if you would specify a -workflow_output or if you start the TLS-Client with the -debug flag.
More Actions
As I already hinted, TLS-Attacker has more actions to offer than just a basic Send- and ReceiveAction (50+ in total). The most useful, and easiest to understand actions are now introduced:ActivateEncryptionAction
This action does basically what the CCS message does. It activates the currently "negotiated" parameters. If necessary values are missing in the context of the connection, they are drawn from the Config.DeactivateEncryptionAction
This action does the opposite. If the encryption was active, we now send unencrypted again.PrintLastHandledApplicationDataAction
Prints the last application data message either sent or received.PrintProposedExtensionsAction
Prints the proposed extensions (from the client)PrintSecretsAction
Prints the secrets (RSA) from the current connection. This includes the nonces, cipher suite, public key, modulus, premaster secret, master secret and verify data.RenegotiationAction
Resets the message digest. This is usually done if you want to perform a renegotiation.ResetConnectionAction
Closes and reopens the connection. This can be useful if you want to analyze session resumption or similar things which involve more than one handshake.SendDynamicClientKeyExchangeAction
Send a ClientKeyExchange message, and always chooses the correct one (depending on the current connection state). This is useful if you just don't care about the actual cipher suite and just want the handshake done.SendDynamicServerKeyExchangeAction
(Maybe) sends a ServerKeyExchange message. This depends on the currently selected cipher suite. If the cipher suite requires the transmission of a ServerKeyExchange message, then a ServerKeyExchange message will be sent, otherwise, nothing is done. This is useful if you just don't care about the actual cipher suite and just want the handshake done.WaitAction
This lets TLS-Attacker sleep for a specified amount of time (in ms).
As you might have already seen there is so much more to talk about in TLS-Attacker. But this should give you a rough idea of what is going on.
If you have any research ideas or need support feel free to contact us on Twitter (@ic0nz1, @jurajsomorovsky ) or at https://www.hackmanit.de/.
If TLS-Attacker helps you to find a bug in a TLS implementation, please acknowledge our tool(s). If you want to learn more about TLS, Juraj and I are also giving a Training about TLS at Ruhrsec (27.05.2019).
More information
