testssl.sh: Testing TLS/SSL encryption

NameLast ModifiedSizeType
CHANGELOG.txt2014-Dec-12 12:16:2910.03KB TXT Type Document
LICENSE.txt2014-May-03 11:04:2217.59KB TXT Type Document
bash-heartbleed.changelog.txt2014-May-03 17:37:15572.00B TXT Type Document
bash-heartbleed.sh2014-Jun-18 23:22:164.09KB SH File
ccs-injection.sh2014-Jun-14 23:44:423.94KB SH File
mapping-rfc.txt2014-Nov-18 10:49:5915.88KB TXT Type Document
openssl-1.0.2-beta1.linux64_32bit.tar.gz2014-Aug-03 20:38:042.50MB GZ Compressed Archive
openssl-1.0.2-beta1.linux64_32bit.tar.gz.asc2014-Aug-03 20:38:04190.00B ASC File
openssl-1.0.2-chacha.pm.tar.gz2014-Jul-16 19:16:135.19MB GZ Compressed Archive
openssl-1.0.2-chacha.pm.tar.gz.asc2014-Jul-16 19:16:54190.00B ASC File
openssl-rfc.mappping.html2014-Jun-17 21:33:2731.04KB HTML File
testssl.sh2014-Dec-08 10:32:5060.78KB SH File
testssl.sh.asc2014-Dec-12 10:59:24190.00B ASC File

testssl.sh is a free command line tool which checks a server's service on any port for the support of TLS/SSL ciphers, protocols as well as some flaws. It's designed to provide a clear output for a "is this good or bad" decision. It works for Linux and BSD out of the box – no gems, CPAN, pip or the like.

Standard call: testssl.sh <hostname> As for security reasons some distributors outphase the buggy stuff – and this is exactly you want to check for – it's recommended to compile OpenSSL by yourself or check out the OpenSSL binaries below (Linux) – they come with a whopping 191 ciphers, ~80 more than on an average Linux distro. In any case: Except the ciphers, you will get a warning if your OpenSSL client cannot perform a specific check, see below.

testssl.sh is pretty much portable. It is working on every recent Linux and BSD distribution. It is supposed also to work on any other unixoid systems — MacOSX and MSYS2. A newer OpenSSL version (1.0) is needed though. Suggested is to have GNU tools installed (specifically /bin/bash and awk).

