testssl.sh/doc/testssl.1

.\" Automatically generated by Pandoc 3.1.11.1
.\"
.TH "" "" "" "" ""
.SS NAME
testssl.sh \[en] check encryption of SSL/TLS servers
.SS SYNOPSIS
\f[CR]testssl.sh [OPTIONS] <URI>\f[R],
\f[CR]testssl.sh [OPTIONS] \-\-file <FILE>\f[R]
.PP
or
.PP
\f[CR]testssl.sh [BANNER OPTIONS]\f[R]
.SS DESCRIPTION
testssl.sh is a free command line tool which checks a server\[cq]s
service on any port for the support of TLS/SSL ciphers, protocols as
well as cryptographic flaws and much more.
.PP
The output rates findings by color (screen) or severity (file output) so
that you are able to tell whether something is good or bad.
The (screen) output has several sections in which classes of checks are
being performed.
To ease readability on the screen it aligns and indents the output
properly.
.PP
Only you see the result.
You also can use it internally on your LAN.
Except DNS lookups or unless you instruct testssl.sh to check for
revocation of certificates it doesn\[cq]t use any other hosts or even
third parties for any test.
.SS REQUIREMENTS
Testssl.sh is out of the box portable: it runs under any Unix\-like
stack: Linux, *BSD, MacOS X, WSL=Windows Subsystem for Linux, Cygwin and
MSYS2.
\f[CR]bash\f[R] is a prerequisite, also version 3 is still supported.
Standard utilities like awk, sed, tr and head are also needed.
This can be of a BSD, System 5 or GNU flavor whereas grep from System V
is not yet supported.
.PP
Any OpenSSL or LibreSSL version is needed as a helper.
Unlike previous versions of testssl.sh almost every check is done via
(TCP) sockets.
In addition statically linked OpenSSL binaries for major operating
systems are supplied in \f[CR]./bin/\f[R].
.SS GENERAL
\f[CR]testssl.sh URI\f[R] as the default invocation does the so\-called
default run which does a number of checks and puts out the results
colorized (ANSI and termcap) on the screen.
It does every check listed below except \f[CR]\-E\f[R] which are (order
of appearance):
.IP " 0)" 4
displays a banner (see below), does a DNS lookup also for further IP
addresses and does for the returned IP address a reverse lookup.
Last but not least a service check is being done.
.IP " 1)" 4
SSL/TLS protocol check
.IP " 2)" 4
standard cipher categories
.IP " 3)" 4
server\[cq]s cipher preferences (server order?)
.IP " 4)" 4
forward secrecy: ciphers and elliptical curves
.IP " 5)" 4
server defaults (certificate info, TLS extensions, session information)
.IP " 6)" 4
HTTP header (if HTTP detected or being forced via
\f[CR]\-\-assume\-http\f[R])
.IP " 7)" 4
vulnerabilities
.IP " 8)" 4
testing each of 370 preconfigured ciphers
.IP " 9)" 4
client simulation
.IP "10)" 4
rating
.SS OPTIONS AND PARAMETERS
Options are either short or long options.
Any long or short option requiring a value can be called with or without
an equal sign.
E.g.
\f[CR]testssl.sh \-t=smtp \-\-wide \-\-openssl=/usr/bin/openssl <URI>\f[R]
(short options with equal sign) is equivalent to
\f[CR]testssl.sh \-\-starttls smtp \-\-wide \-\-openssl /usr/bin/openssl <URI>\f[R]
(long option without equal sign).
Some command line options can also be preset via ENV variables.
\f[CR]WIDE=true OPENSSL=/usr/bin/openssl testssl.sh \-\-starttls=smtp <URI>\f[R]
would be the equivalent to the aforementioned examples.
Preference has the command line over any environment variables.
.PP
\f[CR]<URI>\f[R] or \f[CR]\-\-file <FILE>\f[R] always needs to be the
last parameter.
.SS BANNER OPTIONS (standalone)
\f[CR]\-\-help\f[R] (or no arg) displays command line help
.PP
\f[CR]\-b, \-\-banner\f[R] displays testssl.sh banner, including
license, usage conditions, version of testssl.sh, detected openssl
version, its path to it, # of ciphers of openssl, its build date and the
architecture.
.PP
\f[CR]\-v, \-\-version\f[R] same as before
.PP
\f[CR]\-V [pattern], \-\-local [pattern]\f[R] pretty print all local
ciphers supported by openssl version.
If a pattern is supplied it performs a match (ignore case) on any of the
strings supplied in the wide output, see below.
The pattern will be searched in the any of the columns: hexcode, cipher
suite name (OpenSSL or IANA), key exchange, encryption, bits.
It does a word pattern match for non\-numbers, for number just a normal
match applies.
Numbers here are defined as [0\-9,A\-F].
This means (attention: catch) that the pattern CBC is matched as
non\-word, but AES as word.
This option also accepts \f[CR]\-\-openssl=<path_to_openssl>\f[R].
.SS INPUT PARAMETERS
\f[CR]URI\f[R] can be a hostname, an IPv4 or IPv6 address (restriction
see below) or an URL.
IPv6 addresses need to be in square brackets.
For any given parameter port 443 is assumed unless specified by
appending a colon and a port number.
The only preceding protocol specifier allowed is \f[CR]https\f[R].
You need to be aware that checks for an IP address might not hit the
vhost you want.
DNS resolution (A/AAAA record) is being performed unless you have an
\f[CR]/etc/hosts\f[R] entry for the hostname.
.PP
\f[CR]\-\-file <fname>\f[R] or the equivalent \f[CR]\-iL <fname>\f[R]
are mass testing options.
Per default it implicitly turns on \f[CR]\-\-warnings batch\f[R], unless
warnings has been set to off before.
In its first incarnation the mass testing option reads command lines
from \f[CR]fname\f[R].
\f[CR]fname\f[R] consists of command lines of testssl, one line per
instance.
Comments after \f[CR]#\f[R] are ignored, \f[CR]EOF\f[R] signals the end
of fname any subsequent lines will be ignored too.
You can also supply additional options which will be inherited to each
child, e.g.\ When invoking
\f[CR]testssl.sh \-\-wide \-\-log \-\-file <fname>\f[R] .
Each single line in \f[CR]fname\f[R] is parsed upon execution.
If there\[cq]s a conflicting option and serial mass testing option is
being performed the check will be aborted at the time it occurs and
depending on the output option potentially leaving you with an output
file without footer.
In parallel mode the mileage varies, likely a line won\[cq]t be scanned.
.PP
Alternatively \f[CR]fname\f[R] can be in \f[CR]nmap\f[R]\[cq]s
grep(p)able output format (\f[CR]\-oG\f[R]).
Only open ports will be considered.
Multiple ports per line are allowed.
The ports can be different and will be tested by testssl.sh according to
common practice in the internet, i.e.\ if nmap shows in its output an
open port 25, automatically \f[CR]\-t smtp\f[R] will be added before the
URI whereas port 465 will be treated as a plain TLS/SSL port, not
requiring an STARTTLS SMTP handshake upfront.
This is done by an internal table which correlates nmap\[cq]s open port
detected to the STARTTLS/plain text decision from testssl.sh.
.PP
Nmap\[cq]s output always returns IP addresses and only if there\[cq]s a
PTR DNS record available a hostname.
As it is not checked by nmap whether the hostname matches the IP (A or
AAAA record), testssl.sh does this automatically for you.
If the A record of the hostname matches the IP address, the hostname is
used and not the IP address.
Please keep in mind that checks against an IP address might not hit the
vhost you maybe were aiming at and thus it may lead to different
results.
.PP
A typical internal conversion to testssl.sh file format from nmap\[cq]s
grep(p)able format could look like:
.IP
.EX
  10.10.12.16:443
  10.10.12.16:1443
  \-t smtp host.example.com:25
  host.example.com:443
  host.example.com:631
  \-t ftp 10.10.12.11:21
  10.10.12.11:8443
