github.com/Psiphon-Labs/tls-tris@v0.0.0-20230824155421-58bf6d336a9a/README.md (about)

     1  ```
     2   _____ _     ____        _        _
     3  |_   _| |   / ___|      | |_ _ __(_)___
     4    | | | |   \___ \ _____| __| '__| / __|
     5    | | | |___ ___) |_____| |_| |  | \__ \
     6    |_| |_____|____/       \__|_|  |_|___/
     7  
     8  ```
     9  
    10  crypto/tls, now with 100% more 1.3.
    11  
    12  THE API IS NOT STABLE AND DOCUMENTATION IS NOT GUARANTEED.
    13  
    14  [![Build Status](https://travis-ci.org/cloudflare/tls-tris.svg?branch=master)](https://travis-ci.org/cloudflare/tls-tris)
    15  
    16  ## Usage
    17  
    18  Since `crypto/tls` is very deeply (and not that elegantly) coupled with the Go stdlib,
    19  tls-tris shouldn't be used as an external package.  It is also impossible to vendor it
    20  as `crypto/tls` because stdlib packages would import the standard one and mismatch.
    21  
    22  So, to build with tls-tris, you need to use a custom GOROOT.
    23  
    24  A script is provided that will take care of it for you: `./_dev/go.sh`.
    25  Just use that instead of the `go` tool.
    26  
    27  The script also transparently fetches the custom Cloudflare Go 1.10 compiler with the required backports.
    28  
    29  ## Development
    30  
    31  ### Dependencies
    32  
    33  Copy paste line bellow to install all required dependencies:
    34  
    35  * ArchLinux:
    36  ```
    37  pacman -S go docker gcc git make patch python2 python-docker rsync
    38  ```
    39  
    40  * Debian:
    41  ```
    42  apt-get install build-essential docker go patch python python-pip rsync
    43  pip install setuptools
    44  pip install docker
    45  ```
    46  
    47  * Ubuntu (18.04) :
    48  ```
    49  apt-get update
    50  apt-get install build-essential docker docker.io golang patch python python-pip rsync sudo
    51  pip install setuptools
    52  pip install docker
    53  sudo usermod -a -G docker $USER
    54  ```
    55  
    56  Similar dependencies can be found on any UNIX based system/distribution.
    57  
    58  ### Building
    59  
    60  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``.
    61  
    62  ```
    63  git clone https://github.com/cloudflare/tls-tris.git
    64  cd tls-tris; cp _dev/utils/pre-commit .git/hooks/ 
    65  make -f _dev/Makefile build-all
    66  ```
    67  
    68  ### Testing
    69  
    70  We run 3 kinds of test:.
    71  
    72  * Unit testing: <br/>``make -f _dev/Makefile test-unit``
    73  * Testing against BoringSSL test suite: <br/>``make -f _dev/Makefile test-bogo``
    74  * Compatibility testing (see below):<br/>``make -f _dev/Makefile test-interop``
    75  
    76  To run all the tests in one go use:
    77  ```
    78  make -f _dev/Makefile test
    79  ```
    80  
    81  ### Testing interoperability with 3rd party libraries
    82  
    83  In order to ensure compatibility we are testing our implementation against BoringSSL, NSS and PicoTLS.
    84  
    85  Makefile has a specific target for testing interoperability with external libraries. Following command can be used in order to run such test:
    86  
    87  ```
    88  make -f _dev/Makefile test-interop
    89  ```
    90  
    91  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. 
    92  
    93  Script can be started from command line directly. For example:
    94  
    95  ```
    96  > ./interop_test_runner -v InteropServer_NSS.test_zero_rtt
    97  test_zero_rtt (__main__.InteropServer_NSS) ... ok
    98  
    99  ----------------------------------------------------------------------
   100  Ran 1 test in 8.765s
   101  
   102  OK
   103  ```
   104  
   105  ### Debugging
   106  
   107  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.