README.md

TryTLS

Does your library check TLS certificates properly? Broken certificate checks seems to be an overlooked issue. Handling certificates is surprisingly complex, and calls for extra attention.

TryTLS is a tool for the software and library developers, vulnerability researchers, and end-users, who want to use TLS safely.

We hope to help you to test certificate handling easily. We support systematic and readily planned tests and try make integrating your favorite language and library easy.

How Does It Work?

• Backends use ports and virtual hosts to provide falsified/broken certificate checks
• Stubs are written for the target languages and libraries to attempt the TLS connection
• Runners "check the checks" by calling the stubs systematically to find out how libraries handle signatures, domain names, time, SNI etc. against the backends

Runners

We have a Python based test runner and a work-in-progress bash based test runner.

Installation

$ git clone https://github.com/ouspg/trytls.git
$ cd trytls
$ pip install .

In case you don't have pip installed, please refer to these instructions.

Usage

$ trytls https python stubs/python-urllib2/run.py
platform: OS X 10.11.5
runner: trytls 0.1.0 (CPython 2.7.10, OpenSSL 0.9.8zh)
stub: python 'stubs/python-urllib2/run.py'
 PASS expired certificate [reject expired.badssl.com:443]
 PASS wrong hostname in certificate [reject wrong.host.badssl.com:443]
 PASS self-signed certificate [reject self-signed.badssl.com:443]
  ...

Stubs

Stubs and their documentation can be found from the stubs/ directory.

Backends

We currently are working to support following backends:

• BadSSL - we have cherry picked the relevant tests
• Local backend in the test runner itself (aka localhost backend)
• SSLLabs - protection against certain attacks
• Trytls backend both as docker based "run-it-yourself" packaging and as a hosted service provided by us [WIP]

Test runners allow user to test against all or any of these backends.

What TryTLS Is Not

• We do not address possible client certificate check problems in server code
• We do not do or require a man-in-the-middle tools
• We do not support smart TVs, IoT toasters and other such devices that can't run the test driver

Found issues

• Wreq connection to HTTPS site with invalid hostname · Issue #84 · bos/wreq GitHub
• See also Is Wreq suitable for HTTPS applications? · Issue #82 · bos/wreq · GitHub
• Related http-client-tls connection to HTTPS site with invalid hostname · Issue #212 · snoyberg/http-client · GitHub

Contributors

• Mauri Miettinen (@Mamietti)
• Aleksi Klasila (@aleksiklasila)
• Jani Kenttälä (@evilon)
• Ossi Herrala (@oherrala)
• Joachim Viide (@jviide)
• Marko Laakso (@ikisusi)
• Pekka Pietikäinen (@ppietikainen)
• Joonas Kuorilehto (@joneskoo)
• Kasper Kyllönen (@nkapu)

We invite people to contribute.

Contact us

• Preferred: public tweet
• Use #trytls and point it to @oupsg
• Less public alternative: direct twitter-message to @ouspg