add getting started guide (#321)

* docs: add getting-started guide
* docs: build with ASAN in getting-started guide
* docs: fix OpenSSL build path in getting-started guide
* docs: fix typos in getting-started guide

docs/docs/guides/getting-started/building-openssl.md

@@ -2,10 +2,28 @@
 title: 'Building OpenSSL'
 ---
 
-:::warning[Ongoing Work]
+## Building Preconfigured Targets
 
-This page is currently under development. Information presented here might be incomplete or outdated.
+*tlspuffin* comes with several preconfigured fuzz targets and a wrapper script *mk_vendor* to simplify the build process:
+
+```sh
+./tools/mk_vendor make openssl:openssl312 --options=sancov,asan --name=openssl312-sancov-asan
+```
+
+This command will fetch the sources for OpenSSL 3.1.2 and build it with Clang's [SanitizerCoverage](https://clang.llvm.org/docs/SanitizerCoverage.html) activated.
+
+:::tip[Want to try another target?]
+
+For the complete list of preconfigured targets, you can look at our [support matrix](../../references/support-matrix).
 
 :::
 
-# OpenSSL
+## Checking The Build Result
+
+By default, *mk_vendor* will store the result of the build process in a subfolder of the `vendor/` folder at the project's root. In our case:
+
+```sh
+ls -al ./vendor/openssl312-sancov-asan
+```
+
+This folder is a standard install prefix containing, most notably, the `include` and `lib` folders that will allow *tlspuffin* to link against the fuzz target.

docs/docs/guides/getting-started/fuzzing-openssl.md

@@ -2,10 +2,37 @@
 title: 'Fuzzing OpenSSL'
 ---
 
-:::warning[Ongoing Work]
+## Building the Fuzzer
 
-This page is currently under development. Information presented here might be incomplete or outdated.
+Now that we have the OpenSSL library to serve as a fuzz target, we can create the corresponding fuzzer:
+```sh
+cargo build --release --bin=tlspuffin --features=openssl312,sancov,asan
+```
 
-:::
+By setting `--features=openssl312,sancov,asan`, the build process will automatically select the fuzz target located in `./vendor/openssl312-sancov-asan`.
+The build process creates the fuzzer at `./target/release/tlspuffin`.
+
+## Generating Seeds
+
+*tlspuffin* comes with a set of standard seeds for TLS (handshake, session resumption, ...) that can serve as the initial corpus for the fuzzing process, rather than letting the fuzzer rediscover the details of the TLS protocol.
+
+You can generate the seeds compatible with the selected fuzz target in the `./seeds` folder by running:
+```sh
+./target/release/tlspuffin seed
+```
+
+## Running the Fuzzer
 
-# Fuzzing OpenSSL
+Now we are finally ready to launch the fuzzer:
+```sh
+./target/release/tlspuffin --cores=0-3 --tui quick-experiment
+```
+
+This creates a folder `experiments/<id>` containing the results of the fuzzing run.
+In particular, the folder `experiments/<id>/corpus` will store the corpus found during the fuzzing session.
+
+:::tip[What are these .trace files in my corpus folder?]
+
+Because *tlspuffin* works at a higher level of abstraction compared to generic fuzzers, the corpus files are not raw inputs for a binary but rather traces of the protocol session between different agents. More details in the next section!
+
+:::

docs/docs/guides/getting-started/installation.md

@@ -4,19 +4,23 @@ title: 'Installation'
 
 ## Before you start
 
-`tlspuffin` relies on [Nix](https://nixos.org/) to setup an environment with all the necessary dependencies and to provide a consistent development experience. This guide will leverage Nix to simplify the install process and **we strongly encourage you to setup Nix** on your machine as a pre-requisite. If you are new to Nix, we recommend using the [Zero to Nix install guide](https://zero-to-nix.com/start/install).
+*tlspuffin* relies on [Nix](https://nixos.org/) to set up an environment with all the necessary dependencies and to provide a consistent development experience. This guide will leverage Nix to simplify the installation process and **we strongly encourage you to set up Nix** on your machine as a pre-requisite. If you are new to Nix, we recommend using the [Zero to Nix install guide](https://zero-to-nix.com/start/install).
 
-Otherwise, you can manually install the dependencies listed in the repository's [README](https://github.com/tlspuffin/tlspuffin?tab=readme-ov-file#dependencies) file, as well as the dependencies for building the OpenSSL fuzz target used in this guide.
+Otherwise, you can manually install the dependencies listed in the repository's [README](https://github.com/tlspuffin/tlspuffin?tab=readme-ov-file#dependencies) file as well as the dependencies for building the OpenSSL fuzz target used in this guide.
 
 ## Install
 
 Download the latest sources of tlspuffin:
 ```sh
 git clone https://github.com/tlspuffin/tlspuffin
+```
+
+Note that all the subsequent commands in this guide should be run from the root `tlspuffin` folder that was just downloaded through git:
+```sh
 cd tlspuffin
 ```
 
-Setup all the dependencies and tools using the provided nix shell environment:
+The provided nix shell environment will provide all the dependencies and tools necessary for this guide:
 ```sh
 nix-shell
 ```

docs/docs/guides/getting-started/introduction.md

@@ -2,23 +2,16 @@
 title: 'Introduction'
 ---
 
-:::warning[Ongoing Work]
-
-This Guide is currently under development. Information presented here might be incomplete or outdated.
-
-:::
-
-
 :::note[TL;DR]
 
-This guide will navigate you through all the steps to setup a first fuzzer with `tlspuffin`.
-If you just want to quickly get a running fuzzer you can try our [Quickstart Guide](../quickstart)!
+This guide will navigate you through all the steps to set up a first fuzzer with *tlspuffin*.
+If you just want to quickly get a running fuzzer, you can try our [Quickstart Guide](../quickstart)!
 
 :::
 
-This guide will help you create your first fuzzer with `tlspuffin`, including:
+This guide will help you create your first fuzzer with *tlspuffin*, including:
 
 - install the necessary tools
-- build one of the pre-configured OpenSSL fuzz target
-- build a fuzzer for the fuzz target
+- build one of the pre-configured OpenSSL fuzz targets
+- build a fuzzer for the selected fuzz target
 - run the fuzzer and check the results

docs/docs/guides/getting-started/replaying-traces.md

@@ -0,0 +1,43 @@
+---
+title: 'Replaying Traces'
+---
+
+*tlspuffin* creates fuzzing inputs using high-level protocol abstractions.
+Such an input is a *trace* of the messages sent to the different *agents*.
+Unlike standard fuzzers that can simply submit the generated inputs to the program under tests, executing a trace is a more involved process, including:
+- spawning the network agents involved in the trace
+- building protocol messages
+- transferring messages to agents
+- reading and parsing the outputs generated by the agents
+
+Therefore, *tlspuffin* provides the ability to store all these steps in a `.trace` file and execute them on demand.
+
+## Executing a Trace
+
+Through the *tlspuffin* CLI, the `execute` command provides a simple way to execute a trace:
+```sh
+./target/debug/tlspuffin execute 'seeds/tlspuffin::tls::seeds::seed_successful.trace'
+```
+
+:::note[Trace Validity]
+
+Not all traces are *valid* traces in the sense of the protocol under test.
+In particular, while fuzzing it is likely to generate invalid traces due to malformed or out-of-order messages.
+When trying to execute an invalid trace, the `execute` command will signal whether the execution finished successfully and provide hints about the error encountered in case of failure.
+
+:::
+
+## Replaying Against a Real Entity
+
+While it is useful to let *tlspuffin* spawn the agents involved in a trace, the communication between these agents is made through a harness interface wrapping the library under test.
+Using the CLI `tcp` command, it is also possible to replace the first agent of a trace with a real entity connected through TCP.
+
+For example, one could start an OpenSSL server on port 44410:
+```sh
+openssl s_server -key tlspuffin/assets/alice-key.pem -cert tlspuffin/assets/alice.pem -accept 44410
+```
+
+And replay one of the seed traces against this server:
+```sh
+./target/debug/tlspuffin tcp --port 44410 'seeds/tlspuffin::tls::seeds::seed_client_attacker_full.trace'
+```

docs/docs/guides/quickstart.md

@@ -2,7 +2,7 @@
 title: Quickstart
 ---
 
-This guide will help you quickly create your first fuzzer with `tlspuffin`, including:
+This guide will help you quickly create your first fuzzer with *tlspuffin*, including:
 
 - installing the necessary tools
 - build a fuzzer for one of the pre-configured fuzz target (OpenSSL)
@@ -17,7 +17,7 @@ This guide is designed to get you started *fast*! The [Getting Started](./gettin
 
 ## Before you start
 
-`tlspuffin` relies on [Nix](https://nixos.org/) to setup an environment with all the necessary dependencies and to provide a consistent development experience. This guide will leverage Nix to simplify the install process and **we strongly encourage you to setup Nix** on your machine as a pre-requisite. If you are new to Nix, we recommend using the [Zero to Nix install guide](https://zero-to-nix.com/start/install).
+*tlspuffin* relies on [Nix](https://nixos.org/) to setup an environment with all the necessary dependencies and to provide a consistent development experience. This guide will leverage Nix to simplify the install process and **we strongly encourage you to setup Nix** on your machine as a pre-requisite. If you are new to Nix, we recommend using the [Zero to Nix install guide](https://zero-to-nix.com/start/install).
 
 Otherwise, you can manually install the dependencies listed in the repository's [README](https://github.com/tlspuffin/tlspuffin?tab=readme-ov-file#dependencies) file, as well as the dependencies for building the OpenSSL fuzz target used in this guide.
 
@@ -36,9 +36,9 @@ nix-shell
 
 ## Building the Fuzzing Target
 
-`tlspuffin` comes with several preconfigured fuzz targets and a wrapper script `mk_vendor` to simplify the build process:
+*tlspuffin* comes with several preconfigured fuzz targets and a wrapper script `mk_vendor` to simplify the build process:
 ```sh
-./tools/mk_vendor make openssl:openssl312 --options=sancov
+./tools/mk_vendor make openssl:openssl312 --options=sancov,asan
 ```
 
 ## Building the Fuzzer

docs/docs/references/support-matrix.md

@@ -2,10 +2,64 @@
 title: 'Support Matrix'
 ---
 
-:::warning[Ongoing Work]
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
-This page is currently under development. Information presented here might be incomplete or outdated.
+*tlspuffin* provides tooling to download, patch, and build several *preset* library configurations.
+This page describes the current support for these presets.
+
+:::warning[tooling support]
+
+The process for building the preset libraries is currently transitioning to use the *mk_vendor* tool
+in a manner consistent across all presets using:
+```
+./tools/mk_vendor make <preset>
+```
+
+As this is still work in progress, if a preset is marked with no *mk_vendor* support, you will need to build it through cargo:
+```
+cargo build --release -p tlspuffin --features=<preset>
+```
 
 :::
 
-**TODO:** OpenSSL/WolfSSL/LibreSSL/BoringSSL support matrix
+<Tabs>
+
+  <TabItem value="openssl" label="OpenSSL" default>
+    | Version    | ASAN support[^1]  | security claims | transcript extraction | mk_vendor preset[^2]   |
+    | :--------: | :---------------: | :-------------: | :-------------------: | ---------------------- |
+    | 3.1.2      | yes               | yes             | yes                   | `openssl:openssl312`   |
+    | 1.1.1u     | yes               | yes             | yes                   | `openssl:openssl111u`  |
+    | 1.1.1k     | yes               | yes             | yes                   | `openssl:openssl111k`  |
+    | 1.1.1j     | yes               | yes             | yes                   | `openssl:openssl111j`  |
+    | 1.0.2u     | yes               | yes             | yes                   | `openssl:openssl102u`  |
+    | 1.0.1f     | yes               | yes             | yes                   | `openssl:openssl101f`  |
+  </TabItem>
+
+  <TabItem value="libressl" label="LibreSSL">
+    | Version    | ASAN support[^1]  | security claims | transcript extraction | mk_vendor preset[^2]                             |
+    | :--------: | :---------------: | :-------------: | :-------------------: | ------------------------------------------------ |
+    | 3.3.3      | yes               | no              | no                    | *work in progress* (cargo preset: `libressl333`) |
+  </TabItem>
+
+  <TabItem value="wolfssl" label="wolfSSL">
+    | Version    | ASAN support[^1]  | security claims | transcript extraction | mk_vendor preset[^2]                             |
+    | :--------: | :---------------: | :-------------: | :-------------------: | ------------------------------------------------ |
+    | 4.3.0      | yes               | no              | yes                   | *work in progress* (cargo preset: `wolfssl430`)  |
+    | 5.1.0      | yes               | no              | yes                   | *work in progress* (cargo preset: `wolfssl510`)  |
+    | 5.2.0      | yes               | no              | yes                   | *work in progress* (cargo preset: `wolfssl520`)  |
+    | 5.3.0      | yes               | no              | yes                   | *work in progress* (cargo preset: `wolfssl530`)  |
+    | 5.4.0      | yes               | no              | yes                   | *work in progress* (cargo preset: `wolfssl540`)  |
+  </TabItem>
+
+  <TabItem value="boringssl" label="BoringSSL">
+    | Version    | ASAN support[^1]  | security claims | transcript extraction | mk_vendor preset[^2]   |
+    | :--------: | :---------------: | :-------------: | :-------------------: | ---------------------- |
+    | [2023.11](https://github.com/google/boringssl/commit/698aa894c96412d4df20e2bb031d9eb9c9d5919a)    | yes               | no              | yes                   | *work in progress* (cargo preset: `boringssl202311`) |
+    | [2024.03](https://github.com/google/boringssl/commit/368d0d87d0bd00f8227f74ce18e8e4384eaf6afa)    | yes               | no              | yes                   | *work in progress* (cargo preset: `boringssl202403`) |
+  </TabItem>
+
+</Tabs>
+
+[^1]: ASAN is available on platforms where *Clang* has [support for ASAN](https://clang.llvm.org/docs/AddressSanitizer.html#supported-platforms)
+[^2]: [*mk_vendor*](./mk_vendor) let you build a preset library independently of *tlspuffin*'s cargo-based build system, by running `./tools/mk_vendor make <preset>`

docs/docusaurus.config.ts

@@ -72,7 +72,7 @@ const config: Config = {
             },
             {
               label: 'Getting Started',
-              to: '/docs/guides/getting-started/installation',
+              to: '/docs/guides/getting-started/introduction',
             },
             {
               label: 'Reference Manual',

docs/sidebars.ts

@@ -13,6 +13,7 @@ const sidebars: SidebarsConfig = {
         'guides/getting-started/installation',
         'guides/getting-started/building-openssl',
         'guides/getting-started/fuzzing-openssl',
+        'guides/getting-started/replaying-traces',
       ],
     },
     {

tlspuffin/Cargo.toml

@@ -99,8 +99,10 @@ openssl102u = [
     "tls12-session-resumption"
 ]
 
+libressl = [ "libressl333" ]
+
 # Some LibreSSL version
-libressl = [
+libressl333 = [
     "openssl-src/libressl333",
     "tls12",
     "tls13",