_____ _ ____ _ _
|_ _| | / ___| | |_ _ __(_)___
| | | | \___ \ _____| __| '__| / __|
| | | |___ ___) |_____| |_| | | \__ \
|_| |_____|____/ \__|_| |_|___/
crypto/tls, now with 100% more 1.3.
THE API IS NOT STABLE AND DOCUMENTATION IS NOT GUARANTEED.
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.
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
Ubuntu (18.04) :
apt-get update
apt-get install build-essential docker docker.io golang patch python python-pip rsync sudo
pip install setuptools
pip install docker
sudo usermod -a -G docker $USER
Similar dependencies can be found on any UNIX based system/distribution.
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
.
git clone https://github.com/cloudflare/tls-tris.git
cd tls-tris; cp _dev/utils/pre-commit .git/hooks/
make -f _dev/Makefile build-all
We run 3 kinds of test:.
make -f _dev/Makefile test-unit
make -f _dev/Makefile test-bogo
make -f _dev/Makefile test-interop
To run all the tests in one go use:
make -f _dev/Makefile test
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
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.