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
The quick start guide is showing you how to use TLS-Anvil to test a TLS server or client. This is basically a two step process. First TLS-Anvil is executed to perform the tests against the OpenSSL example server and client. TLS-Anvil as well as the OpenSSL server/client will run inside a Docker container. The TLS server/client images are provided by the TLS-Docker-Library project which we released alongside TLS-Anvil.
3
+
The quick start guide is showing you how to use TLS-Anvil to test a TLS server or client.
4
+
This is basically a two step process.
4
5
5
-
The second step is to analyze the results. Those are going to be imported into a web application that visualizes the results for each test case. The application is also able to inspect every connection between TLS-Anvil and the tested target at TCP message level.
6
+
First TLS-Anvil is executed to perform the tests against the OpenSSL example server and client.
7
+
We will use OpenSSL as an example implementation here.
8
+
TLS-Anvil as well as the OpenSSL server/client will run inside a Docker container.
9
+
The OpenSSL server/client images are provided by the TLS-Docker-Library project which we released alongside TLS-Anvil.
10
+
So see how you can test against other implementations that are inside the TLS-Docker-Library see [Using the TLS-Docker-Library](/docs/Docker-Library).
11
+
12
+
The second step is to analyze the results.
13
+
Those are going to be imported into a web application that visualizes the results for each test case.
14
+
The application is also able to inspect every connection between TLS-Anvil and the tested target at TCP message level.
6
15
7
16
### Requirements
8
17
9
18
- Docker
10
-
- Python (for using TLS-Docker-Library)
19
+
- Python *(optional, for using TLS-Docker-Library to test other implementations)*
11
20
12
-
### GitHub Repos
21
+
### GitHub Repositories
13
22
14
-
- TLS-Anvil (Testsuite)
15
-
- TLS-Docker-Library(optional, for test server and clients)
16
-
- Anvil-Web(optional, for a graphical user interface)
Copy file name to clipboardExpand all lines: Docs/docs/01-Quick-Start/01-Server-Testing.md
+28-14Lines changed: 28 additions & 14 deletions
Original file line number
Diff line number
Diff line change
@@ -1,28 +1,36 @@
1
1
# Server Testing
2
2
3
-
This site demonstrates how to test the OpenSSL server provided by the TLS-Docker-Library.
4
-
Testing the server in the most simple form roughly takes around 10 minutes. However, this duration can increase to several depending on the strength parameter that that basically defines how often a single test case triggered with different parameters.
3
+
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.
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.
5
8
6
9
### Preparations
7
10
8
-
The server we will use, is found in the [TLS-Docker-Library](https://github.com/tls-attacker/tls-docker-library).
11
+
:::info
9
12
10
-
Before the server is able to do anything we need to generate a TLS certificate. Inside the TLS-Docker-Library repo, run:
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.
11
15
12
-
```bash
13
-
./setup.sh
14
-
```
16
+
:::
15
17
16
-
Next we create a dedicated docker network that is used by the TLS-Anvil and OpenSSL server container to communicate with each other.
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.
17
19
18
20
```bash
19
21
docker network create tls-anvil
20
22
```
21
23
22
24
### Starting the OpenSSL Server
23
25
26
+
:::info
27
+
24
28
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.
25
29
30
+
:::
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.
33
+
26
34
```bash showLineNumbers
27
35
docker run \
28
36
-d \
@@ -42,7 +50,7 @@ docker run \
42
50
43
51
### Starting TLS-Anvil
44
52
45
-
Finally TLS-Anvil is started. The current directory is mounted to the docker container and used to store the results.
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.
46
54
47
55
```bash showLineNumbers
48
56
docker run \
@@ -52,6 +60,7 @@ docker run \
52
60
--network tls-anvil \
53
61
-v $(pwd):/output/ \
54
62
ghcr.io/tls-attacker/tlsanvil:latest \
63
+
-zip \
55
64
-parallelHandshakes 1 \
56
65
-connectionTimeout 200 \
57
66
-strength 1 \
@@ -63,8 +72,13 @@ docker run \
63
72
* Lines 2-5: Docker related command flags
64
73
* Line 6: Set the output directory through a docker volume
65
74
* Line 7: Specifies the TLS-Anvil docker image
66
-
* Line 8: Since the OpenSSL example server is single threaded, we can only perform one handshakes sequentially
67
-
* Line 9: We run our server locally, so we can reduce the timeout to 200ms.
68
-
* Line 10: Defines the strength, i.e. the `t` for t-way combinatorial testing
69
-
* Line 12: We want to test a server
70
-
* Line 13: Determines the details how TLS-Anvil should connect to the server
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 `TestSuiteResults_...` which contains all the results.
84
+
To analyze them, go to [Viewing Results](Anvil-Web).
Copy file name to clipboardExpand all lines: Docs/docs/01-Quick-Start/02-Client-Testing.md
+27-9Lines changed: 27 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,14 @@
1
1
# Client Testing
2
2
3
3
This site demonstrates how to test the OpenSSL client provided by the TLS-Docker-Library.
4
-
Testing the client in the most simple form roughly takes around 15 minutes. However, this duration can increase to several depending on the strength parameter that that basically defines how often a single test case triggered with different parameters.
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.
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.
5
8
6
9
### Preparations
7
10
8
-
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.
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.
9
12
10
13
```bash
11
14
docker network create tls-anvil
@@ -14,6 +17,7 @@ docker network create tls-anvil
14
17
### Starting the TLS-Anvil container
15
18
16
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.
17
21
18
22
```bash showLineNumbers
19
23
docker run \
@@ -23,6 +27,7 @@ docker run \
23
27
--name tls-anvil \
24
28
-v $(pwd):/output/ \
25
29
ghcr.io/tls-attacker/tlsanvil:latest \
30
+
-zip \
26
31
-parallelHandshakes 3 \
27
32
-parallelTests 3 \
28
33
-strength 1 \
@@ -35,19 +40,28 @@ docker run \
35
40
* Lines 2-5: Docker related command flags
36
41
* Line 6: Set the output directory through a docker volume
37
42
* Line 7: Specifies the TLS-Anvil docker image
38
-
* Lines 8-9: Since the client can started multiple times, TLS-Anvil can run multiple tests and handshakes in parallel
39
-
* Line 10: Defines the strength, i.e. the `t` for t-way combinatorial testing
40
-
* Line 11: Defines an arbitrary name that is written to the report
41
-
* Line 12: We want to test a client
42
-
* Line 13: The port on which TLS-Anvil listens to accept requests from the client
43
-
* Line 14: Specifies a script that is executed before each handshake, which the goal to trigger a connection from the client. See below how this works.
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.
44
50
45
51
### Starting the OpenSSL client container
46
52
47
-
The OpenSSL client image is provided by the TLS-Docker-Library. The entrypoint of the client images is a small HTTP server that provides two REST-API endpoints on port 8090.
53
+
:::info
54
+
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.
48
57
*`GET /trigger` starts the client
49
58
*`GET /shutdown` shutdown the HTTP server to terminate the container
50
59
60
+
:::
61
+
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.
64
+
51
65
```bash showLineNumbers
52
66
docker run \
53
67
-d \
@@ -61,3 +75,7 @@ docker run \
61
75
* Lines 2-5: Docker related command flags
62
76
* Line 6: Specifies the OpenSSL client image from the TLS-Docker-Library
63
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`.
78
+
79
+
### What now?
80
+
After the testsuite finished you should see a folder named `TestSuiteResults_...` which contains all the results.
Copy file name to clipboardExpand all lines: Docs/docs/01-Quick-Start/03-Anvil-Web.md
+7-4Lines changed: 7 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -3,22 +3,24 @@ import Definition from '@site/src/components/Definition';
3
3
4
4
# Viewing Results
5
5
6
-
TLS-Anvil stores the test results in multiple `json` files. In addition the network traffic is captured during the execution. Since analyzing those files by hand is tedious, we created a small web application to get the job done.
6
+
TLS-Anvil stores the test results in multiple `json` files. In addition the network traffic is captured during the execution. Since analyzing those files by hand is tedious, we created a web application called **Anvil-Web** to get the job done.
7
7
8
-
The result analyzer application is also shipped as docker container. Since a database is required, `docker-compose` is the easiest way to start the application. The `docker-compose.yml` file is part the [Anvil-Web GitHub Repo](https://github.com/tls-attacker/Anvil-Web).
8
+
The result analyzer application is also shipped as docker container. Since a database is required, `dockercompose` is the easiest way to start the application. The `docker-compose.yml` file is part the [Anvil-Web GitHub Repo](https://github.com/tls-attacker/Anvil-Web).
Download the file `docker-compose.yml` and in the same directory as the downloaded file, execute the following commands.
16
+
This will download prebuilt images of Anvil-Web and start a webserver.
15
17
16
18
```bash
17
19
docker compose pull
18
20
docker compose up -d
19
21
```
20
22
21
-
The application should be available at [http://localhost:5001](http://localhost:5001).
23
+
The application should then be available at [http://localhost:5001](http://localhost:5001).
22
24
23
25
:::info
24
26
@@ -33,13 +35,14 @@ Below, you can find a short description of the core principles.
33
35
34
36
Next the results need to be imported, i.e. importing the JSON files of TLS-Anvil into a MongoDB that is accessed by the backend of the web application.
35
37
The easiest way to do that is to zip your results folder (the folder that contains the report.json file) and upload it in the web-interface.
38
+
If you used the `-zip` flag during the execution, a zip file ready to upload should already be inside the results folder.
36
39
Just go to `Tests` -> `Upload Test` and select the zip file.
37
40
38
41
### Using the application
39
42
40
43
1. Open your web browser at [http://localhost:5001](http://localhost:5001).
41
44
2. Click `Tests` in the navbar (if not already selected) and look for the test you just uploaded. Here you can click on `Details`.
42
-
3. You will see an overview over the testresults. The specific result for each <Definitionid="test template"/> is presented in the table at the bottom, sorted by RFC.
45
+
3. You will see an overview over the test results. The specific result for each <Definitionid="test template"/> is presented in the table at the bottom, sorted by RFC.
43
46
4. The table rows are clickable, if you do, a detailed view will be presented to you showing what exactly got tested in that run and the results for each <Definitionid="test input"/>, i.e. each performed handshake.
44
47
1. Click on a row of a test case to view the recorded PCAP dump for the handshake as well as additional information about the handshake. `Parameter Combination`, for example, shows the <Definitionid="test input"/> for the test case, generated by the combinatorial testing algorithm.
The [TLS-Docker-Library](https://github.com/tls-attacker/Tls-docker-library) is a set of Dockerfiles and scripts for building and running many different TLS implementations.
4
+
It can be used to test example server and client implementations of various TLS libraries.
5
+
6
+
You can follow the README file of the repository to learn, how to build the docker containers yourself.
7
+
8
+
In short, you need to
9
+
- run `./setup.sh` to generate the base images and certificates
10
+
- go to `cd src/main/resources/images`
11
+
- run `python3 build.py -l image-name:version` with the name of the implementation as well as the version you would like to build
12
+
- if you would like to build the newest version use `:latest`
13
+
14
+
## Testing Built Library Containers using TLS-Anvil
15
+
Once you built an image of a library you'd like to test, we have to create and start the container and then connect it to TLS-Anvil.
16
+
17
+
This procedure differs between server and client images.
18
+
19
+
To see how to create and run a container of your desired implementation, go to the subfolder of that implementation where you will find a readme file with more infos.
20
+
21
+
### Server Images
22
+
Server images almost always just start a binary server example implementation of that library in a loop.
23
+
24
+
The arguments you pass to the docker container after the image name will get passed to the server executable. E.g. the image `openssl-server:1.1.1i` has the entrypoint `openssl s_server`. Any arguments that you pass after `docker run openssl-server:1.1.1i ...` are passed to the openssl executable.
25
+
26
+
Many of the server implementations need certificates. Many certificates were created when you ran `./setup.sh`. Those are stored in the docker volume `cert-data` and can be used with any image.
27
+
28
+
E.g. to start an OpenSSL server with an RSA certificate we can use:
The `-v` option bind the `cert-data` volume to the container at the location `/certs/`.
33
+
34
+
The server is now listening on port 8443, but since it is a container, the port is only accessible from inside the container. To be able to connect to it we have to:
35
+
- add the server container and TLS-Anvil container to the same docker network (like in our [example](/docs/Quick-Start/Server-Testing))
36
+
- expose the port using `-p 8443:8443` or
37
+
- add the docker container to the host network using `--network host`
38
+
39
+
If you added it to a network, the server will be reachable with its container name (can be changed by using `--name ...`), or via the other options, it should be reachable via `localhost:8443`.
40
+
This is, what you will need to input in the `-connect ...` parameter of TLS-Anvil.
41
+
42
+
### Client Images
43
+
Client images implement a small web server that listens on port 8090. Command line arguments that you pass behind the image name also get passed directly to the client executable. But the client executable is not running in a loop, but rather only started when a GET request is sent to the `/trigger` endpoint of the webserver.
44
+
45
+
E.g. to start the OpenSSL client, we can run `docker run openssl-client:1.1.1i -connect localhost:8443` and the `-connect ...` part is directly passed to `openssl s_client`.
46
+
47
+
You have to make sure, that TLS-Anvil can reach the webserver (port 8090) of the client image, and the client can reach TLS-Anvil to connect to. This can be done by either:
48
+
- adding the client container and TLS-Anvil container to the same docker network (like in our [example](/docs/Quick-Start/Client-Testing))
49
+
- the client can then connect to TLS-Anvil using its container name
50
+
- TLS-Anvil can connect to the client using its container name
51
+
- exposing port the port 8090 on the client using `-p 8090:8090` and exposing the server listening port on the TLS-Anvil container if also run via docker
52
+
- the client can then connect to TLS-Anvil using the ip `172.17.0.1` or `host.docker.internal`
53
+
- TLS-Anvil can reach the container using `172.17.0.1` or `host.docker.internal` if also run in a container or `localhost` if run in the host
54
+
- adding the client (and TLS-Anvil) to the host network using `--network host`
55
+
- the client can then connect to TLS-Anvil using `localhost`
56
+
- TLS-Anvil can also connect to the client using `localhost`
57
+
58
+
TLS-Anvil uses a *trigger script* in the client testing mode. The script is called every time it wants the client to connect to it. Using the TLS-Docker-Library images you almost always want to use `curl` in the trigger script to connect to the `/trigger` endpoint of the client.
59
+
60
+
An example would be `docker run --network host -v $(pwd):/output/ ghcr.io/tls-attacker/tlsanvil:latest client -port 8443 -triggerScript curl localhost:8090/trigger`.
61
+
62
+
:::info
63
+
64
+
You could also execute a binary of a client implementation directly in the `-triggerScript` parameter.
0 commit comments