You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Welcome to TLS-Anvil, our test suite for (D)TLS 1.2 and 1.3 servers and clients. TLS-Anvil currently includes around 400 test cases that are based on requirements derived from various TLS related RFCs listed below as well as attacks from the past. The tests are implemented in Java using JUnit, coffee4j and TLS-Attacker and aim to detect violations of the TLS specification by TLS servers or clients.
3
+
Welcome to **TLS-Anvil**, our comprehensive test suite for testing (D)TLS 1.2 and 1.3 servers and clients.
4
+
TLS-Anvil currently includes approximately 400 test cases based on requirements derived from various TLS-related RFCs, as well as from known past attacks.
4
5
5
-
**RFCs covered by tests:**
6
-
*[RFC 5246](https://datatracker.ietf.org/doc/html/rfc5246) - The Transport Layer Security (TLS) Protocol Version 1.2
7
-
*[RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446) - The Transport Layer Security (TLS) Protocol Version 1.3
8
-
*[RFC 8701](https://datatracker.ietf.org/doc/html/rfc8701) - Applying Generate Random Extensions And Sustain Extensibility (GREASE) to TLS Extensibility
9
-
*[RFC 7507](https://datatracker.ietf.org/doc/html/rfc7507) - TLS Fallback Signaling Cipher Suite Value (SCSV) for Preventing Protocol Downgrade Attacks
10
-
*[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066) - Transport Layer Security (TLS) Extensions: Extension Definitions
11
-
*[RFC 7568](https://datatracker.ietf.org/doc/html/rfc7568) - Deprecating Secure Sockets Layer Version 3.0
12
-
*[RFC 7919](https://datatracker.ietf.org/doc/html/rfc7919) - Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer Security (TLS)
*[RFC 7366](https://datatracker.ietf.org/doc/html/rfc7366) - Encrypt-then-MAC for Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)
15
-
*[RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422) - Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS) Versions 1.2 and Earlier
16
-
*[RFC 7685](https://datatracker.ietf.org/doc/html/rfc7685) - A Transport Layer Security (TLS) ClientHello Padding Extension
17
-
*[RFC 6176](https://datatracker.ietf.org/doc/html/rfc6176) - Prohibiting Secure Sockets Layer (SSL) Version 2.0
18
-
*[RFC 7457](https://datatracker.ietf.org/doc/html/rfc7457) - Summarizing Known Attacks on Transport Layer Security (TLS) and Datagram TLS (DTLS)
19
-
*[RFC 6347](https://datatracker.ietf.org/doc/html/rfc6347) - Datagram Transport Layer Security Version 1.2
6
+
The tests are implemented in Java using **JUnit**, **coffee4j**, and **TLS-Attacker**, and are designed to detect deviations from the TLS specification in both servers and clients.
7
+
8
+
---
9
+
10
+
### RFCs Covered by the Test Suite
11
+
12
+
*[RFC 5246](https://datatracker.ietf.org/doc/html/rfc5246) — The Transport Layer Security (TLS) Protocol Version 1.2
13
+
*[RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446) — The Transport Layer Security (TLS) Protocol Version 1.3
14
+
*[RFC 8701](https://datatracker.ietf.org/doc/html/rfc8701) — Applying Generate Random Extensions And Sustain Extensibility (GREASE) to TLS Extensibility
15
+
*[RFC 7507](https://datatracker.ietf.org/doc/html/rfc7507) — TLS Fallback Signaling Cipher Suite Value (SCSV) for Preventing Protocol Downgrade Attacks
This site demonstrates how to test an OpenSSL server provided by the TLS-Docker-Library.
4
-
You can of course also test other implementations, for example by [using the TLS-Docker-Library](/docs/Docker-Library) or by running your own server binary.
3
+
This site demonstrates how to test an OpenSSL server provided by the TLS-Docker-Library.
4
+
You can also test other implementations, for example by [using the TLS-Docker-Library](/docs/Docker-Library) or by running your own server binary.
5
5
6
-
Testing the server in the most simple form roughly takes around 10-20 minutes.
7
-
However, this duration can increase to several depending on the strength parameter that basically defines how often a single test case is performed with different parameters.
6
+
Testing the server in its simplest form typically takes around 10-20 minutes.
7
+
However, this duration may increase to several hours depending on the strength parameter, which defines how many times each test case is executed with varying parameters.
8
8
9
9
### Preparations
10
10
11
11
:::info
12
12
13
-
The server image we will use, is prebuilt by us using the [TLS-Docker-Library](https://github.com/tls-attacker/tls-docker-library).
14
-
We included certificates in the container, so that you do not have to generate them yourself.
13
+
The server image we use is prebuilt by us using the [TLS-Docker-Library](https://github.com/tls-attacker/tls-docker-library).
14
+
We have included certificates in the container, so you do not need to generate them yourself.
15
15
16
16
:::
17
17
18
-
For better compatibility, we create a dedicated docker network that is used by TLS-Anvil and the OpenSSL server container to communicate with each other.
18
+
For better compatibility, we create a dedicated Docker network that allows TLS-Anvil and the OpenSSL server container to communicate.
As mentioned before, we use OpenSSL as an example. In this case the server uses an RSA certificate. However, TLS-Anvil works with any certificate and automatically adapts the tests to the given circumstances.
28
+
As mentioned before, we use OpenSSL as an example. In this case, the server uses an RSA certificate. However, TLS-Anvil supports any certificate type and automatically adapts the tests accordingly.
29
29
30
30
:::
31
31
32
-
Starting the server can be done with the following command. This will download a pre-built image from our GitHub registry, and run it.
32
+
Start the server with the following command. This will download a pre-built image from our GitHub registry and run it.
33
33
34
34
```bash showLineNumbers
35
35
docker run \
36
36
-d \
37
37
--rm \
38
38
--name openssl-server \
39
39
--network tls-anvil \
40
-
-v cert-data:/certs/ \
41
40
ghcr.io/tls-attacker/openssl-server:1.1.1i \
42
41
-port 8443 \
43
42
-cert /certs/rsa2048cert.pem \
44
43
-key /certs/rsa2048key.pem
45
44
```
46
45
47
-
* Lines 2-6: Dockerrelated command flags
48
-
* Line 7: Specifies the Docker image from the TLS-Docker-Library
49
-
* Lines 8-10: Those flags are passed to the OpenSSL `s_server` binary
46
+
* Lines 2-5: Docker-related command flags
47
+
* Line 6: Specifies the Docker image from the TLS-Docker-Library
48
+
* Lines 7-9: Flags passed to the OpenSSL `s_server` binary
50
49
51
50
### Starting TLS-Anvil
52
51
53
-
After that, TLS-Anvil is started. The current directory is mounted to the docker container and used to store the results. We connect to the server using its docker hostname `openssl-server`, which is possible since they are on the same docker network.
52
+
Next, start TLS-Anvil. The current directory is mounted into the Docker container to store the results. We connect to the server using its Docker hostname `openssl-server`, which works because both containers are on the same Docker network.
54
53
55
54
```bash showLineNumbers
56
55
docker run \
@@ -69,16 +68,17 @@ docker run \
69
68
-connect openssl-server:8443
70
69
```
71
70
72
-
* Lines 2-5: Docker related command flags
73
-
* Line 6: Set the output directory through a docker volume
74
-
* Line 7: Specifies the TLS-Anvil docker image
75
-
* Line 8: Zip the results, that way we can easily import them into Anvil-Web later
76
-
* Line 9: Since the OpenSSL example server is single threaded, we can only perform one handshakes sequentially
77
-
* Line 10: We run our server locally, so we can reduce the timeout to 200ms.
78
-
* Line 11: Defines the strength, i.e. the `t` for t-way combinatorial testing
79
-
* Line 13: We want to test a server
80
-
* Line 14: Determines the details how TLS-Anvil should connect to the server
81
-
82
-
### What now?
83
-
After the testsuite finished you should see a folder named `Results_...` which contains all the results.
84
-
To analyze them, go to [Viewing Results](Anvil-Web).
71
+
* Lines 2-5: Docker-related command flags
72
+
* Line 6: Mounts the output directory as a Docker volume
73
+
* Line 7: Specifies the TLS-Anvil Docker image
74
+
* Line 8: Compresses the results into a zip archive for easier import into Anvil-Web later
75
+
* Line 9: Since the OpenSSL example server is single-threaded, only one handshake is performed sequentially
76
+
* Line 10: The server runs locally, so the connection timeout is set to 200 ms
77
+
* Line 11: Sets the strength parameter, i.e., the `t` value for t-way combinatorial testing
78
+
* Line 13: Specifies that we want to test a server
79
+
* Line 14: Details how TLS-Anvil should connect to the server
80
+
81
+
### What Now?
82
+
83
+
After the test suite finishes, you should see a folder named `Results_...` containing all the results.
84
+
To analyze them, refer to [Viewing Results](Anvil-Web).
This site demonstrates how to test the OpenSSL client provided by the TLS-Docker-Library.
4
-
You can of course also test other implementations, for example by [using the TLS-Docker-Library](/docs/Docker-Library) or by running your own client binary.
3
+
This page demonstrates how to test the OpenSSL client using the TLS-Docker-Library.
4
+
You can also test other implementations—for example, by [using the TLS-Docker-Library](/docs/Docker-Library) or by running your own client binary.
5
5
6
-
Testing the client in the most simple form roughly takes around 15 minutes.
7
-
However, this duration can increase to several depending on the strength parameter that basically defines how often a single test case is performed with different parameters.
6
+
Running the test suite in its simplest form typically takes around 15 minutes.
7
+
However, the duration may increase depending on the `strength` parameter, which defines how many variations of a single test case are executed with different parameters.
8
8
9
9
### Preparations
10
10
11
-
Similar to the server test we first create a dedicated docker network that is used by the TLS-Anvil and OpenSSL client container to communicate with each other. If it is already created, no need to recreate it.
11
+
Just like with server testing, we first create a dedicated Docker network that allows the TLS-Anvil and OpenSSL client containers to communicate.
12
+
If the network has already been created, you can skip this step.
12
13
13
14
```bash
14
15
docker network create tls-anvil
15
16
```
16
17
17
-
### Starting the TLS-Anvil container
18
+
### Starting the TLS-Anvil Container
18
19
19
-
Since the client has to connect to TLS-Anvil the test suite container is started first.
20
-
After starting, the testsuite is waiting for the client to connect, so leave the terminal open.
20
+
Since the client needs to connect to TLS-Anvil, the test suite container must be started first.
21
+
Once running, the test suite will wait for the client to connect, so keep the terminal open.
* Line 6: Set the output directory through a docker volume
42
-
* Line 7: Specifies the TLS-Anvil docker image
43
-
* Line 8: Zip the results, that way we can easily import them into Anvil-Web later
44
-
* Lines 9-10: Since the client can started multiple times, TLS-Anvil can run multiple tests and handshakes in parallel
45
-
* Line 11: Defines the strength, i.e. the `t` for t-way combinatorial testing
46
-
* Line 12: Defines an arbitrary name that is written to the report
47
-
* Line 13: We want to test a client
48
-
* Line 14: The port on which TLS-Anvil listens to accept requests from the client
49
-
* Line 15: Specifies a script that is executed before each handshake, which the goal to trigger a connection from the client. See below how this works.
41
+
* Lines 2–5: Docker-related command flags
42
+
* Line 6: Mounts the current directory as the output directory
43
+
* Line 7: Specifies the TLS-Anvil Docker image
44
+
* Line 8: Compresses the results into a ZIP file for easier import into Anvil-Web
45
+
* Lines 9–10: TLS-Anvil can run multiple tests and handshakes in parallel since the client can be started multiple times
46
+
* Line 11: Sets the `strength` parameter for t-way combinatorial testing
47
+
* Line 12: Defines an identifier name that appears in the test report
48
+
* Line 13: Indicates that we are testing a client
49
+
* Line 14: Specifies the port TLS-Anvil listens on for client connections
50
+
* Line 15: Provides a script that is executed before each handshaketo trigger a new client connection. See explanation below.
50
51
51
-
### Starting the OpenSSL client container
52
+
### Starting the OpenSSL Client Container
52
53
53
54
:::info
54
55
55
-
As mentioned before, we use OpenSSL as an example.
56
-
The OpenSSL client image in this example is prebuilt using the [TLS-Docker-Library](https://github.com/tls-attacker/tls-docker-library). The entrypoint of the client images is a small HTTP server that provides two REST-API endpoints on port 8090.
57
-
*`GET /trigger` starts the client
58
-
*`GET /shutdown` shutdown the HTTP server to terminate the container
56
+
As mentioned, we use OpenSSL as an example client.
57
+
The OpenSSL client image used here is pre-built using the [TLS-Docker-Library](https://github.com/tls-attacker/tls-docker-library).
58
+
Its entrypoint is a small HTTP server that exposes two REST API endpoints on port 8090:
59
+
60
+
-`GET /trigger` — starts the client
61
+
-`GET /shutdown` — shuts down the HTTP server and terminates the container
59
62
60
63
:::
61
64
62
-
Starting the client can be done with the following command. This will download a pre-built image from our GitHub registry, and run it.
63
-
Since TLS-Anvil is already running, open another terminal to start the client.
65
+
Start the client using the following command. This downloads a pre-built image from our GitHub Container Registry and runs it.
66
+
Since TLS-Anvil is already running, open a new terminal to start the client.
64
67
65
68
```bash showLineNumbers
66
69
docker run \
@@ -72,10 +75,11 @@ docker run \
72
75
-connect tls-anvil:8443
73
76
```
74
77
75
-
* Lines 2-5: Dockerrelated command flags
78
+
* Lines 2–5: Docker-related command flags
76
79
* Line 6: Specifies the OpenSSL client image from the TLS-Docker-Library
77
-
* Line 7: This is passed to the OpenSSL `s_client` binary, which is started each time a HTTP-GET request is sent to `:8090/trigger`.
80
+
* Line 7: This argument is passed to the OpenSSL `s_client` binary, which is executed each time a `GET /trigger` request is sent to port 8090
81
+
82
+
### What Now?
78
83
79
-
### What now?
80
-
After the testsuite finished you should see a folder named `Results_...` which contains all the results.
81
-
To analyze them, go to the next page.
84
+
After the test suite finishes, a folder named `Results_...` will appear in your working directory.
85
+
This folder contains all the test results. To analyze them, proceed to the next page.
0 commit comments