New features (for development version 2.3dev see github (branch master):

check of a broken TLS setup (client: FreeBSD 10)
Invoking

The normal use case is probably just  testssl.sh <hostname> , see first picture above. The second picture with the dark background shows a run from a FreeBSD 10 machine against a completey broken and not patched Ubuntu 12.04 machine. The features not available locally on FreeBSD are in magenta, the dangerous ciphers, protocols and vulnerabilities are in red.
    Starting testssl.sh with no params will give you a general idea how to use it:
userid@somehost:~ % testssl.sh

testssl.sh <options> 

where <options> is one of

   <-h|--help>                 what you're looking at
   <-b|--banner>               displays banner + version
   <-v|--version>              same as above
   <-V|--local>                pretty print all local ciphers
   <-V|--local> <hexcode>      what cipher is <pattern hexcode>?


testssl.sh <options> URI

   <-e|--each-cipher>          check each local ciphers remotely 
   <-E|-ee|--cipher-per-proto> check those per protocol
   <-f|--ciphers>              check cipher suites
   <-p|--protocols>            check TLS/SSL protocols only
   <-P|--preference>           displays the servers picks: protocol+cipher
   <-y|--spdy>                 checks for SPDY/NPN
   <-x|--single-ciphers-test> <pattern>  tests matched <pattern> of cipher
   <-B|--heartbleed>           tests only for heartbleed vulnerability
   <-I|--ccs|--ccs_injection>  tests only for CCS injection vulnerability
   <-R|--renegotiation>        tests only for renegotiation vulnerability
   <-C|--compression|--crime>  tests only for CRIME vulnerability
   <-T|--breach>               tests only for BREACH vulnerability
   <-0|--poodleh>              tests only for POODLE vulnerability
   <-s|--pfs|--fs|--nsa>       checks (perfect) forward secrecy settings
   <-4|--rc4|--appelbaum>      which RC4 ciphers are being offered?
   <-H|--header|--headers>     check for HSTS and server banner string

   <t|--starttls> protocol     does a default run against a STARTTLS enabled service


partly mandatory parameters:

  URI           host|host:port|URL|URL:port   (port 443 is assumed unless otherwise specified)
  pattern       an ignore case word pattern of cipher hexcode or any other string in the name, kx or bits
  protocol      is one of ftp,smtp,pop3,imap,xmpp,telnet (for the latter you need e.g. the supplied openssl)

userid@somehost:~ %

A STARTTLS check (see third picture on the lower left hand side, invoked with  testssl.sh -t pop3 pop.o2online.de:110) would be achieved with e.g.
testssl.sh --starttls smtp <smtphostname>.<tld>:587 
testssl.sh -t xmpp <jabberhostname>.<tld>:5222 
testssl.sh --starttls pop3 <pophostname>.<tld>:110
STARTTLS check with Ubuntu's 12.04 OpenSSL, no recompiled OpenSSL
As the help says: Currently only one option at a time works. Note that the calling order has changed in 2.2. The second argument now is the protocol!

A neat feature: If you want to find out what local ciphers you have and print them pretty, use  testssl.sh -V. Ever wondered what hexcode a cipher is?  testssl.sh -V 9f  lets you search for the hexcode 9f. You can also supply an ignore case pattern in the output of a single cipher line, e.g.  testssl.sh -V CBC  puts out every locally available cipher having the Cipher Block Chaining mode in its name. If you have the file  mapping-rfc.txt in the same directory  testssl.sh -V  displays the matching RFC style cipher suite name. Also during every cipher suite test the corresponding RFC style name is displayed. It's a broad output. If you don't want this, you need to move mapping-rfc.txt away.

A similar test can be performed with  testssl.sh -x <pattern> URL . Example:  testssl.sh -x ECDH google.com  checks google.com for ECDH ciphers (and lists also not available ones at the target),  testssl.sh -x DHE smtp.posteo.de:465  does a similar thing for the TLS enabled SMTP service – see picture on the lower right hand side.

Got it so far? Good.
check ECDHE cipher @ gmail's TLS SMTP port


Hint regarding OpenSSL binary

As mentioned above, a prerequisite for thoroughly checking SSL/TLS enabled servers is: all you want to check for has to be available on your client. Transport encryption is not only depending on the server but also on your crypto provider on the client side – especially if you want to use it for testing. So there are drawbacks out of the Linux distributions boxes -- so to speak: The worst test scenario is using libressl -- as it has lots of stuff disabled.A
The signed tarball provides specially compiled statically linked (except glibc and the loader) OpenSSL binaries as a courtesy. The newer version version also has ChaCha+Poly ciphers on board. There are also Kerberos binaries included -- the latter ones require a bunch of libraries (no static binaries). In the end those binaries will give you 191 ciphers as opposed to ~110 from standard Linux distros! You'll need to unpack my binaries, dump those you need either in the same location as  testssl.sh , named just  openssl  or  openssl.`uname -m` . You can also tell  testssl.sh  via environment variable where your openssl binary is:
export
OPENSSL=<path_to_myopenssl>
before you use testssl. Or issue
OPENSSL=<path_to_myopenssl> testssl.sh <hostname>
Don't try outdated OpenSSL versions before 1.0! Those versions are deprecated, you likely will not get very far. testssl.sh is not locking those out but things might not work as expected. Support will be retired soon. If you insist on using crippled binaries, you'll get a warning in magenta, see picture on the right hand side.


Misc

Feedback, bugs and contributions are welcome! Currently there are two git repos @ github and @ nginx goodies on bitbucket (thx Markus setting the latter up). Here @ https://testssl.sh you will always find the stable version. At the github repo is the latest-greatest devel version. Mailing list, bug tracker etc. will come soon.

Contact me via github or send me an e-mail to dirk aet testssl dot sh.



I post all significant updates on Twitter (@drwetter).  

Imprint