.EE
.PP
Please note that \f[CR]fname\f[R] has to be in Unix format.
DOS carriage returns won\[cq]t be accepted.
Instead of the command line switch the environment variable FNAME will
be honored too.
.PP
\f[CR]\-\-mode <serial|parallel>\f[R].
Mass testing to be done serial (default) or parallel
(\f[CR]\-\-parallel\f[R] is shortcut for the latter,
\f[CR]\-\-serial\f[R] is the opposite option).
Per default mass testing is being run in serial mode, i.e.\ one line
after the other is processed and invoked.
The variable \f[CR]MASS_TESTING_MODE\f[R] can be defined to be either
equal \f[CR]serial\f[R] or \f[CR]parallel\f[R].
.PP
\f[CR]\-\-warnings <batch|off>\f[R].
The warnings parameter determines how testssl.sh will deal with
situations where user input normally will be necessary.
There are two options.
\f[CR]batch\f[R] doesn\[cq]t wait for a confirming keypress when a
client\- or server\-side problem is encountered.
As of 3.0 it just then terminates the particular scan.
This is automatically chosen for mass testing (\f[CR]\-\-file\f[R]).
\f[CR]off\f[R] just skips the warning, the confirmation but continues
the scan, independent whether it makes sense or not.
Please note that there are conflicts where testssl.sh will still ask for
confirmation which are the ones which otherwise would have a drastic
impact on the results.
Almost any other decision will be made in the future as a best guess by
testssl.sh.
The same can be achieved by setting the environment variable
\f[CR]WARNINGS\f[R].
.PP
\f[CR]\-\-connect\-timeout <seconds>\f[R] This is useful for socket TCP
connections to a node.
If the node does not complete a TCP handshake (e.g.\ because it is down
or behind a firewall or there\[cq]s an IDS or a tarpit) testssl.sh may
usually hang for around 2 minutes or even much more.
This parameter instructs testssl.sh to wait at most \f[CR]seconds\f[R]
for the handshake to complete before giving up.
This option only works if your OS has a timeout binary installed.
CONNECT_TIMEOUT is the corresponding environment variable.
.PP
\f[CR]\-\-openssl\-timeout <seconds>\f[R] This is especially useful for
all connects using openssl and practically useful for mass testing.
It avoids the openssl connect to hang for \[ti]2 minutes.
The expected parameter \f[CR]seconds\f[R] instructs testssl.sh to wait
before the openssl connect will be terminated.
The option is only available if your OS has a timeout binary installed.
As there are different implementations of \f[CR]timeout\f[R]: It
automatically calls the binary with the right parameters.
OPENSSL_TIMEOUT is the equivalent environment variable.
.PP
\f[CR]\-\-basicauth <user:pass>\f[R] This can be set to provide HTTP
basic auth credentials which are used during checks for security
headers.
BASICAUTH is the ENV variable you can use instead.
.PP
\f[CR]\-\-reqheader <header>\f[R] This can be used to add additional
HTTP request headers in the correct format
\f[CR]Headername: headercontent\f[R].
This parameter can be called multiple times if required.
For example:
\f[CR]\-\-reqheader \[aq]Proxy\-Authorization: Basic dGVzdHNzbDpydWxlcw==\[aq] \-\-reqheader \[aq]ClientID: 0xDEADBEAF\[aq]\f[R].
REQHEADER is the corresponding environment variable.
.PP
\f[CR]\-\-mtls <path_to_client_cert>\f[R] This can be set to provide a
file containing a client certificatete and a private key (not encrypted)
in PEM format, which is used when a mutual TLS authentication is
required by the remote server.
MTLS is the equivalent environment variable.
.SS SPECIAL INVOCATIONS
\f[CR]\-t <protocol>, \-\-starttls <protocol>\f[R] does a default run
against a STARTTLS enabled \f[CR]protocol\f[R].
\f[CR]protocol\f[R] must be one of \f[CR]ftp\f[R], \f[CR]smtp\f[R],
\f[CR]pop3\f[R], \f[CR]imap\f[R], \f[CR]xmpp\f[R], \f[CR]sieve\f[R],
\f[CR]xmpp\-server\f[R], \f[CR]telnet\f[R], \f[CR]ldap\f[R],
\f[CR]irc\f[R], \f[CR]lmtp\f[R], \f[CR]nntp\f[R], \f[CR]postgres\f[R],
\f[CR]mysql\f[R].
For the latter four you need e.g.\ the supplied OpenSSL or OpenSSL
version 1.1.1.
Please note: MongoDB doesn\[cq]t offer a STARTTLS connection, IRC
currently only works with \f[CR]\-\-ssl\-native\f[R].
\f[CR]irc\f[R] is WIP.
.PP
\f[CR]\-\-xmpphost <jabber_domain>\f[R] is an additional option for
STARTTLS enabled XMPP: It expects the jabber domain as a parameter.
This is only needed if the domain is different from the URI supplied.
.PP
\f[CR]\-\-mx <domain|host>\f[R] tests all MX records (STARTTLS on port
25) from high to low priority, one after the other.
.PP
\f[CR]\-\-ip <ip>\f[R] tests either the supplied IPv4 or IPv6 address
instead of resolving host(s) in \f[CR]<URI>\f[R].
IPv6 addresses need to be supplied in square brackets.
\f[CR]\-\-ip=one\f[R] means: just test the first A record DNS returns
(useful for multiple IPs).
If \f[CR]\-6\f[R] and \f[CR]\-\-ip=one\f[R] was supplied an AAAA record
will be picked if available.
The \f[CR]\-\-ip\f[R] option might be also useful if you want to resolve
the supplied hostname to a different IP, similar as if you would edit
\f[CR]/etc/hosts\f[R] or
\f[CR]/c/Windows/System32/drivers/etc/hosts\f[R].
\f[CR]\-\-ip=proxy\f[R] tries a DNS resolution via proxy.
\f[CR]\-\-ip=proxy\f[R] plus \f[CR]\-\-nodns=min\f[R] is useful for
situations with no local DNS as there\[cq]ll be no DNS timeouts when
trying to resolve CAA, TXT and MX records.
.PP
\f[CR]\-\-proxy <host>:<port>\f[R] does ANY check via the specified
proxy.
\f[CR]\-\-proxy=auto\f[R] inherits the proxy setting from the
environment.
Any hostname supplied will be resolved to the first A record, if it does
not exist the AAAA record is used.
IPv4 and IPv6 addresses can be passed too, the latter \f[I]also\f[R]
with square bracket notation.
Please note that you need a newer OpenSSL or LibreSSL version for IPv6
proxy functionality.
In addition if you want lookups via proxy you can specify
\f[CR]DNS_VIA_PROXY=true\f[R].
OCSP revocation checking (\f[CR]\-S \-\-phone\-out\f[R]) is not
supported by OpenSSL via proxy.
As supplying a proxy is an indicator for port 80 and 443 outgoing being
blocked in your network an OCSP revocation check won\[cq]t be performed.
However if \f[CR]IGN_OCSP_PROXY=true\f[R] has been supplied it will be
tried directly.
Authentication to the proxy is not supported, also no HTTPS or SOCKS
proxy.
.PP
\f[CR]\-6\f[R] does (also) IPv6 checks.
Please note that testssl.sh doesn\[cq]t perform checks on an IPv6
address automatically, because of two reasons: testssl.sh does no
connectivity checks for IPv6 and it cannot determine reliably whether
the OpenSSL binary you\[cq]re using has IPv6 s_client support.
\f[CR]\-6\f[R] assumes both is the case.
If both conditions are met and you in general prefer to test for IPv6
branches as well you can add \f[CR]HAS_IPv6\f[R] to your shell
environment.
Besides the OpenSSL binary supplied IPv6 is known to work with vanilla
OpenSSL >= 1.1.0 and older versions >=1.0.2 in RHEL/CentOS/FC and
Gentoo.
.PP
\f[CR]\-\-ssl\-native\f[R] Instead of using a mixture of bash sockets
and a few openssl s_client connects, testssl.sh uses the latter (almost)
only.
This is faster but provides less accurate results, especially for the
client simulation and for cipher support.
For all checks you will see a warning if testssl.sh cannot tell if a
particular check cannot be performed.
For some checks however you might end up getting false negatives without
a warning.
Thus it is not recommended to use.
It should only be used if you prefer speed over accuracy or you know
that your target has sufficient overlap with the protocols and cipher
provided by your openssl binary.
.PP
\f[CR]\-\-openssl <path_to_openssl>\f[R] testssl.sh tries first very
hard to find the binary supplied (where the tree of testssl.sh resides,
from the directory where testssl.sh has been started from, etc.).
If all that doesn\[cq]t work it falls back to openssl supplied from the
OS (\f[CR]$PATH\f[R]).
With this option you can point testssl.sh to your binary of choice and
override any internal magic to find the openssl binary.
(Environment preset via \f[CR]OPENSSL=<path_to_openssl>\f[R]).
Depending on your test parameters it could be faster to pick the OpenSSL
version which has a bigger overlap in terms of ciphers protocols with
the target.
Also, when testing a modern server, OpenSSL 3.X is faster than older
OpenSSL versions, or on MacOS 18, as opposed to the provided LibreSSL
version.
.SS TUNING OPTIONS
\f[CR]\-\-bugs\f[R] does some workarounds for buggy servers like padding
for old F5 devices.
The option is passed as \f[CR]\-bug\f[R] to openssl when needed, see
\f[CR]s_client(1)\f[R], environment preset via
\f[CR]BUGS=\[dq]\-bugs\[dq]\f[R] (1x dash).
For the socket part testssl.sh has always workarounds in place to cope
with broken server implementations.
.PP
\f[CR]\-\-assuming\-http\f[R] testssl.sh normally does upfront an
application protocol detection.
In cases where HTTP cannot be automatically detected you may want to use
this option.
It enforces testssl.sh not to skip HTTP specific tests (HTTP header) and
to run a browser based client simulation.
Please note that sometimes also the severity depends on the application
protocol, e.g.\ SHA1 signed certificates, the lack of any SAN matches
and some vulnerabilities will be punished harder when checking a web
server as opposed to a mail server.
.PP
\f[CR]\-n, \-\-nodns <min|none>\f[R] tells testssl.sh which DNS lookups
should be performed.
\f[CR]min\f[R] uses only forward DNS resolution (A and AAAA record or MX
record) and skips CAA lookups and PTR records from the IP address back
to a DNS name.
\f[CR]none\f[R] performs no DNS lookups at all.
For the latter you either have to supply the IP address as a target, to
use \f[CR]\-\-ip\f[R] or have the IP address in \f[CR]/etc/hosts\f[R].
The use of the switch is only useful if you either can\[cq]t or are not
willing to perform DNS lookups.
The latter can apply e.g.\ to some pentests.
In general this option could e.g.\ help you to avoid timeouts by DNS
lookups.
\f[CR]NODNS\f[R] is the environment variable for this.
\f[CR]\-\-nodns=min\f[R] plus \f[CR]\-\-ip=proxy\f[R] is useful for
situations with no local DNS as there\[cq]ll be no DNS timeouts when
trying to resolve CAA, TXT and MX records.
.PP
\f[CR]\-\-sneaky\f[R] For HTTP header checks testssl.sh uses normally
the server friendly HTTP user agent \f[CR]TLS tester from ${URL}\f[R].
With this option your traces are less verbose and a Firefox user agent
is being used.
Be aware that it doesn\[cq]t hide your activities.
That is just not possible (environment preset via
\f[CR]SNEAKY=true\f[R]).
.PP
\f[CR]\-\-user\-agent <user agent>\f[R] tells testssl.sh to use the
supplied HTTP user agent instead of the standard user agent
\f[CR]TLS tester from ${URL}\f[R].
.PP
\f[CR]\-\-ids\-friendly\f[R] is a switch which may help to get a scan
finished which otherwise would be blocked by a server side IDS.
This switch skips tests for the following vulnerabilities: Heartbleed,
CCS Injection, Ticketbleed and ROBOT.
The environment variable OFFENSIVE set to false will achieve the same
result.
Please be advised that as an alternative or as a general approach you
can try to apply evasion techniques by changing the variables USLEEP_SND
and / or USLEEP_REC and maybe MAX_WAITSOCK.
.PP
\f[CR]\-\-phone\-out\f[R] Checking for revoked certificates via CRL and
OCSP is not done per default.
This switch instructs testssl.sh to query external \[en] in a sense of
the current run \[en] URIs.
By using this switch you acknowledge that the check might have privacy
issues, a download of several megabytes (CRL file) may happen and there
may be network connectivity problems while contacting the endpoint which
testssl.sh doesn\[cq]t handle.
PHONE_OUT is the environment variable for this which needs to be set to
true if you want this.
.PP
\f[CR]\-\-add\-ca <CAfile>\f[R] enables you to add your own CA(s) in PEM
format for trust chain checks.
\f[CR]CAfile\f[R] can be a directory containing files with a .pem
extension, a single file or multiple files as a comma separated list of
root CAs.
Internally they will be added during runtime to all CA stores.
This is (only) useful for internal hosts whose certificates are issued
by internal CAs.
Alternatively ADDTL_CA_FILES is the environment variable for this.
.SS SINGLE CHECK OPTIONS
Any single check switch supplied as an argument prevents testssl.sh from
doing a default run.
It just takes this and if supplied other options and runs them \- in the
order they would also appear in the default run.
.PP
\f[CR]\-e, \-\-each\-cipher\f[R] checks each of the (currently
configured) 370 ciphers via openssl + sockets remotely on the server and
reports back the result in wide mode.
If you want to display each cipher tested you need to add
\f[CR]\-\-show\-each\f[R].
Per default it lists the following parameters: \f[CR]hexcode\f[R],
\f[CR]OpenSSL cipher suite name\f[R], \f[CR]key exchange\f[R],
\f[CR]encryption bits\f[R], \f[CR]IANA/RFC cipher suite name\f[R].
Please note the \f[CR]\-\-mapping\f[R] parameter changes what cipher
suite names you will see here and at which position.
Also please note that the \f[B]bit\f[R] length for the encryption is
shown and not the \f[B]security\f[R] length, albeit it\[cq]ll be sorted
by the latter.
For 3DES due to the Meet\-in\-the\-Middle problem the bit size of 168
bits is equivalent to the security size of 112 bits.
.PP
\f[CR]\-E, \-\-cipher\-per\-proto\f[R] is similar to
\f[CR]\-e, \-\-each\-cipher\f[R].
It checks each of the possible ciphers, here: per protocol.
If you want to display each cipher tested you need to add
\f[CR]\-\-show\-each\f[R].
The output is sorted by security strength, it lists the encryption bits
though.
.PP
\f[CR]\-s, \-\-std, \-\-categories\f[R] tests certain lists of cipher
suites / cipher categories by strength.
(\f[CR]\-\-standard\f[R] is deprecated.)
Those lists are (\f[CR]openssl ciphers $LIST\f[R], $LIST from below:)
.IP \[bu] 2
\f[CR]NULL encryption ciphers\f[R]: `NULL:eNULL'
.IP \[bu] 2
\f[CR]Anonymous NULL ciphers\f[R]: `aNULL:ADH'
.IP \[bu] 2
\f[CR]Export ciphers\f[R] (w/o the preceding ones): `EXPORT:!ADH:!NULL'
.IP \[bu] 2
\f[CR]LOW\f[R] (64 Bit + DES ciphers, without EXPORT ciphers):
`LOW:DES:RC2:RC4:MD5:!ADH:!EXP:!NULL:!eNULL:!AECDH'
.IP \[bu] 2
\f[CR]3DES + IDEA ciphers\f[R]: `3DES:IDEA:!aNULL:!ADH:!MD5'
.IP \[bu] 2
\f[CR]Obsoleted CBC ciphers\f[R]:
`HIGH:MEDIUM:AES:CAMELLIA:ARIA:!IDEA:!CHACHA20:!3DES:!RC2:!RC4:!AESCCM8:!AESCCM:!AESGCM:!ARIAGCM:!aNULL:!MD5'
.IP \[bu] 2
\f[CR]Strong ciphers with no FS\f[R] (AEAD):
`AESGCM:CHACHA20:CamelliaGCM:AESCCM:ARIAGCM:!kEECDH:!kEDH:!kDHE:!kDHEPSK:!kECDHEPSK:!aNULL'
.IP \[bu] 2
\f[CR]Forward Secrecy strong ciphers\f[R] (AEAD):
`AESGCM:CHACHA20:CamelliaGCM:AESCCM:ARIAGCM:!kPSK:!kRSAPSK:!kRSA:!kDH:!kECDH:!aNULL'
.PP
\f[CR]\-f, \-\-fs, \-\-nsa, \-\-forward\-secrecy\f[R] Checks robust
forward secrecy key exchange.
\[lq]Robust\[rq] means that ciphers having intrinsic severe weaknesses
like Null Authentication or Encryption, 3DES and RC4 won\[cq]t be
considered here.
There shouldn\[cq]t be the wrong impression that a secure key exchange
has been taking place and everything is fine when in reality the
encryption sucks.
Also this section lists the available elliptical curves and Diffie
Hellman groups, as well as FFDHE groups (TLS 1.2 and TLS 1.3).
.PP
\f[CR]\-p, \-\-protocols\f[R] checks TLS/SSL protocols SSLv2, SSLv3, TLS
1.0 through TLS 1.3.
And for HTTP also QUIC (HTTP/3), SPDY (NPN) and ALPN (HTTP/2).
For TLS 1.3 the final version and several drafts (from 18 on) are
tested.
QUIC needs OpenSSL >= 3.2 which can be automatically picked up when in
\f[CR]/usr/bin/openssl\f[R] (or when defined environment variable
OPENSSL2).
If a TLS\-1.3\-only host is encountered and the openssl\-bad version is
used testssl.sh will e.g.\ for HTTP header checks switch to
\f[CR]/usr/bin/openssl\f[R] (or when defined via ENV to OPENSSL2).
Also this will be tried for the QUIC check.
.PP
\f[CR]\-P, \-\-server\-preference, \-\-preference\f[R] displays the
servers preferences: cipher order, with used openssl client: negotiated
protocol and cipher.
If there\[cq]s a cipher order enforced by the server it displays it for
each protocol (openssl+sockets).
If there\[cq]s not, it displays instead which ciphers from the server
were picked with each protocol.
.PP
\f[CR]\-S, \-\-server_defaults\f[R] displays information from the server
hello(s):
.IP \[bu] 2
Available TLS extensions,
.IP \[bu] 2
TLS ticket + session ID information/capabilities,
.IP \[bu] 2
session resumption capabilities,
.IP \[bu] 2
Time skew relative to localhost (most server implementations return
random values).
.IP \[bu] 2
Several certificate information
.RS 2
.IP \[bu] 2
signature algorithm,
.IP \[bu] 2
key size,
.IP \[bu] 2
key usage and extended key usage,
.IP \[bu] 2
fingerprints and serial
.IP \[bu] 2
Common Name (CN), Subject Alternative Name (SAN), Issuer,
.IP \[bu] 2
Trust via hostname + chain of trust against supplied certificates
.IP \[bu] 2
EV certificate detection
.IP \[bu] 2
experimental \[lq]eTLS\[rq] detection
.IP \[bu] 2
validity: start + end time, how many days to go (warning for certificate
lifetime >=5 years)
.IP \[bu] 2
revocation info (CRL, OCSP, OCSP stapling + must staple).
When \f[CR]\-\-phone\-out\f[R] supplied it checks against the
certificate issuer whether the host certificate has been revoked (plain
OCSP, CRL).
.IP \[bu] 2
displaying DNS Certification Authority Authorization resource record
.IP \[bu] 2
Certificate Transparency info (if provided by server).
.RE
.PP
For the trust chain check 5 certificate stores are provided.
If the test against one of the trust stores failed, the one is being
identified and the reason for the failure is displayed \- in addition
the ones which succeeded are displayed too.
You can configure your own CA via ADDTL_CA_FILES, see section
\f[CR]FILES\f[R] below.
If the server provides no matching record in Subject Alternative Name
(SAN) but in Common Name (CN), it will be indicated as this is
deprecated.
Also for multiple server certificates are being checked for as well as
for the certificate reply to a non\-SNI (Server Name Indication) client
hello to the IP address.
Regarding the TLS clock skew: it displays the time difference to the
client.
Only a few TLS stacks nowadays still support this and return the local
clock \f[CR]gmt_unix_time\f[R], e.g.\ IIS, openssl < 1.0.1f.
In addition to the HTTP date you could e.g.\ derive that there are
different hosts where your TLS and your HTTP request ended \[en] if the
time deltas differ significantly.
.PP
\f[CR]\-x <pattern>, \-\-single\-cipher <pattern>\f[R] tests matched
\f[CR]pattern\f[R] of ciphers against a server.
Patterns are similar to \f[CR]\-V pattern , \-\-local pattern\f[R], see
above about matching.
.PP
\f[CR]\-h, \-\-header, \-\-headers\f[R] if the service is HTTP (either
by detection or by enforcing via \f[CR]\-\-assume\-http\f[R].
It tests several HTTP headers like
.IP \[bu] 2
HTTP Strict Transport Security (HSTS)
.IP \[bu] 2
HTTP Public Key Pinning (HPKP)
.IP \[bu] 2
Server banner
.IP \[bu] 2
HTTP date+time
.IP \[bu] 2
Server banner like Linux or other Unix vendor headers
.IP \[bu] 2
Application banner (PHP, RoR, OWA, SharePoint, Wordpress, etc)
.IP \[bu] 2
Reverse proxy headers
.IP \[bu] 2
Web server modules
.IP \[bu] 2
IPv4 address in header
.IP \[bu] 2
Cookie (including Secure/HTTPOnly flags)
.IP \[bu] 2
Decodes BIG IP F5 non\-encrypted cookies
.IP \[bu] 2
Security headers (X\-Frame\-Options, X\-XSS\-Protection,
Expect\-CT,\&...
, CSP headers).
Nonsense is not yet detected here.
.PP
\f[CR]\-c, \-\-client\-simulation\f[R] This simulates a handshake with a
number of standard clients so that you can figure out which client
cannot or can connect to your site.
For the latter case the protocol, cipher and curve is displayed, also if
there\[cq]s Forward Secrecy.
testssl.sh uses a handselected set of clients which are retrieved by the
SSLlabs API.
The output is aligned in columns when combined with the
\f[CR]\-\-wide\f[R] option.
If you want the full nine yards of clients displayed use the environment
variable ALL_CLIENTS.
.PP
\f[CR]\-g, \-\-grease\f[R] checks several server implementation bugs
like tolerance to size limitations and GREASE, see RFC 8701.
This check doesn\[cq]t run per default.
.SS VULNERABILITIES
\f[CR]\-U, \-\-vulnerable, \-\-vulnerabilities\f[R] Just tests all (of
the following) vulnerabilities.
The environment variable \f[CR]VULN_THRESHLD\f[R] determines after which
value a separate headline for each vulnerability is being displayed.
Default is \f[CR]1\f[R] which means if you check for two
vulnerabilities, only the general headline for vulnerabilities section
is displayed \[en] in addition to the vulnerability and the result.
Otherwise each vulnerability or vulnerability section gets its own
headline in addition to the output of the name of the vulnerability and
test result.
A vulnerability section is comprised of more than one check, e.g.\ the
renegotiation vulnerability check has two checks, so has Logjam.
.PP
\f[CR]\-H, \-\-heartbleed\f[R] Checks for Heartbleed, a memory leakage
in openssl.
Unless the server side doesn\[cq]t support the heartbeat extension it is
likely that this check runs into a timeout.
The seconds to wait for a reply can be adjusted with
\f[CR]HEARTBLEED_MAX_WAITSOCK\f[R].
8 is the default.
.PP
\f[CR]\-I, \-\-ccs, \-\-ccs\-injection\f[R] Checks for CCS Injection
which is an openssl vulnerability.
Sometimes also here the check needs to wait for a reply.
The predefined timeout of 5 seconds can be changed with the environment
variable \f[CR]CCS_MAX_WAITSOCK\f[R].
.PP
\f[CR]\-T, \-\-ticketbleed\f[R] Checks for Ticketbleed memory leakage in
BigIP loadbalancers.
.PP
\f[CR]\-\-BB, \-\-robot\f[R] Checks for vulnerability to ROBOT /
(\f[I]Return Of Bleichenbacher\[cq]s Oracle Threat\f[R]) attack.
.PP
\f[CR]\-\-SI, \-\-starttls\-injection\f[R] Checks for STARTTLS injection
vulnerabilities (SMTP, IMAP, POP3 only).
\f[CR]socat\f[R] and OpenSSL >=1.1.0 is needed.
.PP
\f[CR]\-R, \-\-renegotiation\f[R] Tests renegotiation vulnerabilities.
Currently there\[cq]s a check for \f[I]Secure Renegotiation\f[R] and for
\f[I]Secure Client\-Initiated Renegotiation\f[R].
Please be aware that vulnerable servers to the latter can likely be
DoSed very easily (HTTP).
A check for \f[I]Insecure Client\-Initiated Renegotiation\f[R] is not
yet implemented.
.PP
\f[CR]\-C, \-\-compression, \-\-crime\f[R] Checks for CRIME
(\f[I]Compression Ratio Info\-leak Made Easy\f[R]) vulnerability in TLS.
CRIME in SPDY is not yet being checked for.
.PP
\f[CR]\-B, \-\-breach\f[R] Checks for BREACH (\f[I]Browser
Reconnaissance and Exfiltration via Adaptive Compression of
Hypertext\f[R]) vulnerability.
As for this vulnerability HTTP level compression is a prerequisite
it\[cq]ll be not tested if HTTP cannot be detected or the detection is
not enforced via \f[CR]\-\-assume\-http\f[R].
Please note that only the URL supplied (normally \[lq]/\[rq] ) is being
tested.
.PP
\f[CR]\-O, \-\-poodle\f[R] Tests for SSL POODLE (\f[I]Padding Oracle On
Downgraded Legacy Encryption\f[R]) vulnerability.
It basically checks for the existence of CBC ciphers in SSLv3.
.PP
\f[CR]\-Z, \-\-tls\-fallback\f[R] Checks TLS_FALLBACK_SCSV mitigation.
TLS_FALLBACK_SCSV is basically a ciphersuite appended to the Client
Hello trying to prevent protocol downgrade attacks by a Man in the
Middle.
.PP
\f[CR]\-W, \-\-sweet32\f[R] Checks for vulnerability to SWEET32 by
testing 64 bit block ciphers (3DES, RC2 and IDEA).
.PP
\f[CR]\-F, \-\-freak\f[R] Checks for FREAK vulnerability (\f[I]Factoring
RSA Export Keys\f[R]) by testing for EXPORT RSA ciphers
.PP
\f[CR]\-D, \-\-drown\f[R] Checks for DROWN vulnerability
(\f[I]Decrypting RSA with Obsolete and Weakened eNcryption\f[R]) by
checking whether the SSL 2 protocol is available at the target.
Please note that if you use the same RSA certificate elsewhere you might
be vulnerable too.
testssl.sh doesn\[cq]t check for this but provides a helpful link \[at]
censys.io which provides this service.
.PP
\f[CR]\-J, \-\-logjam\f[R] Checks for LOGJAM vulnerability by checking
for DH EXPORT ciphers.
It also checks for \[lq]common primes\[rq] which are preconfigured DH
keys.
DH keys =< 1024 Bit will be penalized.
Also FFDHE groups (TLS 1.2) will be displayed here.
.PP
\f[CR]\-A, \-\-beast\f[R] Checks BEAST vulnerabilities in SSL 3 and TLS
1.0 by testing the usage of CBC ciphers.
.PP
\f[CR]\-L, \-\-lucky13\f[R] Checks for LUCKY13 vulnerability.
It checks for the presence of CBC ciphers in TLS versions 1.0 \- 1.2.
.PP
\f[CR]\-WS, \-\-winshock\f[R] Checks for Winshock vulnerability.
It tests for the absence of a lot of ciphers, some TLS extensions and ec
curves which were introduced later in Windows.
In the end the server banner is being looked at.
.PP
\f[CR]\-4, \-\-rc4, \-\-appelbaum\f[R] Checks which RC4 stream ciphers
are being offered.
.SS OUTPUT OPTIONS
\f[CR]\-q, \-\-quiet\f[R] Normally testssl.sh displays a banner on
stdout with several version information, usage rights and a warning.
This option suppresses it.
Please note that by choosing this option you acknowledge usage terms and
the warning normally appearing in the banner.
.PP
\f[CR]\-\-wide\f[R] Except the \[lq]each cipher output\[rq] all tests
displays the single cipher name (scheme see below).
This option enables testssl.sh to display also for the following
sections the same output as for testing each ciphers: BEAST, FS, RC4.
The client simulation has also a wide mode.
The difference here is restricted to a column aligned output and a
proper headline.
The environment variable \f[CR]WIDE\f[R] can be used instead.
.PP
\f[CR]\-\-mapping <openssl|iana|no\-openssl|no\-iana>\f[R]
.IP \[bu] 2
\f[CR]openssl\f[R]: use the OpenSSL cipher suite name as the primary
name cipher suite name form (default),
.IP \[bu] 2
\f[CR]iana\f[R]: use the IANA cipher suite name as the primary name
cipher suite name form.
.IP \[bu] 2
\f[CR]no\-openssl\f[R]: don\[cq]t display the OpenSSL cipher suite name,
display IANA names only.
.IP \[bu] 2
\f[CR]no\-iana\f[R]: don\[cq]t display the IANA cipher suite name,
display OpenSSL names only.
.PP
Please note that in testssl.sh 3.0 you can still use \f[CR]rfc\f[R]
instead of \f[CR]iana\f[R] and \f[CR]no\-rfc\f[R] instead of
\f[CR]no\-iana\f[R] but it\[cq]ll disappear after 3.0.
.PP
\f[CR]\-\-show\-each\f[R] This is an option for all wide modes only: it
displays all ciphers tested \[en] not only succeeded ones.
\f[CR]SHOW_EACH_C\f[R] is your friend if you prefer to set this via the
shell environment.
.PP
\f[CR]\-\-color <0|1|2|3>\f[R] determines the use of colors on the
screen and in the log file: \f[CR]2\f[R] is the default and makes use of
ANSI and termcap escape codes on your terminal.
\f[CR]1\f[R] just uses non\-colored mark\-up like bold, italics,
underline, reverse.
\f[CR]0\f[R] means no mark\-up at all = no escape codes.
This is also what you want when you want a log file without any escape
codes.
\f[CR]3\f[R] will color ciphers and EC according to an internal (not yet
perfect) rating.
Setting the environment variable \f[CR]COLOR\f[R] to the value achieves
the same result.
Please not that OpenBSD and early FreeBSD do not support italics.
.PP
\f[CR]\-\-colorblind\f[R] Swaps green and blue colors in the output, so
that this percentage of folks (up to 8% of males, see
https://en.wikipedia.org/wiki/Color_blindness) can distinguish those
findings better.
\f[CR]COLORBLIND\f[R] is the according variable if you want to set this
in the environment.
.PP
\f[CR]\-\-debug <0\-6>\f[R] This gives you additional output on the
screen (2\-6), only useful for debugging.
\f[CR]DEBUG\f[R] is the according environment variable which you can
use.
There are six levels (0 is the default, thus it has no effect):
.IP "1." 3
screen output normal but leaves useful debug output in
\f[B]/tmp/testssl.XXXXXX/\f[R] .
The info about the exact directory is included in the screen output in
the end of the run.
.IP "2." 3
lists more what\[cq]s going on, status (high level) and connection
errors, a few general debug output
.IP "3." 3
even slightly more info: hexdumps + other info
.IP "4." 3
display bytes sent via sockets
.IP "5." 3
display bytes received via sockets
.IP "6." 3
whole 9 yards
.PP
\f[CR]\-\-disable\-rating\f[R] disables rating.
Rating automatically gets disabled, to not give a wrong or misleading
grade, when not all required functions are executed (e.g when checking
for a single vulnerabilities).
.SS FILE OUTPUT OPTIONS
\f[CR]\-\-log, \-\-logging\f[R] Logs stdout also to
\f[CR]${NODE}\-p${port}${YYYYMMDD\-HHMM}.log\f[R] in current working
directory of the shell.
Depending on the color output option (see above) the output file will
contain color and other markup escape codes, unless you specify
\f[CR]\-\-color 0\f[R] too.
\f[CR]cat\f[R] and \[en] if properly configured \f[CR]less\f[R] \[en]
will show the output properly formatted on your terminal.
The output shows a banner with the almost the same information as on the
screen.
In addition it shows the command line of the testssl.sh instance.
Please note that the resulting log file is formatted according to the
width of your screen while running testssl.sh.
You can override the width with the environment variable TERM_WIDTH.
.PP
\f[CR]\-\-logfile <logfile>\f[R] or \f[CR]\-oL <logfile>\f[R] Instead of
the previous option you may want to use this one if you want to log into
a directory or if you rather want to specify the log file name yourself.
If \f[CR]logfile\f[R] is a directory the output will put into
\f[CR]logfile/${NODE}\-p${port}${YYYYMMDD\-HHMM}.log\f[R].
If \f[CR]logfile\f[R] is a file it will use that file name, an absolute
path is also permitted here.
LOGFILE is the variable you need to set if you prefer to work
environment variables instead.
Please note that the resulting log file is formatted according to the
width of your screen while running testssl.sh.
You can override the width with the environment variable TERM_WIDTH.
.PP
\f[CR]\-\-json\f[R] Logs additionally to JSON file
\f[CR]${NODE}\-p${port}${YYYYMMDD\-HHMM}.json\f[R] in the current
working directory of the shell.
The resulting JSON file is opposed to \f[CR]\-\-json\-pretty\f[R] flat
\[en] which means each section is self contained and has an identifier
for each single check, the hostname/IP address, the port, severity and
the finding.
For vulnerabilities it may contain a CVE and CWE entry too.
The output doesn\[cq]t contain a banner or a footer.
.PP
\f[CR]\-\-jsonfile <jsonfile>\f[R] or \f[CR]\-oj <jsonfile>\f[R] Instead
of the previous option you may want to use this one if you want to log
the JSON out put into a directory or if you rather want to specify the
log file name yourself.
If \f[CR]jsonfile\f[R] is a directory the output will put into
\f[CR]logfile/${NODE}\-p${port}${YYYYMMDD\-HHMM}.json\f[R].
If \f[CR]jsonfile\f[R] is a file it will use that file name, an absolute
path is also permitted here.
.PP
\f[CR]\-\-json\-pretty\f[R] Logs additionally to JSON file
\f[CR]${NODE}\-p${port}${YYYYMMDD\-HHMM}.json\f[R] in the current
working directory of the shell.
The resulting JSON file is opposed to \f[CR]\-\-json\f[R] non\-flat
\[en] which means it is structured.
The structure contains a header similar to the banner on the screen,
including the command line, scan host, openssl binary used, testssl
version and epoch of the start time.
Then for every test section of testssl.sh it contains a separate JSON
object/section.
Each finding has a key/value pair identifier with the identifier for
each single check, the severity and the finding.
For vulnerabilities it may contain a CVE and CWE entry too.
The footer lists the scan time in seconds.
.PP
\f[CR]\-\-jsonfile\-pretty <jsonfile>\f[R] or \f[CR]\-oJ <jsonfile>\f[R]
Similar to the aforementioned \f[CR]\-\-jsonfile\f[R] or
\f[CR]\-\-logfile\f[R] it logs the output in pretty JSON format (see
\f[CR]\-\-json\-pretty\f[R]) into a file or a directory.
For further explanation see \f[CR]\-\-jsonfile\f[R] or
\f[CR]\-\-logfile\f[R].
.PP
\f[CR]\-\-csv\f[R] Logs additionally to a CSV file
\f[CR]${NODE}\-p${port}${YYYYMMDD\-HHMM}.csv\f[R] in the current working
directory of the shell.
The output contains a header with the keys, the values are the same as
in the flat JSON format (identifier for each single check, the
hostname/IP address, the port, severity, the finding and for
vulnerabilities a CVE and CWE number).
.PP
\f[CR]\-\-csvfile <csvfile>\f[R] or \f[CR]\-oC <csvfile>\f[R] Similar to
the aforementioned \f[CR]\-\-jsonfile\f[R] or \f[CR]\-\-logfile\f[R] it
logs the output in CSV format (see \f[CR]\-\-cvs\f[R]) additionally into
a file or a directory.
For further explanation see \f[CR]\-\-jsonfile\f[R] or
\f[CR]\-\-logfile\f[R].
.PP
\f[CR]\-\-html\f[R] Logs additionally to an HTML file
\f[CR]${NODE}\-p${port}${YYYYMMDD\-HHMM}.html\f[R] in the current
working directory of the shell.
It contains a 1:1 output of the console.
In former versions there was a non\-native option to use \[lq]aha\[rq]
(Ansi HTML Adapter: github.com/theZiz/aha) like
\f[CR]testssl.sh [options] <URI> | aha >output.html\f[R].
This is not necessary anymore.
.PP
\f[CR]\-\-htmlfile <htmlfile>\f[R] or \f[CR]\-oH <htmlfile>\f[R] Similar
to the aforementioned \f[CR]\-\-jsonfile\f[R] or \f[CR]\-\-logfile\f[R]
it logs the output in HTML format (see \f[CR]\-\-html\f[R]) additionally
into a file or a directory.
For further explanation see \f[CR]\-\-jsonfile\f[R] or
\f[CR]\-\-logfile\f[R].
.PP
\f[CR]\-oA <filename>\f[R] / \f[CR]\-\-outFile <filename>\f[R] Similar
to nmap it does a file output to all available file formats: LOG, JSON
pretty, CSV, HTML.
If the filename supplied is equal \f[CR]auto\f[R] the filename is
automatically generated using
`\f[I]N\f[R]\f[I]O\f[R]\f[I]D\f[R]\f[I]E\f[R] − \f[I]p\f[R]{port}\f[I]Y\f[R]\f[I]Y\f[R]\f[I]Y\f[R]\f[I]Y\f[R]\f[I]M\f[R]\f[I]M\f[R]\f[I]D\f[R]\f[I]D\f[R] − \f[I]H\f[R]\f[I]H\f[R]\f[I]M\f[R]\f[I]M\f[R].{EXT}'
with the according extension.
If a directory is provided all output files will put into
\f[CR]<filename>/${NODE}\-p${port}${YYYYMMDD\-HHMM}.{log,json,csv,html}\f[R].
.PP
\f[CR]\-oa <filename>\f[R] / \f[CR]\-\-outfile <filename>\f[R] Does the
same as the previous option but uses flat JSON instead.
.PP
\f[CR]\-\-hints\f[R] This option is not in use yet.
This option is meant to give hints how to fix a finding or at least a
help to improve something.
GIVE_HINTS is the environment variable for this.
.PP
\f[CR]\-\-severity <severity>\f[R] For CSV and both JSON outputs this
will only add findings to the output file if a severity is equal or
higher than the \f[CR]severity\f[R] value specified.
Allowed are \f[CR]<LOW|MEDIUM|HIGH|CRITICAL>\f[R].
WARN is another level which translates to a client\-side scanning error
or problem.
Thus you will always see them in a file if they occur.
.PP
\f[CR]\-\-append\f[R] Normally, if an output file already exists and it
has a file size greater zero, testssl.sh will prompt you to manually
remove the file and exit with an error.
\f[CR]\-\-append\f[R] however will append to this file, without a
header.
The environment variable APPEND does the same.
Be careful using this switch/variable.
A complementary option which overwrites an existing file doesn\[cq]t
exist per design.
.PP
\f[CR]\-\-overwrite\f[R] Normally, if an output file already exists and
it has a file size greater zero, testssl.sh will not allow you to
overwrite this file.
This option will do that \f[B]without any warning\f[R].
The environment variable OVERWRITE does the same.
Be careful, you have been warned!
.PP
\f[CR]\-\-outprefix <fname_prefix>\f[R] Prepend output filename prefix 
before \f[CR]${NODE}\-\f[R].
You can use as well the environment variable FNAME_PREFIX.
Using this any output files will be named
\f[CR]<fname_prefix>\-${NODE}\-p${port}${YYYYMMDD\-HHMM}.<format>\f[R]
when no file name of the respective output option was specified.
If you do not like the separator `\-' you can as well supply a
\f[CR]<fname_prefix>\f[R] ending in `.', \[cq]_\[cq] or `,'.
In this case or if you already supplied `\-' no additional `\-' will be
appended to \f[CR]<fname_prefix>\f[R].
.PP
A few file output options can also be preset via environment variables.
.SS COLOR RATINGS
Testssl.sh makes use of (the eight) standard terminal colors.
The color scheme is as follows:
.IP \[bu] 2
light red: a critical finding
.IP \[bu] 2
red: a high finding
.IP \[bu] 2
brown: a medium finding
.IP \[bu] 2
yellow: a low finding
.IP \[bu] 2
green (blue if COLORBLIND is set): something which is either in general
a good thing or a negative result of a check which otherwise results in
a high finding
.IP \[bu] 2
light green (light blue if COLORBLIND is set) : something which is
either in general a very good thing or a negative result of a check
which otherwise results in a critical finding
.IP \[bu] 2
no color at places where also a finding can be expected: a finding on an
info level
.IP \[bu] 2
cyan: currently only used for \f[CR]\-\-show\-each\f[R] or an additional
hint
.IP \[bu] 2
magenta: signals a warning condition, e.g.\ either a local lack of
capabilities on the client side or another problem
.IP \[bu] 2
light magenta: a fatal error which either requires strict consent from
the user to continue or a condition which leaves no other choice for
testssl.sh to quit
.PP
What is labeled as \[lq]light\[rq] above appears as such on the screen
but is technically speaking \[lq]bold\[rq].
Besides \f[CR]\-\-color=3\f[R] will color ciphers according to an
internal and rough rating.
.PP
Markup (without any color) is used in the following manner:
.IP \[bu] 2
bold: for the name of the test
.IP \[bu] 2
underline + bold: for the headline of each test section
.IP \[bu] 2
underline: for a sub\-headline
.IP \[bu] 2
italics: for strings just reflecting a value read from the server
.SS TUNING via ENV variables and more options
Except the environment variables mentioned above which can replace
command line options here a some which cannot be set otherwise.
Variables used for tuning are preset with reasonable values.
\f[I]There should be no reason to change them\f[R] unless you use
testssl.sh under special conditions.
.IP \[bu] 2
TERM_WIDTH is a variable which overrides the auto\-determined terminal
width size.
Setting this variable normally only makes sense if you log the output to
a file using the \f[CR]\-\-log\f[R], \f[CR]\-\-logfile\f[R] or
\f[CR]\-oL\f[R] option.
.IP \[bu] 2
DEBUG_ALLINONE / SETX: when setting one of those to true testssl.sh
falls back to the standard bash behavior, i.e.\ calling
\f[CR]bash \-x testssl.sh\f[R] it displays the bash debugging output not
in an external file \f[CR]/tmp/testssl\-<XX>.log\f[R]
.IP \[bu] 2
DEBUGTIME: Profiling option.
When using bash\[cq]s debug mode and when this is set to true, it
generates a separate text file with epoch times in
\f[CR]/tmp/testssl\-<XX>.time\f[R].
They need to be concatenated by
\f[CR]paste /tmp/testssl\-<XX>.{time,log}\f[R]
.IP \[bu] 2
EXPERIMENTAL=true is an option which is sometimes used in the
development process to make testing easier.
In released versions this has no effect.
.IP \[bu] 2
ALL_CLIENTS=true runs a client simulation with \f[I]all\f[R] (currently
126) clients when testing HTTP.
.IP \[bu] 2
UNBRACKTD_IPV6: needs to be set to true for some old versions of OpenSSL
(like from Gentoo) which don\[cq]t support [bracketed] IPv6 addresses
.IP \[bu] 2
NO_ENGINE: if you have problems with garbled output containing the word
`engine' you might want to set this to true.
It forces testssl.sh not try to configure openssl\[cq]s engine or a non
existing one from libressl
.IP \[bu] 2
HEADER_MAXSLEEP: To wait how long before killing the process to retrieve
a service banner / HTTP header
.IP \[bu] 2
MAX_WAITSOCK: It instructs testssl.sh to wait until the specified time
before declaring a socket connection dead.
Don\[cq]t change this unless you\[cq]re absolutely sure what you\[cq]re
doing.
Value is in seconds.
.IP \[bu] 2
CCS_MAX_WAITSOCK Is the similar to above but applies only to the CCS
handshakes, for both of the two the two CCS payload.
Don\[cq]t change this unless you\[cq]re absolutely sure what you\[cq]re
doing.
Value is in seconds.
.IP \[bu] 2
HEARTBLEED_MAX_WAITSOCK Is the similar to MAX_WAITSOCK but applies only
to the ServerHello after sending the Heartbleed payload.
Don\[cq]t change this unless you\[cq]re absolutely sure what you\[cq]re
doing.
Value is in seconds.
.IP \[bu] 2
MEASURE_TIME_FILE For seldom cases when you don\[cq]t want the scan time
to be included in the output you can set this to false.
.IP \[bu] 2
STARTTLS_SLEEP is per default set to 10 (seconds).
That\[cq]s the value testssl.sh waits for a string in the STARTTLS
handshake before giving up.
.IP \[bu] 2
MAX_PARALLEL is the maximum number of tests to run in parallel in
parallel mass testing mode.
The default value of 20 may be made larger on systems with faster
processors.
.IP \[bu] 2
MAX_WAIT_TEST is the maximum time (in seconds) to wait for a single test
in parallel mass testing mode to complete.
The default is 1200.
.IP \[bu] 2
HSTS_MIN is preset to 179 (days).
If you want warnings sooner or later for HTTP Strict Transport Security
you can change this.
.IP \[bu] 2
HPKP_MIN is preset to 30 (days).
If you want warnings sooner or later for HTTP Public Key Pinning you can
change this
.IP \[bu] 2
DAYS2WARN1 is the first threshold when you\[cq]ll be warning of a
certificate expiration of a host, preset to 60 (days).
For Let\[cq]s Encrypt this value will be divided internally by 2.
.IP \[bu] 2
DAYS2WARN2 is the second threshold when you\[cq]ll be warning of a
certificate expiration of a host, preset to 30 (days).
For Let\[cq]s Encrypt this value will be divided internally by 2.
.IP \[bu] 2
TESTSSL_INSTALL_DIR is the derived installation directory of testssl.sh.
Relatively to that the \f[CR]bin\f[R] and mandatory \f[CR]etc\f[R]
directory will be looked for.
.IP \[bu] 2
CA_BUNDLES_PATH: If you have an own set of CA bundles or you want to
point testssl.sh to a specific location of a CA bundle, you can use this
variable to set the directory which testssl.sh will use.
Please note that it overrides completely the builtin path of testssl.sh
which means that you will only test against the bundles you point to.
Also you might want to use \f[CR]\[ti]/utils/create_ca_hashes.sh\f[R] to
create the hashes for HPKP.
.IP \[bu] 2
MAX_SOCKET_FAIL: A number which tells testssl.sh how often a TCP socket
connection may fail before the program gives up and terminates.
The default is 2.
You can increase it to a higher value if you frequently see a message
like \f[I]Fatal error: repeated openssl s_client connect problem,
doesn\[cq]t make sense to continue\f[R].
.IP \[bu] 2
MAX_OSSL_FAIL: A number which tells testssl.sh how often an OpenSSL
s_client connect may fail before the program gives up and terminates.
The default is 2.
You can increase it to a higher value if you frequently see a message
like \f[I]Fatal error: repeated TCP connect problems, giving up\f[R].
.IP \[bu] 2
MAX_HEADER_FAIL: A number which tells testssl.sh how often a HTTP GET
request over OpenSSL may return an empty file before the program gives
up and terminates.
The default is 3.
Also here you can increase the threshold when you spot messages like
\f[I]Fatal error: repeated HTTP header connect problems, doesn\[cq]t
make sense to continue\f[R].
.IP \[bu] 2
OPENSSL2 can be used to supply an alternative openssl version.
This only makes sense if you want to amend the supplied version in
\f[CR]bin/\f[R] which lacks TLS 1.3 support with a version which doesn
not and is not in \f[CR]/usr/bin/openssl\f[R].
.IP \[bu] 2
OSSL_SHORTCUT should be set to false when you run interactively and
don\[cq]t want to switch automatically to \f[CR]/usr/bin/openssl\f[R]
(\f[CR]OPENSSL2\f[R]) if you encounter a TLS 1.3\-only host.
.SS RATING
This program has a near\-complete implementation of SSL Labs\[cq]s `\c
.UR https://github.com/ssllabs/research/wiki/SSL-Server-Rating-Guide
SSL Server Rating Guide
.UE \c
'.
.PP
This is \f[I]not\f[R] a 100% reimplementation of the \c
.UR https://www.ssllabs.com/ssltest/analyze.html
SSL Lab\[cq]s SSL Server Test
.UE \c
, but an implementation of the above rating specification, slight
discrepancies may occur.
Please note that for now we stick to the SSL Labs rating as good as
possible.
We are not responsible for their rating.
Before filing issues please inspect their Rating Guide.
.PP
Disclaimer: Having a good grade is \f[B]NOT\f[R] necessarily equal to
having good security!
Don\[cq]t start a competition for the best grade, at least not without
monitoring the client handshakes and not without adding a portion of
good sense to it.
Please note STARTTLS always results in a grade cap to T. Anything else
would lead to a false sense of security.
Use TLS, see also RFC 8314.
The security of STARTTLS is always client determined, i.e.\ checking the
certificate which for SMTP port 25 is often enough not the case.
Also with DANE or MTA\-STS no one can test on the server side whether a
client makes use if it.
.PP
As of writing, these checks are missing:
.IP \[bu] 2
GOLDENDOODLE \- should be graded \f[B]F\f[R] if vulnerable
.IP \[bu] 2
Insecure renegotiation \- should be graded \f[B]F\f[R] if vulnerable
.IP \[bu] 2
Padding oracle in AES\-NI CBC MAC check (CVE\-2016\-2107) \- should be
graded \f[B]F\f[R] if vulnerable
.IP \[bu] 2
Sleeping POODLE \- should be graded \f[B]F\f[R] if vulnerable
.IP \[bu] 2
Zero Length Padding Oracle (CVE\-2019\-1559) \- should be graded
\f[B]F\f[R] if vulnerable
.IP \[bu] 2
Zombie POODLE \- should be graded \f[B]F\f[R] if vulnerable
.IP \[bu] 2
All remaining old Symantec PKI certificates are distrusted \- should be
graded \f[B]T\f[R]
.IP \[bu] 2
Symantec certificates issued before June 2016 are distrusted \- should
be graded \f[B]T\f[R]
.IP \[bu] 2
Anonymous key exchange \- should give \f[B]0\f[R] points in
\f[CR]set_key_str_score()\f[R]
.IP \[bu] 2
Exportable key exchange \- should give \f[B]40\f[R] points in
\f[CR]set_key_str_score()\f[R]
.IP \[bu] 2
Weak key (Debian OpenSSL Flaw) \- should give \f[B]0\f[R] points in
\f[CR]set_key_str_score()\f[R]
.SS Implementing new grades caps or \-warnings
To implement a new grading cap, simply call the
\f[CR]set_grade_cap()\f[R] function, with the grade and a reason:
.IP
.EX
set_grade_cap \[dq]D\[dq] \[dq]Vulnerable to documentation\[dq]
.EE
.PP
To implement a new grade warning, simply call the
\f[CR]set_grade_warning()\f[R] function, with a message:
.IP
.EX
set_grade_warning \[dq]Documentation is always right\[dq]
.EE
.SS Implementing a new check which contains grade caps
When implementing a new check (be it vulnerability or not) that sets
grade caps, the \f[CR]set_rating_state()\f[R] has to be updated
(i.e.\ the \f[CR]$do_mycheck\f[R] variable\-name has to be added to the
loop, and \f[CR]$nr_enabled\f[R] if\-statement has to be incremented)
.PP
The \f[CR]set_rating_state()\f[R] automatically disables rating, if all
the required checks are \f[I]not\f[R] enabled.
This is to prevent giving out a misleading or wrong grade.
.SS Implementing a new revision
When a new revision of the rating specification comes around, the
following has to be done:
.IP \[bu] 2
New grade caps has to be either:
.RS 2
.IP "1." 3
Added to the script wherever relevant, or
.IP "2." 3
Added to the above list of missing checks (if above is not possible)
.RE
.IP \[bu] 2
New grade warnings has to be added wherever relevant
.IP \[bu] 2
The revision output in \f[CR]run_rating()\f[R] function has to updated
.SS EXAMPLES
.IP
.EX
  testssl.sh testssl.sh
.EE
.PP
does a default run on https://testssl.sh (protocols, standard cipher
lists, server\[cq]s cipher preferences, forward secrecy, server
defaults, vulnerabilities, client simulation, and rating.
.IP
.EX
  testssl.sh testssl.net:443
.EE
.PP
does the same default run as above with the subtle difference that
testssl.net has two IPv4 addresses.
Both are tested.
.IP
.EX
  testssl.sh \-\-ip=one \-\-wide https://testssl.net:443
.EE
.PP
does the same checks as above, with the difference that one IP address
is being picked randomly.
Displayed is everything where possible in wide format.
.IP
.EX
  testssl.sh \-6 https://testssl.net
.EE
.PP
As opposed to the first example it also tests the IPv6 part \[en]
supposed you have an IPv6 network and your openssl supports IPv6 (see
above).
.IP
.EX
  testssl.sh \-t smtp smtp.gmail.com:25
.EE
.PP
Checks are done via a STARTTLS handshake on the plain text port 25.
It checks every IP on smtp.gmail.com.
.IP
.EX
    testssl.sh \-\-starttls=imap imap.gmx.net:143
.EE
.PP
does the same on the plain text IMAP port.
.PP
Please note that for plain TLS\-encrypted ports you must not specify the
protocol option when no STARTTLS handshake is offered:
\f[CR]testssl.sh smtp.gmail.com:465\f[R] just checks the encryption on
the SMTPS port, \f[CR]testssl.sh imap.gmx.net:993\f[R] on the IMAPS
port.
Also MongoDB which provides TLS support without STARTTLS can be tested
directly.
.SS RFCs and other standards
.IP \[bu] 2
RFC 2246: The TLS Protocol Version 1.0
.IP \[bu] 2
RFC 2595: Using TLS with IMAP, POP3 and ACAP
.IP \[bu] 2
RFC 2818: HTTP Over TLS
.IP \[bu] 2
RFC 2830: Lightweight Directory Access Protocol (v3): Extension for
Transport Layer Security
.IP \[bu] 2
RFC 3207: SMTP Service Extension for Secure SMTP over Transport Layer
Security
.IP \[bu] 2
RFC 3501: INTERNET MESSAGE ACCESS PROTOCOL \- VERSION 4rev1
.IP \[bu] 2
RFC 4346: The Transport Layer Security (TLS) Protocol Version 1.1
.IP \[bu] 2
RFC 4366: Transport Layer Security (TLS) Extensions
.IP \[bu] 2
RFC 4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport
Layer Security (TLS)
.IP \[bu] 2
RFC 5077: Transport Layer Security (TLS) Session Resumption
.IP \[bu] 2
RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2
.IP \[bu] 2
RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
Certificate Revocation List (CRL) Profile
.IP \[bu] 2
RFC 5321: Simple Mail Transfer Protocol
.IP \[bu] 2
RFC 5746: Transport Layer Security (TLS) Renegotiation Indication
Extension
.IP \[bu] 2
RFC 5804: A Protocol for Remotely Managing Sieve Scripts
.IP \[bu] 2
RFC 6066: Transport Layer Security (TLS) Extensions: Extension
Definitions
.IP \[bu] 2
RFC 6101: The Secure Sockets Layer (SSL) Protocol Version 3.0
.IP \[bu] 2
RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core
.IP \[bu] 2
RFC 6125: Domain\-Based Application Service Identity [..]
.IP \[bu] 2
RFC 6797: HTTP Strict Transport Security (HSTS)
.IP \[bu] 2
RFC 6961: The Transport Layer Security (TLS) Multiple Certificate Status
Request Extension
.IP \[bu] 2
RFC 7469: Public Key Pinning Extension for HTTP (HPKP)
.IP \[bu] 2
RFC 7507: TLS Fallback Signaling Cipher Suite Value (SCSV) for
Preventing Protocol Downgrade Attacks
.IP \[bu] 2
RFC 7627: Transport Layer Security (TLS) Session Hash and Extended
Master Secret Extension
.IP \[bu] 2
RFC 7633: X.509v3 Transport Layer Security (TLS) Feature Extension
.IP \[bu] 2
RFC 7465: Prohibiting RC4 Cipher Suites
.IP \[bu] 2
RFC 7685: A Transport Layer Security (TLS) ClientHello Padding Extension
.IP \[bu] 2
RFC 7905: ChaCha20\-Poly1305 Cipher Suites for Transport Layer Security
(TLS)
.IP \[bu] 2
RFC 7919: Negotiated Finite Field Diffie\-Hellman Ephemeral Parameters
for Transport Layer Security
.IP \[bu] 2
RFC 8143: Using Transport Layer Security (TLS) with Network News
Transfer Protocol (NNTP)
.IP \[bu] 2
RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3
.IP \[bu] 2
RFC 8701: Applying Generate Random Extensions And Sustain Extensibility
(GREASE) to TLS Extensibility
.IP \[bu] 2
RFC 9000: QUIC: A UDP\-Based Multiplexed and Secure Transport
.IP \[bu] 2
W3C CSP: Content Security Policy Level 1\-3
.IP \[bu] 2
TLSWG Draft: The Transport Layer Security (TLS) Protocol Version 1.3
.SS EXIT STATUS
.IP \[bu] 2
0 testssl.sh finished successfully without errors and without ambiguous
results
.IP \[bu] 2
1 testssl.sh has encountered exactly one ambiguous situation or an error
during run
.IP \[bu] 2
1+n same as previous.
The errors or ambiguous results are added, also per IP.
.IP \[bu] 2
50\-200 reserved for returning a vulnerability scoring for system
monitoring or a CI tools
.IP \[bu] 2
242 (ERR_CHILD) Child received a signal from master
.IP \[bu] 2
244 (ERR_RESOURCE) Resources testssl.sh needs couldn\[cq]t be read
.IP \[bu] 2
245 (ERR_CLUELESS) Weird state, either though user options or testssl.sh
.IP \[bu] 2
246 (ERR_CONNECT) Connectivity problem
.IP \[bu] 2
247 (ERR_DNSLOOKUP) Problem with resolving IP addresses or names
.IP \[bu] 2
248 (ERR_OTHERCLIENT) Other client problem
.IP \[bu] 2
249 (ERR_DNSBIN) Problem with DNS lookup binaries
.IP \[bu] 2
250 (ERR_OSSLBIN) Problem with OpenSSL binary
.IP \[bu] 2
251 (ERR_NOSUPPORT) Feature requested is not supported
.IP \[bu] 2
252 (ERR_FNAMEPARSE) Input file couldn\[cq]t be parsed
.IP \[bu] 2
253 (ERR_FCREATE) Output file couldn\[cq]t be created
.IP \[bu] 2
254 (ERR_CMDLINE) Cmd line couldn\[cq]t be parsed
.IP \[bu] 2
255 (ERR_BASH) Bash version incorrect
.SS FILES
\f[B]etc/*pem\f[R] are the certificate stores from Apple, Linux, Mozilla
Firefox, Windows and Java.
.PP
\f[B]etc/client\-simulation.txt\f[R] contains client simulation data.
.PP
\f[B]etc/cipher\-mapping.txt\f[R] provides a mandatory file with mapping
from OpenSSL cipher suites names to the ones from IANA / used in the
RFCs.
.PP
\f[B]etc/tls_data.txt\f[R] provides a mandatory file for ciphers (bash
sockets) and key material.
.SS AUTHORS
Developed by Dirk Wetter, David Cooper and many others, see CREDITS.md .
.SS COPYRIGHT
Copyright © 2012 Dirk Wetter.
License GPLv2: Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it under
the terms of the license, see LICENSE.
.PP
Attribution is important for the future of this project \- also in the
internet.
Thus if you\[cq]re offering a scanner based on testssl.sh as a public
and/or paid service in the internet you are strongly encouraged to
mention to your audience that you\[cq]re using this program and where to
get this program from.
That helps us to get bugfixes, other feedback and more contributions.
.PP
Usage WITHOUT ANY WARRANTY.
USE at your OWN RISK!
.SS LIMITATION
All native Windows platforms emulating Linux are known to be slow.
.SS BUGS
Probably.
Current known ones and interface for filing new ones:
https://testssl.sh/bugs/ .
.SS SEE ALSO
\f[CR]ciphers\f[R](1), \f[CR]openssl\f[R](1), \f[CR]s_client\f[R](1),
\f[CR]x509\f[R](1), \f[CR]verify\f[R](1), \f[CR]ocsp\f[R](1),
\f[CR]crl\f[R](1), \f[CR]bash\f[R](1) and the websites
https://testssl.sh/ and https://github.com/testssl/testssl.sh/ .