Repository files navigation

tlsfuzzer is a test suite for SSLv2, SSLv3, TLS 1.0, TLS 1.1, TLS 1.2, andTLS 1.3 implementations. It's in early stages of development, so there areno API stability guarantees. While it uses fuzzing techniques for testing(randomisation of passed in inputs), the scripts are generally written in away that verifies correct error handling: unlike typical fuzzers it doesn'tcheck only that the system under test didn't crash, it checks that itreturned correct error messages.

You can find ready-to-use scripts testing for many vulnerabilities (ROBOT,DROWN, etc.)and general standards conformity(RFC 5246,RFC 7627,RFC 7905, etc.) in thescripts/directory.

You'll need:

• Python 2.6 or later or Python 3.6 or later
• tlslite-ng0.8.0-beta1 or later (note thattlslite willnot work andthey conflict with each other)
• ecdsapython module (dependency of tlslite-ng, should get installedautomatically with it), use at least version 0.15 for optimal performance

Optionally, to make cryptographic calculations significantly faster, you maywant to install the following libraries (see tlslite-ng and python-ecdsaREADME files for details):

• m2crypto
• gmpy

To getpip (if your python installation doesn't already have it) downloadget-pip.py and run(or seeUSAGE.mdfor alternative configuration that does not require installation of packages):

python get-pip.py

Then install tlslite-ng:

pip install --pre tlslite-ng

(Use--upgrade --pre if you did install it before)

Download the tlsfuzzer:

git clone https://github.com/tlsfuzzer/tlsfuzzer.git

After all dependencies are installed, make sure:

• you're in the directory of the project (after git clone justcd tlsfuzzer)
• 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 validHTTP responses is optional)

Then you can run one of the tests inscriptsdirectory, like so:

PYTHONPATH=. python scripts/test-invalid-compression-methods.py

If test has additional requirements, it will output them to console. No errorsprinted means that all expecations were met (so for tests with bad data theserver rejected our messages).

All scripts also accept--help to print the help message (specification ofall the options given script supports),-h to specify the hostname orIP address of the server-to-be-tested and-p to specify the port of theservice to be tested.

SeeUSAGE.md formore info and how to interpret errors and failures reported by scripts.

You can find mode detailed documentation for the project attlsfuzzer.readthedocs.io.

Using tlsfuzzer to test for timing side-channel attacks (Lucky13, paddingoracle attacks and timing-based Bleichenbacher oracle) is described intheTIMING.mddocument.

In general, the server under test requires just a RSA certificate, youcan 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 performany checks on the certificate (like hostname validation, CA signatures orkey usage). It does however verify if the signatures made on TLS messageby 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 frameworksfrom source, are available in theServer setup wikipage.

Example server configurations:

To test OpenSSL, it's sufficient to pass an extra-www option to atypicals_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 serverand 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 databasewith server certificate:

mkdir nssdbcertutil -N -d sql:nssdb --empty-passwordopenssl pkcs12 -export -passout pass: -out localhost.p12 -inkey localhost.key \-in localhost.crt -name localhostpk12util -i localhost.p12 -d sql:nssdb -W ''

Finally, start the server with support for TLSv1.0 and later protocols, DHEciphers 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 compilethe above servers from source is available on the wiki pageServer setup.

See theCONTRIBUTING.mddocument for description how to set up your development environment, sanitycheck the changes and requirements the changes need to follow.

You may also want to read theVISION.mdto learn more about the planned scope of the project.

Contributors are expected to follow the project'sCODE OF CONDUCTwhen interacting with other members of the community.