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.
3.0 KiB
_____ _ ____ _ _
|_ _| | / ___| | |_ _ __(_)___
| | | | \___ \ _____| __| '__| / __|
| | | |___ ___) |_____| |_| | | \__ \
|_| |_____|____/ \__|_| |_|___/
crypto/tls, now with 100% more 1.3.
THE API IS NOT STABLE AND DOCUMENTATION IS NOT GUARANTEED.
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:
make -f _dev/Makefile test-unit - Testing against BoringSSL test suite:
make -f _dev/Makefile test-bogo - Compatibility testing (see below):
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.