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