Henry D. Case
e5c37bded5
Goal of this PR is to rework testing script so that actual testing is easy to extend and perform during development cycle. * For interoperability testing I use python script and test framework, instead of complicated bsah scripts. Script itself is not yet perfect but it makes it much easier to extend tests and work with them during development time * Makefile has been extended and now includes all steps needed to build the library and run tests. It's now possible to run any kind of tests without exporting environment variables. Thanks to this change it is stupid-easy to run any kind of tests. * There are 3 kinds of tests implemented in the library - unittests, interoperability tests and bogo. Travis has been changed and now dashbord will show only results for those 3 targets.
97 lines
3.0 KiB
Markdown
97 lines
3.0 KiB
Markdown
```
|
|
_____ _ ____ _ _
|
|
|_ _| | / ___| | |_ _ __(_)___
|
|
| | | | \___ \ _____| __| '__| / __|
|
|
| | | |___ ___) |_____| |_| | | \__ \
|
|
|_| |_____|____/ \__|_| |_|___/
|
|
|
|
```
|
|
|
|
crypto/tls, now with 100% more 1.3.
|
|
|
|
THE API IS NOT STABLE AND DOCUMENTATION IS NOT GUARANTEED.
|
|
|
|
[](https://travis-ci.org/cloudflare/tls-tris)
|
|
|
|
## Usage
|
|
|
|
Since `crypto/tls` is very deeply (and not that elegantly) coupled with the Go stdlib,
|
|
tls-tris shouldn't be used as an external package. It is also impossible to vendor it
|
|
as `crypto/tls` because stdlib packages would import the standard one and mismatch.
|
|
|
|
So, to build with tls-tris, you need to use a custom GOROOT.
|
|
|
|
A script is provided that will take care of it for you: `./_dev/go.sh`.
|
|
Just use that instead of the `go` tool.
|
|
|
|
The script also transparently fetches the custom Cloudflare Go 1.10 compiler with the required backports.
|
|
|
|
## Development
|
|
|
|
### Dependencies
|
|
|
|
Copy paste line bellow to install all required dependencies:
|
|
|
|
* ArchLinux:
|
|
```
|
|
pacman -S go docker gcc git make patch python2 python-docker rsync
|
|
```
|
|
|
|
* Debian:
|
|
```
|
|
apt-get install build-essential docker go patch python python-pip rsync
|
|
pip install setuptools
|
|
pip install docker
|
|
```
|
|
|
|
Similar dependencies can be found on any UNIX based system/distribution.
|
|
|
|
### Building
|
|
|
|
There are number of things that need to be setup before running tests. Most important step is to copy ``go env GOROOT`` directory to ``_dev`` and swap TLS implementation and recompile GO. Then for testing we use go implementation from ``_dev/GOROOT``.
|
|
|
|
```
|
|
make -f _dev/Makefile build-all
|
|
```
|
|
|
|
### Testing
|
|
|
|
We run 3 kinds of test:.
|
|
|
|
* Unit testing: <br/>``make -f _dev/Makefile test-unit``
|
|
* Testing against BoringSSL test suite: <br/>``make -f _dev/Makefile test-bogo``
|
|
* Compatibility testing (see below):<br/>``make -f _dev/Makefile test-compat``
|
|
|
|
To run all the tests in one go use:
|
|
```
|
|
make -f _dev/Makefile test
|
|
```
|
|
|
|
### Testing interoperability with 3rd party libraries
|
|
|
|
In order to ensure compatibility we are testing our implementation against BoringSSL, NSS and PicoTLS.
|
|
|
|
Makefile has a specific target for testing interoperability with external libraries. Following command can be used in order to run such test:
|
|
|
|
```
|
|
make -f _dev/Makefile test-interop
|
|
```
|
|
|
|
The makefile target is just a wrapper and it executes ``_dev/interop_test_runner`` script written in python. The script implements interoperability tests using ``python unittest`` framework.
|
|
|
|
Script can be started from command line directly. For example:
|
|
|
|
```
|
|
> ./interop_test_runner -v InteropServer_NSS.test_zero_rtt
|
|
test_zero_rtt (__main__.InteropServer_NSS) ... ok
|
|
|
|
----------------------------------------------------------------------
|
|
Ran 1 test in 8.765s
|
|
|
|
OK
|
|
```
|
|
|
|
### Debugging
|
|
|
|
When the environment variable `TLSDEBUG` is set to `error`, Tris will print a hexdump of the Client Hello and a stack trace if an handshake error occurs. If the value is `short`, only the error and the first meaningful stack frame are printed.
|