| 1 |
# BoringSSL SSL Tests |
| 2 |
|
| 3 |
This directory contains BoringSSL's protocol-level test suite. |
| 4 |
|
| 5 |
Testing a TLS implementation can be difficult. We need to produce invalid but |
| 6 |
sufficiently correct handshakes to get our implementation close to its edge |
| 7 |
cases. TLS's cryptographic steps mean we cannot use a transcript and effectively |
| 8 |
need a TLS implementation on the other end. But we do not wish to litter |
| 9 |
BoringSSL with options for bugs to test against. |
| 10 |
|
| 11 |
Instead, we use a fork of the Go `crypto/tls` package, heavily patched with |
| 12 |
configurable bugs. This code, along with a test suite and harness written in Go, |
| 13 |
lives in the `runner` directory. The harness runs BoringSSL via a C/C++ shim |
| 14 |
binary which lives in this directory. All communication with the shim binary |
| 15 |
occurs with command-line flags, sockets, and standard I/O. |
| 16 |
|
| 17 |
This strategy also ensures we always test against a second implementation. All |
| 18 |
features should be implemented twice, once in C for BoringSSL and once in Go for |
| 19 |
testing. If possible, the Go code should be suitable for potentially |
| 20 |
upstreaming. However, sometimes test code has different needs. For example, our |
| 21 |
test DTLS code enforces strict ordering on sequence numbers and has controlled |
| 22 |
packet drop simulation. |
| 23 |
|
| 24 |
To run the tests manually, run `go test` from the `runner` directory. It takes |
| 25 |
command-line flags found at the top of `runner/runner.go`. The `-help` option |
| 26 |
also works after using `go test -c` to make a `runner.test` binary first. |
| 27 |
|
| 28 |
If adding a new test, these files may be a good starting point: |
| 29 |
|
| 30 |
* `runner/runner.go`: the test harness and all the individual tests. |
| 31 |
* `runner/common.go`: contains the `Config` and `ProtocolBugs` struct which |
| 32 |
control the Go TLS implementation's behavior. |
| 33 |
* `test_config.h`, `test_config.cc`: the command-line flags which control the |
| 34 |
shim's behavior. |
| 35 |
* `bssl_shim.cc`: the shim binary itself. |