Henry D. Case
c20de2f694
* Makes building instructions for Ubuntu copy-paste'able * Updates dependency list
107 lines
3.3 KiB
Markdown
107 lines
3.3 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
|
|
```
|
|
|
|
* 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.
|
|
|
|
### 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``.
|
|
|
|
```
|
|
git clone https://github.com/cloudflare/tls-tris.git
|
|
cd tls-tris; 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.
|