Fuzzer and test suite for TLS (SSLv2, SSLv3, v1.0, v1.1, v1.2, v1.3) implementations. Early alpha version - thus no API stability guarantees.
- Python 2.6 or later or Python 3.3 or later
0.8.0-alpha37 or later (note that
tlslitewill not work and they conflict with each other)
- ecdsa python module (dependency of tlslite-ng, should get installed automatically with it), use at least version 0.15 for optimal performance
Optionally, to make cryptographic calculations significantly faster, you may want to install the following libraries (see tlslite-ng and python-ecdsa README files for details):
Then install tlslite-ng:
pip install --pre tlslite-ng
--upgrade --pre if you did install it before)
Download the tlsfuzzer:
git clone https://github.com/tomato42/tlsfuzzer.git
After all dependencies are installed, make sure:
- you're in the directory of the project (after git clone just
- the server you want to test is running on the same computer (localhost)
- the server is listening on port 4433
- and the server will answer with data to HTTP queries (answer with valid HTTP responses is optional)
Then you can run one of the tests in
directory, like so:
PYTHONPATH=. python scripts/test-invalid-compression-methods.py
If test has additional requirements, it will output them to console. No errors printed means that all expecations were met (so for tests with bad data the server rejected our messages).
All scripts also accept
--help to print the help message (specification of
all the options given script supports),
-h to specify the hostname or
IP address of the server-to-be-tested and
-p to specify the port of the
service to be tested.
See USAGE.md for more info and how to interpret errors and failures reported by scripts.
You can find mode detailed documentation for the project at tlsfuzzer.readthedocs.io.
Using tlsfuzzer to test for timing side-channel attacks (Lucky13, padding oracle attacks and timing-based Bleichenbacher oracle) is described in the TIMING.md document.
Server under test configuration
In general, the server under test requires just a RSA certificate, you can create it using the following OpenSSL command:
openssl req -x509 -newkey rsa -keyout localhost.key -out localhost.crt -subj \ /CN=localhost -nodes -batch
Note: tlsfuzzer verifies only TLS level behaviour, it does not perform any checks on the certificate (like hostname validation, CA signatures or key usage). It does however verify if the signatures made on TLS message by the server (like in Server Key Exchange or Certificiate Verify message) match the certificate sent by the server.
More detailed instructions, including how to build the different frameworks from source, are available in the Server setup wiki page.
Example server configurations:
To test OpenSSL, it's sufficient to pass an extra
-www option to a
s_server command line:
openssl s_server -key localhost.key -cert localhost.crt -www
To test GnuTLS server, you need to tell it to behave as an HTTP server and additionally, to not ask for client certificates:
gnutls-serv --http -p 4433 --x509keyfile localhost.key --x509certfile \ localhost.crt --disable-client-cert
To test the Mozilla NSS library server, you first need to create a database with server certificate:
mkdir nssdb certutil -N -d sql:nssdb --empty-password openssl pkcs12 -export -passout pass: -out localhost.p12 -inkey localhost.key \ -in localhost.crt -name localhost pk12util -i localhost.p12 -d sql:nssdb -W ''
Finally, start the server with support for TLSv1.0 and later protocols, DHE ciphers and with the above certificate:
selfserv -d sql:./nssdb -p 4433 -V tls1.0: -H 1 -n localhost
More advanced and complex configurations as well as description how to compile the above servers from source is available on the wiki page Server setup.
See the CONTRIBUTING.md document for description how to set up your development environment, sanity check the changes and requirements the changes need to follow.
You may also want to read the VISION.md to learn more about the planned scope of the project.
Contributors are expected to follow the project's CODE OF CONDUCT when interacting with other members of the community.