Difference between revisions of "O-Saft/Documentation"

Latest revision as of 19:42, 29 December 2019

O-Saft

This is O-Saft's documentation as you get with:

o-saft.pl --help

On Windows following must be used

o-saft.pl --help --v

1 O-Saft

NAME

o-saft.pl - OWASP SSL advanced forensic tool

OWASP SSL audit for testers

DESCRIPTION

This tools lists information about remote target's SSL certificate

and tests the remote target according given list of ciphers.

Note: Throughout this description $0 is used as an alias for the

program name o-saft.pl .

SYNOPSIS

 o-saft.pl [COMMANDS ..] [OPTIONS ..] target [target target ...]

Where [COMMANDS] and [OPTIONS] are described below and target

is a hostname either as full qualified domain name or as IP address.

Multiple commands and targets may be combined.

All commands and options can also be specified in a rc-file, see

RC-FILE below.

I.g. all commands start with a + character and options start with

- or -- characters. Anything else is treated as target name.

QUICKSTART

Before going into a detailed description of the purpose and usage,

here are some examples of the most common use cases:

Show supported (enabled) ciphers of target:

   o-saft.pl +cipher --enabled example.tld

Show supported (enabled) ciphers with their DH parameters:

   o-saft.pl +cipher-dh example.tld

Test all ciphers, even if not supported by local SSL implementation:

   o-saft.pl +cipherall example.tld

Show details of certificate and connection of target:

   o-saft.pl +info example.tld

Check certificate, ciphers and SSL connection of target:

   o-saft.pl +check example.tld

Check connection to target for vulnerabilities:

   o-saft.pl +vulns example.tld

Check for all known ciphers (independant of SSL library):

   o-saft.pl example.tld --range=full
   checkAllCiphers.pl example.tld
   checkAllCiphers.pl example.tld --range=full --v

Get the certificate's Common Name for a bunch of servers:

   o-saft.pl +cn example.tld some.tld other.tld

List more usage examples

   o-saft.pl --help=examples

List all available commands:

   o-saft.pl --help=commands

Get table of contents for complete help

   o-saft.pl --help=toc

Show just one section, for example SECURITY, from help

   o-saft.pl --help=SECURITY

Show all --help=* commands

   o-saft.pl --help=HELP

Search for text in O-Saft's help and show with context

   o-saft -help=your-text

Start the simple GUI

   o-saft.tcl

Start the simple GUI which uses o-saft.pl in a Docker image

   o-saft.tcl --docker

For more specialised test cases, refer to the COMMANDS and OPTIONS

sections below. For more examples please refer to EXAMPLES section.

For more details, please see INSTALLATION below.

WHY?

Why a new tool for checking SSL security and configuration when there

are already a dozen or more such good tools in existence (in 2012)?

Unique features:

working in closed environments, i.e. without internet connection
checking availability of ciphers independent of installed library
checking for all possible ciphers (up to 65535 per SSL protocol)
mainly same results on all platforms.

Currently available tools suffer from some or all of following issues:

lack of tests of unusual SSL certificate configurations
may return different results for the same checks on a given target
missing tests for modern SSL/TLS functionality
missing tests for specific, known SSL/TLS vulnerabilities
no support for newer, advanced, features e.g. CRL, OCSP, EV
limited capability to create your own customised tests

Other reasons or problems are that other tools are either binary or

use additional binaries and hence not portable to other platforms.

In contrast to (all?) most other tools, including openssl, it can be

used to `ask simple questions' like `does target support STS' just by

calling:

   o-saft.pl +hsts_sts example.tld

For more, please see EXAMPLES section below.

If it should run on systems with old software (perl or Perl modules),

please see DEBUG section below.

SECURITY

This tool is designed to be used by people doing security or forensic

analyses. Hence no malicious input is expected.

There are no special security checks implemented. Some parameters are

roughly sanatised according unwanted characters. In particular there

are no checks according any kind of code injection.

Care should be taken, when additional tools and modules are installed

as described in INSTALLATION below. In particular it is recommended

to do these installations into directoies specially prepared for use

with o-saft.pl . No other tools of your system should use these installations

i.e. by accident or because your environment variables point to them.

Note that compilation and installation of additional tools (openssl,

Net::SSLeay, etc.) uses known insecure configurations and features!

This is essential to make o-saft.pl able to check for such insecurities.

It is highly recommended to do these installations and use the tools

on a separate testing system.

DO NOT USE THESE INSTALLATIONS ON PRODUCTIVE SYTEMS.

CONCEPTS

The purpose of O-Saft is to do the work, not to force the user to

learn a new tool or to install "newer" software first.

However, the user "should do something" if necessary depending on the

reported results.

Results

Results of checks are marked yes or no. This leaves the proper

interpretation, if the result is "good" or "bad", to the user.

Background: it is not always possible to rate a result as "good" or

"bad" or "insecure" or whatever. That's why O-Saft can not give the

"the best" or a "proper" recommendation. In practice it depends on

the context what a recommendation or countermeasure should be. That's

why results are marked yes or no if considered "questionable"

or "not good" (for example according other checks).

... more comming soon ...

TECHNICAL INFORMATION

It is important to understand, which provided information is based on

data returned by underlaying (used) libraries and the information

computed directly.

Version 19.11.19 and later

Starting with version 19.11.19 the +cipher command does not use any

external library. Checking for ciphers is done using plain Perl code.

Only other collected SSL/TLS related information requires an external

library, in general libssl.

The description about OpenSSL and libssl below applies only if any of

to the options --ciphermode=openssl or --siphermode=ssleay are given

with the +cipher command.

Therefore following commands and options changed:

+cipher uses internal method
+cipherall command obsolete, automatically changed to +cipher
+cipherraw command obsolete, automatically chnaged to +cipher
--openssl-ciphers --force-openssl changed to --ciphermode=openssl
--openssl=TOOL TOOL only used for +cipher --ciphermode=openssl
--legacy=owasp option obsolete

The commands +cipherall and +cipherraw are "converted" to the new

syntax, as follows:

 VERSION < 19.11.19           VERSION > 19.11.19
 ----------------------------+-------------------------------
 +cipher                      +cipher --ciphermode=ssleay
 +cipher --force-openssl      +cipher --ciphermode=openssl
 +cipherall                   +cipher
 +cipherraw                   +cipher --ciphermode=intern
 ----------------------------+-------------------------------

Version < 19.11.19

Up to version 19.11.19 the default behaviour for the +cipher command

was to use libssl. The commands +cipherall and +cipherraw did not

use any other library as described below.

OpenSSL, libssl, libcrypto

In general the tool uses Perl's Net::SSLeay(3pm) module which itself

is based on libssl and/or libssleay library of the operating system.

It's possible to use other versions of these libraries, see options:

--exe-path=PATH --exe=PATH
--lib-path=PATH --lib=PATH
--envlibvar=NAME

The external openssl(1) is called to extract some information from

its output. The version of openssl can be controlled with following

options:

--openssl=TOOL
--no-openssl
--openssl-ciphers --force-openssl
--exe-path=PATH --exe=PATH
--openssl-cnf=PATH
--openssl-s_client --s_client

OpenSSL is recommended to be used for libssl and libcrypto. Versions

0.9.8k to 1.0.2e (Jan. 2016) are known to work. However, versions be-

for 1.0.0 may not provide all informations.

Some functionality (checks) of O-Saft may be missing or fail, when

openssl versions 1.1.x are used (because functionality was removed).

LibreSSL is not recommended, because some functionallity considered

insecure, has been removed.

For more details, please see INSTALLATION below.

Certificates and CA

All checks according the validity of the certificate chain are based

on the root CAs installed on the system. Note that Net::SSLeay(3pm)

and openssl(1) may have their own rules how and where to find the

root CAs. Please refer to the documentation on your system for these

tools. However, there are folloing options to tweak these rules:

--ca-file=FILE
--ca-path=DIR
--ca-depth=INT

Commands and options

All arguments starting with + are considered COMMANDS for this

tool. All arguments starting with -- are considered OPTIONS for

this tool.

Reading any data from STDIN or here-documents is not yet supported.

It's reserved for future use.

Environment variables

Following environment variables are incorporated:

OPENSSL - if set, full path to openssl executable
OPENSSL_CONF - if set, full path to openssl's openssl.cnf or

directory where to find openssl.cnf

LD_LIBRARY_PATH - used and extended with definitions from options

Requirements

For checking all ciphers and all protocols with +cipherall command,

just perl (5.x) without any modules is required.

For +info and +check (and all related) commands, perl (5.x) with

following modules (minimal version) is required:

IO 1.25 (2011)
IO::Socket:INET 1.37 (2011)
IO::Socket:SSL 1.90 (2013)
Net::DNS 0.66 (2011)
Net::SSLeay 1.49 (2012)

However, it is recommended to use the most recent version of the mod-

ules which then gives more accurate results and less warnings. If the

modules are missing, they can be installed i.e. with:

  cpan Net::SSLeay

Note: if you want to use advanced features of openssl or Net::SSLeay,

please see INSTALLATION section how to compile and install the tools

fully customized.

Also an openssl executable should be available, but is not mandatory.

For checking DH parameters of ciphers, openssl 1.0.2 or newer should

be available. If an older version of openssl is found, we try hard to

extract the DH parameters from the data returned by the server, see

+cipher-dh command.

If you need to run on systems with older perl or Perl module versions

please refer to the DEBUG section for more information.

RESULTS

All output is designed to be easily parsed by postprocessors. Please

see OUTPUT section below for details.

For the results, we have to distinguish those returned by +cipher

command and those from all other tests and checks like +check or

+info command.

+cipher

The cipher checks will return one line for each tested cipher. It

contains at least the cipher name, yes or no whether it's

supported or not, and a security qualification. It may look like:

   AES256-SHA       yes    HIGH
   NULL-SHA         no     weak

Depending on the used --legacy=* option the format may differ

and also contain more information. For details see --legacy=*

option below.

The text for security qualifications are mainly those returned by

openssl (version 1.0.1): LOW, MEDIUM, HIGH and WEAK.

The same texts but with all lower case characters are used if the

qualification was adapted herein. Following rules for adjusting the

qualification were used:

weak:
- all *NULL* ciphers
- all *RC4* ciphers
- all *EXPORT* ciphers
- all *anon* (aka ADH aka DHA) ciphers
- all *CBC* and *CBC3* (aka 3DES) ciphers
low:
high:
- all *AES(128|256)* ciphers
- all *CAMELLIA* ciphers

+check

These tests return a line with a label describing the test and a

test result for it. The idea is to report yes if the result

is considered "secure" and report the reason why it is considered

insecure otherwise. Example of a check considered secure:

       Label of the performed check:           yes

Example of a check considered insecure:

       Label of the performed check:           no (reason why)

Note that there are tests where the results appear confusing when

first viewed, like for www.wi.ld:

       Certificate is valid according given hostname:  no (*.wi.ld)
       Certificate's wildcard does not match hostname: yes

This can for example occur with:

       Certificate Common Name:                *.wi.ld
       Certificate Subject's Alternate Names:  DNS:www.wi.ld

Please check the result with the +info command also to verify

if the check sounds reasonable.

+info

The test result contains detailed information. The labels there

are mainly the same as for the "+check" command.

COMMANDS

There are commands for various tests according the SSL connection to

the target, the targets certificate and the used ciphers.

All commands are preceded by a + to easily distinguish from other

arguments and options. However, some --OPT options are treated as

commands for historical reason or compatibility to other programs.

The most important commands are (in alphabetical order):

+check +cipher +info +http +list +quick +sni +sni_check +version

A list of all available commands will be printed with

   o-saft.pl --help=cmds

The description of all other commands will be printed with

   o-saft.pl --header --help=commands

The summary and internal commands return requested information or the

results of checks. These are described below.

Note that some commands may be a combination of other commands, see:

   o-saft.pl --header --help=intern

The following sub-sections only describe the commands, which do more

than giving a simple information from the target. All other commands

can be listed with:

   $0 --header --help=commands

The final sub-sections Notes about commands describes some notes

about special commands and related commands.

Commands for information about this tool

All these commands will exit after execution (cannot be used together

with other commands).

+ciphers

Show ciphers offered by local SSL implementation.

This commands prints the ciphers in format like openssl ciphers

does. It also accepts the -v and -V option. The --legacy=TYPE

option can be used as described for +list command.

Use +list command for more information according ciphers.

+list

Show all ciphers known by this tool. This includes cryptogrphic

details of the cipher and some internal details about the rating.

In contrast to +ciphers command +list uses TAB characters

instead of spaces to seperate columns. It also prints table header

lines by default.

Different output formats are used for the --legacy option:

--legacy=simple - tabular output of cipher values
--legacy=full - as --legacy=simple but more data
--legacy=openssl - output like with +cipher command
--legacy=ssltest - output like ssltest --list

+VERSION

Just show version and exit.

+version

Show version information for both the program and the Perl modules

that it uses, then exit.

Use --v option to show more details.

+libversion

Show version of openssl.

+quit

Show internal data and exit, used for testing and debugging only.

Please see TESTING below.

Commands to check SSL details

Following (summary, internal) commands are simply a shortcut for

a list of other commands. For details of the list use:

   o-saft.pl --help=intern

+check

Check the SSL connection for security issues. Implies +cipher .

+host +target

Print details about the targets hostname, DNS, etc.

These details are usually printed only for the +check and +info

command, but not for any individual command.

+http

Perform HTTP checks (like STS, redirects etc.).

+info

Overview of most important details of the SSL connection.

Use --v option to show details also, which span multiple lines.

+info--v

Overview of all details of the SSL connection. This is a shortcut

for all commands listed below but not including +cipher.

This command is intended for debugging as it prints some details

from the used Net::SSLinfo module.

+quick

Quick overview of checks. Implies --enabled and --label=short.

+pfs

Check if servers offers ciphers with prefect forward secrecy (PFS)

+protocols

Check for protocols supported by target.

+vulns

Check for various vulnerabilities.

+sts +hsts

Various checks according STS HTTP header.

This option implies --http, means that --no-http is ignored.

+sni

Check for Server Name Indication (SNI) usage.

+sni_check +check_sni

Check for Server Name Indication (SNI) usage and validity of all

names (CN, subjectAltName, FQDN, etc.).

+bsi

Various checks according BSI TR-02102-2 and TR-03116-4 compliance.

+ev

Various checks according certificate's extended Validation (EV).

Hint: use option --v --v to get information about failed checks.

+sizes

Check length, size and count of some values in the certificate.

+s_client

Dump data retrieved from openssl s_client ... call. Should be

used for debugging only.

It can be used just like openssl itself, for example:

        openssl s_client -connect host:443 -no_sslv2

+dump

Dumps internal data for SSL connection and target certificate.

This is mainly for debugging and should not be used together with

other commands (except +cipher).

Each key-value pair is enclosed in #{ and #} .

Using --trace --trace dumps data of Net::SSLinfo too.

+exec

Command used internally when requested to use other libraries.

This command should not be used directly.

Commands to test ciphers provided by target

Beside the description of the commands itself here, please see also

#Notes about commands below.

+cipher

Check target for ciphers, either all ciphers or ciphers specified

with --cipher=* option.

Note that ciphers not supported by the local SSL implementation

are not checked by default, use +cipherall or +cipherraw command for that.

Use --v option to see all ciphers being checked.

+cipherraw

Check target for all possible ciphers.

Does not depend on local SSL implementation.

In contrast to +cipher this command has some options to tweak

the cipher tests, connection results, and some strange behaviours

of the target. See #Options for cipherall and cipherraw command for details.

+cipherall

Same as +cipherraw but ouput format similat to +cipher command.

+cipher-default

Lists the cipher selected by the server for each protocol sometimes

referred to as "default cipher".

For each protocol the two selected ciphers are shown, one returned

by the server if the cipher list in the ClientHello is sorted with

the strongest cipher first, and one returned if the cipher list in

the ClientHello is sorted with strongest cipher last.

See #Notes about commands for details.

+cipher-dh

Checked target for ciphers. All ciphers supported by the server are

printed with their DH or ECDH paramaters (if available).

ciphers.

+cipher-null +null

Check if target accepts NULL ciphers.

+cipher-adh +adh

Check if target accepts ciphers with anonymous key exchange.

+cipher-exp +export

Check if target accepts EXPORT ciphers.

+cipher-cbc +cbc

Check if target accepts CBC ciphers.

+cipher-des +des

Check if target accepts DES ciphers.

+cipher-rc4

Check if target accepts RC4 ciphers.

+cipher-edh +edh

Check if target supports ephemeral ciphers.

+cipher-pfs

Check if target supports ciphers with PFS.

+cipher-strong

Check if target selects strongest cipher.

+cipher-weak

Check if target selects weak cipher (oposite of +cipher-strong).

Discrete commands to test SSL connection and certificate details

Discrete commands, please see:

   o-saft.pl --help=commands

Notes about commands

+cipher vs. +cipherall

+cipher can only check for ciphers - more precise: cipher suites -

provided by the local SSL implementation (i.e. libssl).

+cipherall can check for any cipher, as it just uses the cipher's

integer value in the range 0 .. 65532.

+cipherall vs. +cipherraw

These commands are identical, just the output format is different.

+cipher vs. +cipher-default

Both commands show the default cipher foreach protocol.

+cipher lists a summary of ciphers selected by the server for each

protocol requested by the user (for example by using options like:

--sslv3 --tlsv1 etc.). When the --v option is used, all selected

ciphers for all known protocols are listed. This summary focuses on

counts for various ciphers.

+cipher-default lists the selected cipher by the server for each

protocol.

+cipher-selected vs. +cipher-default

+cipher-selected lists the cipher selected by the server if no particular

protocol was specified and the system's default cipher list is send

in the ClientHello to the server.

+cipher-default lists the selected cipher by the server for each

protocol.

+cipher-strong vs. +cipher-default

+cipher-strong shows the result of the check if strong ciphers are

preferred by the server. It is a check command.

+cipher-default lists the cipher selected by the server for each

protocol. It is a information command.

It is not possible to check if a server uses 'SSLHonorCipherOrder'.

Even if it is used (switched on), it is not possible to check the

specified order of the ciphers.

I. g. it is expected that the order is according the cipher suite's

strength, meaning the most strongest first, and the weakest last.

It does not make sense to use an order where a weak cipher preceeds

a stronger one. Such a (mis-)configuration should be detected.

Having this in mind, the algorithm to detect a proper cipher order

is as simply as follows:

   1. pass sorted cipher list with strongest cipher first
   2. pass sorted cipher list with strongest cipher last

if the server returns the same cipher for both checks, it's assumed

that it prefers to use the most strongest cipher. In this case it's

obvious that 'SSLHonorCipherOrder' is set (exceptions see below).

+cipherall uses a more accurate algorithm to detect the server's

cipher order.

Exceptions:

If either, the server or the client, uses only one cipher suite in

the list, SSLHonorCipherOrder cannot be detected at all.

The same happens, if only one cipher in the client's list matches a

cipher in the server's list.

+extensions vs. +tlsextensions

+extensions shows the "Certificate extensions" and +tlsextensions

will show the TLS protocol extensions.

Use +tlsextdebug to show more informations about the TLS protocol

extensions.

+http2 +spdy +spdy3 +spdy31 +spdy4 +prots

These commands are just an alias for the +protocols command.

+hostname vs. +wildhost vs. +altname vs. +rfc_2818

The commands +cn and +altname print the information stored in

the certificate.

The command +hostname checks if the given hostname matches the CN

value in the certificate. Note that wildcard names in the CN, only

allow to contain one '*'.

The command +wildcard checks if the given hostname does not match

any name specified in the certificate's "subjectAltname". This check

is useful if the certificate and the configuration must comply to

RFC 6125 or EV certificates.

OPTIONS

All options are written in lowercase. Words written in all capital in

the description here is text provided by the user.

Options for help and documentation

--h

--help

WYSIWYG

--help=help

Show available options to show descriptions (this Options section).

--help=cmds

Show available commands.

--help=commands

Show available commands with short description.

--help=opt

Show available options; short form.

--help=options

Show available options with their description.

--help=checks

Show available checks.

--help=tools

Description of tools around O-Saft, when, where and how to use.

--help=cmd

Show additional and user specified commands.

--help=cfg-cmd

Show additional and user specified commands. Output can be used in

RC-FILE or as option.

--help=check-cfg --help=cfg-check

Show texts used as labels in output for checks (see +check) ready

for use in RC-FILE or as option.

--help=data

Show available informations.

--help=data-cfg --help=cfg-data --help=cfg-info

Show texts used as labels in output for data (see +info) ready

for use in RC-FILE or as option.

--help=hint

Show texts used in hint messages.

--help=hint-cfg --help=cfg-hint

Show texts used in hint messages ready for use in RC-FILE or as

option.

--help=text

Show texts used in various messages.

--help=text-cfg --help=cfg-text

Show texts used in various messages ready for use in RC-FILE or

as option.

--help=legacy

Show possible legacy formats (used as value in --legacy=KEY).

--help=compliance

Show available compliance checks.

--help=intern

Show internal commands.

--help=range

Show list of cipherranges (see #--cipherrange=RANGE--cipherrange=RANGE).

--help=alias

Show alias for commands and options.

--help=pattern

Show list of cipher pattern (used for --cipher=CIPHER).

--help=score

Show score value for each check.

Value is printed in format to be used for --cfg_score=KEY=SCORE.

Note that the sequence of options is important. Use the options

--trace and/or --cfg_score=KEY=SCORE before --help=score.

--help=toc --help=content

Show headlines from help textsUseful to get an overview.

--help=SECTION

Show SECTION from documentation, see --help=toc for a list.

Example:

     o-saft.pl --help=EXAMPLES

--help=regex

Show regular expressions used internally.

--help=gen-html

Show help text in HTML format.

--help=gen-pod

Show help text in POD format.

--help=gen-wiki

Show help text in mediawiki format.

--help=gen-cgi

Generate HTML page with o-saft.cgi as form action..

--help=error --help=warning --help=problem

Show KNOWN PROBLEMS section with description of known error and

warning messages.

--help=FAQ

Show KNOWN PROBLEMS and LIMITATIONS section.

--help=glossar

Show common abbreviation used in the world of security.

--help=links

Show list of URLs related to SSL/TLS.

--help=rfc

Show list of RFC related to SSL/TLS.

--help=todo

Show known problems and bugs.

--help=exit

Show possible --exit=KEY options. Used for debugging only.

--help=program.code

For developers.

Options for all commands (general)

--dns

Do DNS lookups to map given hostname to IP, do a reverse lookup.

--no-dns

Do not make DNS lookups.

Note that the corresponding IP and reverse hostname may be missing

in some messages then.

--host=HOST

Specify HOST as target to be checked. Legacy option.

--port=PORT

Specify target's PORT to be used. Legacy option.

--host=HOST --port=PORT HOST:PORT HOST

When giving more than one HOST argument, the sequence of the given

HOST argument and the given --port=PORT and the given --host=HOST

options are important.

The rule how ports and hosts are mapped is as follows:

* HOST:PORT arguments are used as is (connection to HOST on PORT)

* only HOST is given, then previous specified --port=PORT is used

Note that URLs are treated as HOST:PORT, if they contain a port.

Example:

   o-saft.pl +cmd host-1 --port 23 host-2 host-3:42 host-4

will connect to:

      host-1:443
      host-2:23
      host-3:42
      host-4:23

--proxyhost=PROXYHOST --proxy=PROXYHOST:PROXYPORT

Make all connection to target using PROXYHOST.

Also possible is: --proxy=PROXYUSER:PROXYPASS@PROXYHOST:PROXYPORT

--proxyport=PROXYPORT

Make all connection to target using PROXYHOST:PROXYPORT.

--proxyuser=PROXYUSER

Specify username for proxy authentication.

--proxypass=PROXYPASS

Specify password for proxy authentication.

--proxy=PROXYUSER:PROXYPASS@PROXYHOST:PROXYPORT is also possible.

--starttls

Use STARTTLS command to start a TLS connection via SMTP.

This option is a shortcut for --starttls=SMTP

--starttls=PROT

Use STARTTLS command to start a TLS connection via protocol.

PROT may be any of: SMTP, IMAP, IMAP2, POP3, FTPS, LDAP, RDP, XMPP

For --starttls=SMTP see --dns-mx also to use MX records instead

of host

--starttls-delay=SEC

Number of seconds to wait before sending a packet, to slow down the

STARTTLS requests. Default is 0.

This may prevent blocking of requests by the target due to too much

or too fast connections.

Note: In this case there is an automatic suspension and retry with

a longer delay.

--cgi, --cgi-exec

Internal use for CGI mode only.

Options for SSL tool

--no-rc

Do not read RC-FILE .

--rc

Read RC-FILE if exists, from directory where program was found.

--rc=path/to/FILE

Read RC-FILE path/to/FILE if exists.

--exitcode

The exit status code will be greater 0, if any of following applies:

any check returns no, except if no (<<...>>)
insecure protocols are available
insecure ciphers are supported
ciphers without PFS are supported

In particular, the status code will be the total count of all these

checks. The status code will also be printed at end, like:

   # EXIT 23

Parts of these checks can be diasabled, see --exitcode-* options

below.

Use --v or --exitcode-v to see details about the performed checks.

Functionality implemented experimental, may change in future.

--exitcode-v

Print information about performed checks.

--exitcode-quiet

Do not print status code at end like # EXIT 23.

--exitcode-no-checks

Do not count checks with result 'no' for --exitcode .

--exitcode-no-low --exitcode-no-weak --exitcode-no-medium

Do not count LOW, WEAK or MEDIUM security ciphers for --exitcode .

--exitcode-no-ciphers

Do not count any ciphers for --exitcode .

--exitcode-no-pfs

Do not count ciphers without PFS for --exitcode .

--openssl-s_client --s_client

Use openssl s_slient ... call to retrieve more informations from

the SSL connection. This is disabled by default on Windows because

of performance problems. Without this option (default on Windows !)

following informations are missing:

      compression, expansion, renegotiation, resumption,
      selfsigned, verify, chain, protocols, DH parameters

See Net::SSLinfo for details.

If used together with --trace, s_client data will also be printed

in debug output of Net::SSLinfo.

--no-openssl

Do not use external openssl tool to retrieve informations. Use of

openssl is disabled by default on Windows.

Note that this results in some missing informations, see above.

--openssl=TOOL

TOOL can be a path to openssl executable; default: openssl

--openssl-cnf=FILE --openssl-conf=FILE

FILE path of directory or full path of openssl.cnf

If set, environment variable OPENSSL_CONF will be set to given path

(or file) when openssl(1) is started. Please see openssl's man page

for details about specifying alternate openssl.cnf files.

--openssl-ciphers --force-openssl

Use openssl to check for supported ciphers; default: IO::Socket

This option forces to use openssl s_slient -connect CIPHER .. to

check if a cipher is supported by the remote target. This is useful

if the --lib=PATH option doesn't work (for example due to changes

of the API or other incompatibilities).

--exe-path=PATH --exe=PATH

PATH is a full path where to find openssl.

--lib-path=PATH --lib=PATH

PATH is a full path where to find libssl.so and libcrypto.so

See HACKER's INFO below for a detailed description how it works.

--envlibvar=NAME

NAME is the name of a environment variable containing additional

paths for searching dynamic shared libraries.

Default is LD_LIBRARY_PATH .

Check your system for the proper name, i.e.:

DYLD_LIBRARY_PATH, LIBPATH, RPATH, SHLIB_PATH .

--ssl-error

The connection to a target may fail, or even block, due to various

reasons, for example lost network at all, blocking at firewall, etc.

In particular when checking ciphers with +cipher , this may result

in long delays until results are printed.

Using this option stops trying to do more connections to the target

when --ssl-error-max=CNT consecutive errors occoured, or if the total

amount of errors increases --ssl-error-total=CNT.

--ssl-error-max=CNT

Max. amount of consecutive errors (default: 5).

--ssl-error-timeout=SEC

Timeout in seconds when a failed connection is treated as error and

then counted (default: 1).

--ssl-error-total=CNT

Max. total amount of errors (default: 10).

--ssl-lazy

I.g. this tools tries to identify available functionality according

SSL versions from the underlaying libraries. Unsupported versions

are then disables and a warning is shown.

Unfortunately some libraries have not implemented all functions to

check availability of a specific SSL version, which then results in

a compile error.

This option disables the strict check of availability.

If the underlaying library doesn't support the required SSL version

at all, following error may occour:

      Can't locate auto/Net/SSLeay/CTX_v2_new.al in @INC ...

--timeout=SEC

Timeout in seconds when connecting to the target (default: 2).

-v

Print list of ciphers in style like: openssl ciphers -v.

Option used with +ciphers command only.

-V

Print list of ciphers in style like: openssl ciphers -V.

Option used with +ciphers command only.

Options for SSL connection to target

--ciphermode=MODE

Following MODEs are supported:

intern scan for ciphers using internal method; (default)
openssl scan for ciphers using external openssl executable
ssleay scan for ciphers using IO::Socket and Net::SSLeay
dump same as intern but print all cipher informations,

useful when postprocessed by contrib/* tools

--cipher=CIPHER

CIPHER can be any string accepted by openssl or following:

yeast use all ciphers from list defined herein, see +list

Beside the cipher names accepted by openssl, CIPHER can be the name

of the constant or the (hex) value as defined in openssl's files.

Currently supported are the names and constants of openssl 1.0.1k .

Example:

--cipher=DHE_DSS_WITH_RC4_128_SHA
--cipher=0x03000066
--cipher=66

will be mapped to DHE-DSS-RC4-SHA

Note: if more than one cipher matches, just one will be selected.

Default is ALL:NULL:eNULL:aNULL:LOW as specified in Net::SSLinfo

--socket-reuse

TCP socket will be reused for next connection attempt even if SSL

connection failed.

--no-socket-reuse

Close TCP socket and then reopen for next connection attempt if SSL

connection failed.

This is useful for some servers which may return an "TLS alert" if

the connection fails and then fail again on the same socket.

--ignore-no-connect

A simple check if the target can be connected will be performed by

default. If this check fails, the target will be ignored, means no

more reuqested checks will be done. As this connection check some-

times fails due to various reasons, the check can be disabled using

this option.

--no-md5-cipher

Do not use *-MD5 ciphers for other protocols than SSLv2.

This option is only effective with +cipher command.

The purpose is to avoid warnings from IO::Socket::SSL(3pm) like:

        Use of uninitialized value in subroutine entry at lib/IO/Socket/SSL.pm line 430.

which occours with some versions of IO::Socket::SSL(3pm) when a

-MD5 ciphers will be used with other protocols than SSLv2.

Note that these ciphers will be checked for SSLv2 only.

--SSL, -protocol SSL

--no-SSL

SSL can be any of:

ssl, ssl2, ssl3, sslv2, sslv3, tls1,

tls1, tls11, tls1.1, tls1-1, tlsv1, tlsv11, tlsv1.1, tlsv1-1

(and similar variants for tlsv1.2).

For example --tls1 --tlsv1 --tlsv1_1 are all the same.

(--SSL variants): Test ciphers for this SSL/TLS version.

(--no-SSL variants): Don't test ciphers for this SSL/TLS version.

--no-tcp

Shortcut for:

--no-sslv2 --no-sslv3 --no-tlsv1 --no-tlsv11 --no-tlsv12 --no-tlsv13

--tcp

Shortcut for: --sslv2 --sslv3 --tlsv1 --tlsv11 --tlsv12 --tlsv13

--no-udp

Shortcut for:

--no-dtlsv09 --no-dtlsv1 --no-dtlsv11 --no-dtlsv12 --no-dtlsv13

--udp

Shortcut for: --dtlsv09 --dtlsv1 --dtlsv11 --dtlsv12 --dtlsv13

--nullsslv2

This option forces to assume that SSLv2 is enabled even if the

target does not accept any ciphers.

The target server may accept connections with SSLv2 but not allow

any cipher. Some checks verify if SSLv2 is enabled at all, which

then would result in a failed test.

The default behaviour is to assume that SSLv2 is not enabled if no

ciphers are accepted.

--http

Make a HTTP request if cipher is supported.

If used twice debugging will be enabled using environment variable

HTTPS_DEBUG .

--no-http

Do not make HTTP request.

--sni

Make SSL connection in SNI mode.

--no-sni

Do not make SSL connection in SNI mode (default: SNI mode).

--sni-toggle --toggle-sni

Test with and witout SNI mode (+cipherall only).

--force-sni

Do not check if SNI seems to be supported by Net::SSLeay(3pm).

Older versions of openssl and its libries do not support SNI or the

SNI support is implemented buggy. By default it's checked if SNI is

properly supported. With this option this check can be disabled.

Be warned that this may result in improper results.

--servername=NAME

--sni-name=NAME

If in SNI mode is active, see --sni above, NAME is used instead of

hostname for connections to the target. If SNI mode is not active,

see --no-sni above, NAME is not used. The default is undefined,

which forces to use the given FQDN.

This is useful, for example when an IP instead of a FQDN was given,

where a correct hostname (i.g. a FQDN) needs to be specified.

Note: i.g. there is no need to use this option, as a correct value

for the SNI name will be choosen automatically (except for IPs).

However, it is kind of fuzzing ...even setting to an empty string

is possible.

Limitation: the same NAME is used for all targets, if more than

one target was specified.

--no-cert

Do not get data from target's certificate, return empty string.

--no-cert --no-cert

Do not get data from target's certificate, return default string

of Net::SSLinfo (see --no-cert-text TEXT option).

--no-cert-text=TEXT

Set TEXT to be returned from Net::SSLinfo.pm if no certificate

data is collected due to use of --no-cert.

--ca-depth=INT

Check certificate chain to depth INT (like openssl's -verify).

--ca-file=FILE

Use FILE with bundle of CAs to verify target's certificate chain.

--ca-path=DIR

Use DIR where to find CA certificates in PEM format.

--no-nextprotoneg

Do not use -nextprotoneg option for openssl.

--proto-alpn=NAME

Name of protocol to be added to list of applcation layer protocols

(ALPN), which is used for any connection to the targets.

See --cipher-alpn=NAME also.

--proto-npn=NAME

Name of protocol to be added to list of next protocol negotiations

(NPN), which is used for any connection to the targets.

See --cipher-npn=NAME also.

--ssl-compression --compression

Use SSL option "compression" for connection.

--no-ssl-compression --no-compression

Use SSL option "no compression" for connection (default: don't use)

--no-reconnect

Do not use -reconnect option for openssl.

--no-tlsextdebug

Do not use -tlsextdebug option for openssl.

--sclient-opt=VALUE

Argument or option passed to openssl s_client command.

Options for +cipher command

--cipher-alpn=NAME

Name of protocol to be added to list of applcation layer protocols

(ALPN), which is used for cipher checks.

--cipher-alpn=, sets empty list.
--cipher-alpn=,, sets list to empty element "".

--cipher-npn=NAME

Name of protocol to be added to list of next protocol negotiations

(NPN), which is used for cipher checks.

--cipher-lpn=, sets empty list.
--cipher-lpn=,, sets list to empty element "".

Note: setting empty list or element most likely does not work with

openssl executable (i.e. --force-openssl).

--cipher-curve=NAME

Name of ecliptic curve to be added to list of ecliptic curves (EC),

which is used for cipher checks.

--cipher-curve=, sets empty list.
--cipher-curve=,, sets list to empty element "".

Note: setting empty list or element most likely does not work with

openssl executable (i.e. --force-openssl).

Options for cipherall and cipherraw command

--range=RANGE

--cipherrange=RANGE

Specify range of cipher constants to be tested by +cipherall .

Following RANGEs are supported (see also --cipherrange=RANGE):

rfc all ciphers defined in various RFCs
shifted rfc, shifted by 64 bytes to the right
long like rfc but more lazy list of
huge all constants 0x03000000 .. 0x0300FFFF
safe all constants 0x03000000 .. 0x032FFFFF
full all constants 0x03000000 .. 0x0300FFFF
SSLv2 all ciphers according RFC for SSLv2

Note: SSLv2 is the internal list used for testing SSLv2 ciphers.

It does not make sense to use it for other protocols; however ...

--slow-server-delay=SEC

Additional delay in seconds after the server is connected using a

proxy or before starting STARTTLS.

This is useful when connecting via slow proxy chains or connecting

to slow servers before sending the STARTTLS sequence.

--ssl-maxciphers=CNT

Maximal number of ciphers sent in a sslhello (default: 32).

--ssl-double-reneg

Send SSL extension "reneg_info" even if list of ciphers includes

TLS_EMPTY_RENEGOTIATION_INFO_SCSV (default: do not include)

--ssl-nodata-nocipher

Do not abort testing for next cipher when the target responds with

"NoData" times out. Useful for TLS intolerant servers.

By default testing for ciphers is aborted when the target responds

with "noData message.

--ssl-use-ecc

Use supported elliptic curves. Default on.

--ssl-use-ec-point

Use TLS "ec_point_formats" extension. Default on.

--ssl-use-reneg

Test for ciphers with "secure renegotiation" flag set.

Default: don't set "secure renegotiation" flag.

--ssl-retry=CNT

Number of retries when connection timed-out (default: 2).

--ssl-timeout=SEC

Number of seconds to wait until connection is qualified as timeout.

--dns-mx, --mx

Get DNS MX records for given target and check the returned targets.

(only useful with --starttls=SMTP)

Options for checks and results

Options used for +check command:

--enabled

Only print result for ciphers accepted by target.

--disabled

Only print result for ciphers not accepted by target.

--ignorecase

Checks are done case insensitive.

--no-ignorecase

Checks are done case sensitive. Default: case insensitive.

Currently only checks according CN, alternate names in the target's

certificate compared to the given hostname are effected.

--ignore-no-reply

When checking for the TLS "heartbeat" extension, the server may not

respond at all, which would result in a "no reply" message. This

marks the check for +heartbleed as no.

I.g. a server is not vulnerable to the heartbleed attack if the

TLS "heartbeat" extension is disabled. Hence the check result no

may be mis-leading. This option treats the "no reply" result as

"not vulnerable" and returns yes then.

Note: if the server does not respond for this check, does not mean

that the "heartbeat" extension is switched off. If unsure, disable

this lazy check with --no-ignore-no-reply .

Options for output format

--label=TYPE

Defines the format of the descriptive text(label) for +check and

+info command.

Following TYPEs are supported:

--label=long

Prints full text for labels:

 Certificate Common Name:  some.tld

--label=short

Prints short less descriptive text for labels:

 Common Name:              some.tld

--label=key

Internal format: print name of key instead of text as label. Key is

Prints name of key instead of text as label. The key is that of the

internal data structure(s).

 [cn]                      some.tld

--legacy=TOOL

For compatibility with other tools, the output format used for the

result of the +cipher command can be adjusted to mimic the format

of other SSL testing tools.

The argument to the --legacy=TOOL option is the name of the tool

to be simulated.

Following TOOLs are supported:

sslaudit format of output similar to sslaudit
sslcipher format of output similar to ssl-cipher-check
ssldiagnos format of output similar to ssldiagnos
sslscan format of output similar to sslscan
ssltest format of output similar to ssltest
ssltestg format of output similar to ssltest -g
ssltest-g format of output similar to ssltest -g
sslyze format of output similar to sslyze
ssl-cipher-check same as sslcipher
ssl-cert-check format of output similar to ssl-cert-check
testsslserver format of output similar to TestSSLServer.jar
thcsslcHeck format of output similar to THCSSLCheck

Note that these legacy formats only apply to output of the checked

ciphers. Other texts like headers and footers are adapted slightly.

Please do not expect identical output as the TOOL when using these

options, it's a best guess and should be parsable in a very similar

way.

--legacy=TYPE

--legacy=compact

Internal format: mainly avoid tabs and spaces format is as follows:

Some Label:<-- anything right of colon is data

--legacy=full

Internal format: pretty print each label in its own line, followed

by data prepended by tab character (useful for +info only).

--legacy=owasp

Results for cipher checks use rating from OWASP Cipher Cheat Sheet.

--legacy=quick

Internal format: use tab as separator; ciphers are printed with bit

length (implies --tab).

--legacy=simple

Internal default format.

--format=FORM

This option is used to specify the format of the result lines. This

covers the value of the result line only.

raw Print raw data as passed from Net::SSLinfo .

Note: all data will be printed as is, without additional label

or formatting. It's recommended to use the option in conjunction

with exactly one command. Otherwise the user needs to know how

to "read" the printed data.

hex Convert some data to hex: 2 bytes separated by :.
0x Convert some data with hex values:

2 bytes preceded by 0x and separated by a space.

/x Same as --format=\x
\x Convert some data with hex values:

2 bytes preceded by \x and no separating char.

--header

Print formatting header. Default for +check, +info, +quick.

and +cipher only.

--no-header

Do not print formatting header.

Useful if raw output should be passed to other programs.

Note: must be used on command line to inhibit all header lines.

--ignore-cmd=CMD

--ignore-output=CMD

--no-cmd=CMD

--no-output=CMD

Do not print output (data or check result) for command CMD.

CMD is any valid command, see COMMANDS, without leading +.

Option can be used multiple times.

--score

Print scoring results. Default for +check.

--no-score

Do not print scoring results.

--separator=CHAR

--sep=CHAR

CHAR will be used as separator between label and value of the

printed results. Default is :

--tab

TAB character (0x09, \t) will be used as separator between label

and value of the printed results.

As label and value are already separated by a TAB character, this

options is only useful in conjunction with the --legacy=compact

option.

--showhost

Prefix each printed line with the given hostname (target).

The hostname will be followed by the separator character.

--std-format=utf8

--std-format=crlf

--std-format=raw

--std-format=unix

--std-format=CHARSET

This option is used to specify the general output format for STDOUT

and STDERR. All results are written to STDOUT, errors and warnings

may also be written to STDERR . The default is :unix:utf8, which

is the perlish definition used internally.

Following values are supported:

raw
unix Print raw data, binary in bytes without conversion.

Note: binary here just means characters (as all output is text).

utf8 Convert all characters to UTF-8.
crlf Use CR LF as end of line.

CHARSET CHARSET can be any of the local installed character

sets, like UTF-8, UTF-16LE, CP1252, iso-8859-7, etc..

This conversion may print its own warnings.

The option can be used multiple times with different values.

To reset the default behaviour, either raw or unix must be

used. Obviously, they must be used first. All other values are used

additionally.

Note: utf8 just defines the format of the characters, it does no

further checks on the converted characters. In contrast, UTF-8 is

used as real encoding and does some checks.

For more details, please see "perldoc -f binmode" .

Currently (Jan. 2018), these options must be used before any --help

option.

--win-CR

Obsolete, please use --std-format=crlf .

Options for compatibility with other programs

Please see other programs for detailed description (if not obvious:).

Note that often only the long form options are accepted as most short

form options are ambiguous.

If other programs use the same option,but with a different behaviour,

then thes other options are not supported.

For a list of supported options, please see:

 o-saft.pl --help=alias

Following list contains only those options not shown with:

 o-saft.pl --help=alias

Tool's Option        (Tool)          o-saft.pl Option
--------------------+---------------+---------------------------
 --checks CMD        (TLS-Check.pl)  same as +CMD
 -h, -h=HOST         (various tools) same as --host HOST
 -p, -p=PORT         (various tools) same as --port PORT
 -t HOST             (ssldiagnos)    same as --host HOST
 --protocol SSL      (ssldiagnos)    same as --SSL
 --UDP               (ssldiagnos)    same as --udp
 --insecure          (cnark.pl)      ignored
 --nopct --nocolor   (ssldiagnos)    ignored
 --timeout, --grep   (ssltest.pl)    ignored
 -r,  -s,  -t,  -x   (ssltest.pl)    ignored
 -connect, -H, -u, -url, -U          ignored
 -noSSL                              same as --no-SSL
 -no_SSL                             same as --no-SSL
--------------------+---------------+---------------------------

For definition of SSL see --SSL and --no-SSL above.

Options for customization

For general descriptions please see CUSTOMIZATION section below.

--cfg_cmd=CMD=LIST

Redefine list of commands. Sets %cfg{cmd-CMD} to LIST. Commands

can be written without the leading +.

If CMD is any of the known internal commands, it will be redifned.

If CMD is a unknown command, it will be created.

Example:

   --cfg_cmd=sni=sni hostname

To get a list of commands and their settings, use:

   o-saft.pl --help=intern

Main purpose is to reduce list of commands or to print them sorted.

An example +preload can be found in .o-saft.pl .

--cfg_score=KEY=SCORE

Redefine value for scoring. Sets %checks{KEY}{score} to SCORE.

Most score values are set to 10 by default. Values 0 .. 100 are

allowed.

To get a list of current score settings, use:

   o-saft.pl --help=score

For deatils how scoring works, please see SCORING section.

Use the --trace-key option for the +info and/or +check

command to get the values for KEY.

--cfg_checks=KEY=TEXT --cfg_data=KEY=TEXT

Redefine texts used for labels in output. Sets %data{KEY}{txt} or

%checks{KEY}{txt} to TEXT.

To get a list of preconfigured labels, use:

   o-saft.pl --help=cfg_checks
   o-saft.pl --help=cfg_data

--cfg_text=CIPHER=value

Redefine the security value (i.e. HIGH) in the cipher description.

Example:

   o-saft.pl --cfg-cipher=NULL-MD5=no-security-at-all ...

--cfg_text=KEY=TEXT

Redefine general texts used in output. Sets %text{KEY} to TEXT.

To get a list of preconfigured texts, use:

   o-saft.pl --help=cfg_text

Note that \n, \r and \t are replaced by the corresponding character

when read from RC-FILE.

--cfg_text=FILE

Read definitions for %text{KEY}="my text" from file FILE.

--cfg_hint=KEY=TEXT

Redefine texts used for hints. Sets %cfg{hints}{KEY} to TEXT.

To get a list of preconfigured texts, use:

   o-sat.pl --help=cfg-hint

--call=METHOD

See Options for SSL tool

--usr

Execute functions defined in o-saft-usr.pm.

--usr-*

--user-*

Options ignored, but stored as is internal in $cfg{usr-args} .

These options can be used in o-saft-usr.pm or o-saft-dbx.pm.

--experimental

Use experimental functionality.

Some functionality of this tool is under development and only used

when this option is given.

Options for tracing and debugging

--n --dry-run

Do not execute, just show commands (only useful in conjunction with

using openssl).

Difference --trace vs. --v

While --v is used to print more data, --trace is used to print

more information about internal data such as procedure names and/or

variable names and program flow.

--v

--verbose

Print more information about checks.

Note that this option should be first otherwise some debug messages

are missing.

Note that --v is different from -v (see above).

--v --v

Print remotely checked ciphers.

--v-cipher --cipher-v

Print remotely checked ciphers.

In contrast to --v --v above, this just prints the ciphers while

being checked, but no other verbose messages.

--trace

Print debugging messages.

--trace --trace

Print more debugging messages and pass trace=2 to Net::SSLeay and

Net::SSLinfo.

--trace --trace --trace

Print more debugging messages and pass trace=3 to Net::SSLeay and

Net::SSLinfo.

--trace --trace --trace --trace

Print processing of all command line arguments.

--trace-cli

Print complete command line first. Used for internal testing.

--trace--

--trace-arg

Print command line argument processing.

--trace-cmd

Trace execution of command processing (those given as +*).

--trace@

--trace-key

Print some internal variable names in output texts (labels).

Variable names are prefixed to printed line and enclosed in # .

Example without --trace-key :

      Certificate Serial Number:          deadbeef

Example with --trace-key :

      #serial#          Certificate Serial Number:          deadbeef

--trace=VALUE

Alias for --trace-VALUE options (see above).

Trace Option Alias Option

--trace=1 same as --trace
--trace=2 same as --trace --trace
--trace=arg same as --trace-arg
--trace=cmd same as --trace-cmd
--trace=key same as --trace-key

--trace-time

Prints timestamp in trace output. More timestamps are printed if

used together with --trace-cmd.

--trace=FILE

Use FILE instead of the default RC-FILE, i.e. .o-saft.pl.

--trace-me

Print debugging messages for o-saft.pl only, but not any modules.

--trace-not-me

Print debugging messages for modules only, but not o-saft.pl istself.

--hint

Print hint messages (!!Hint:).

--no-hint

Do not print hint messages (!!Hint:).

--warning

Print warning messages (**WARNING:).

--no-warning

Do not print warning messages (**WARNING:).

--exit=KEY

Terminate o-saft.pl at specified KEY. Please see TESTING below.

Options vs. Commands

For compatibility with other programs and lazy users, some arguments

looking like options are silently taken as commands. This means that

--THIS becomes +THIS then. These options are:

--help
--abbr
--todo
--chain
--default
--fingerprint
--list
--version

Take care that this behaviour may be removed in future versions as it

conflicts with those options and commands which actually exist, like:

--sni vs. +sni

LAZY SYNOPSIS

Commands

Following strings are treated as a command instead of target names:

ciphers
s_client
version

A warning will be printed.

Options

We support following options, which are all identical, for lazy users

and for compatibility with other programs.

Option Variants

--port PORT

--port=PORT

This applies to most such options, --port is just an example.

When used in the RC-FILE, the --OPTION=VALUE variant must be used.

Option Names

Dash -, dot . and/or underscore _ in option names are optional,

all following are the same:

--no.dns

--no-dns

--no_dns

--nodns

This applies to all such options, --no-dns is just an example.

Targets

Following syntax is supported also:

   o-saft.pl http://some.tld other.tld:3889/some/path?a=b

Note that only the hostname and the port are used from an URL.

Options vs. Commands

See Options vs. Commands in OPTIONS section above

CHECKS

All SSL related check performed by the tool will be described here.

General Checks

Lookup the IP of the given hostname (FQDN), and then tries to reverse

resolve the FQDN again.

SSL Ciphers

Check which ciphers are supported by target. Please see RESULTS for

details of this check.

SSL Connection

heartbeat

Check if "heartbead" extension is supported by target.

poodle

Check if target is vulnerable to POODLE attack (SSLv3 enabled).

robot

Check if target is vulnerable to ROBOT attack (server offers ciphers

with RSA encryption).

sloth

Check if target is vulnerable to SLOTH attack (server offeres RSA-MD5

or ECDSA-MD5 ciphers).

sweet32

Check if target is vulnerable to Sweet32 attack (server offers CBC or

CBC3 or DES or 3DES ciphers).

Note that FIPS-140 compliance requires 3DES ciphers, hence compliant

systems are then vulnerable to Sweet32 attacks.

ALPN

Check if target supports ALPN. Following messages are evaluated:

   ALPN protocol: h2-14
   No ALPN negotiated

Please see also CHECKS ALPN and NPN below.

SSL Vulnerabilities

ADH

Check if ciphers for anonymous key exchange are supported: ADH|DHA .

Such key exchanges can be sniffed.

EDH

Check if ephemeral ciphers are supported: DHE|EDH .

They are necessary to support Perfect Forward Secrecy (PFS).

BEAST

Check if ciphers with CBC for protocol SSLv1, SSLv3 or TLSv1 are used.

TLSv1.2 checks are not yet implemented.

CRIME

Connection is vulnerable if target supports SSL-level compression.

DROWN

Connection is vulnerable if target supports SSLv2 (with at least one cipher).

FREAK

Attack Against SSL/TLS to downgrade to EXPORT ciphers.

Currently (2018) a simple check is used: SSLv3 enabled and EXPORT

ciphers supported by server.

See CVE-2015-0204 and https://freakattack.com/ .

HEARTBLEED

Check if target is vulnerable to heartbleed attack, see CVE-2014-0160

and http://heartbleed.com/ .

HEIST

Not implemented.

There are no checks for the HEIST attack implemented, because this is

an attack on TCP/IP rather than SSL/TLS on top of TCP/IP.

KCI

Not implemented.

To perform a MiTM attack with Key Compromise Impersonation, the atta-

cker needs to engage the victim to install and use a client certificate.

This is considered a low risk and hence not tested here.

Logjam

Check if target is vulenerable to Logjam attack.

Check if target suports EXPORT ciphers and/or DH Parameter is less

than 2048 bits.

Lucky 13

Check if CBC ciphers are offered.

NOTE the recommendation to be safe againts Lucky 13 was to use RC4

ciphers. But they are also subjetc to attacks (see below). Hence the

check is only for CBC ciphers.

RC4

Check if RC4 ciphers are supported.

They are assumed to be broken.

Note that +rc4 reports the vulnerabilitiy to the RC4 Attack, while

+rc4_cipher simply reports if RC4 ciphers are offered. However the

the check, and hence the result, is the same.

PFS

Check if DHE ciphers are used. Also check if the TLS session ticket

is random or not used at all.

Currently (2018) only a simple check is used: only DHE ciphers used.

TLSv1.2 checks are not yet implemented.

POODLE

Check if target is vulnerable to POODLE attack (just check if SSLv3

is enabled).

Practical Invalid Curve Attack

This attack allows an attacker to read the servers private key if the

server does not check properly the passed points for a ecliptic curve

when EDH ciphers are used.

This check will not send multiple invalid points, but only checks if

the server closes the connection or responds with no matching cipher.

ROBOT

Bleichebacher's Oracle attack against SSL/TLS ciphers.

Not implemented.

https://robotattack.org/

SLOTH

Currently (2016) we check for ciphers with ECDSA, RSA-MD5.

Checking the TLS extension 'tls-unique' is not yet implemented.

Sweet32

Currently (2016) we check for ciphers with CBC or CBC3 or DES or 3DES.

Target (server) Configuration and Support

BEAST, BREACH, CRIME, DROWN, FREAK, Logjam, Lucky 13, POODLE, RC4, ROBOT, SLOTH, Sweet32

See above.

Renegotiation

Check if the server allows client-side initiated renegotiation.

Version rollback attacks

NOT YET IMPLEMENTED

Check if the server allows changing the protocol.

DH Parameter

Check if target's DH Parameter is less 512 or 2048 bits.

SSTP

Check if target supports SSTP by accepting method SSTP_DUPLEX_POST.

The check does not send other methods (like CONNECT) to verify if the

protocol is fully supported.

Supporting SSTP is considered insecure, because SSTP allows to tunnel

other, probably insecure, protocols.

Target (server) Certificate

Certificate Hashes

Check that fingerprint is not MD5.

Check that certificate private key signature is SHA2 or better.

Root CA

Provided certificate by target should not be a Root CA.

Self-signed Certificate

Certificate should not be self-signed.

FQDN is listed in subjectAltname (RFC2818)

The FQDN must be listed in the certificates subjectAltname.

The check command +rfc_2818_names is based on the info command

+verify_hostname . The check was added in 05/2017 because browsers

started to complain if the FQDN is not part of the subjectAltname.

IP in CommonName or subjectAltname (RFC6125)

NOT YET IMPLEMENTED

Basic Constraints

Certificate extension Basic Constraints should be CA:FALSE.

OCSP, CRL, CPS

Certificate should contain URL for OCSP and CRL.

Private Key encyption

Certificates signature key supports encryption.

Private Key encyption well known

Certificates signature key encryption algorithm is well known.

Public Key encyption

Certificates public key supports encryption.

Public Key encyption well known

Certificates public key encryption algorithm is well known.

Public Key Modulus size

Some (historic) SSL implementations are subject to buffer overflow if

the key exceeds 16384 or 32768 bits. The check is against 16384 bits.

Public Key Modulus Exponent size

The modulus exponent should be = 65537 as it is a prime number and an

easy to calculate exponent.

If the exponent is less than 65537, "Boradcast" attacks are possible.

However, some (mainly historic) SSL implementations may have problems

to connect because they are not able to do the crypt mathematics with

exponenents larger than 65536.

If ecliptic curves are used, the result for these checks is always

no (<<N/A ...).

Sizes and Lengths of Certificate Settings

Serial Number <= 20 octets (RFC5280, 4.1.2.2. Serial Number)

...

DV-SSL - Domain Validation Certificate

The Certificate must provide:

Common Name /CN= field
Common Name /CN= in subject or subjectAltname field
Domain name in commonName or altname field

EV-SSL - Extended Validation Certificate

This check is performed according the requirements defined by the CA/

Browser Forum https://www.cabforum.org/contents.html .

The Certificate must provide:

DV - Domain Validation Certificate (see above)
Organization name /O= Cn subject field
Organization name must be less to 64 characters
Business Category /businessCategory= in subject field
Registration Number /serialNumber= in subject field
Address of Place of Business in subject field

Required are: /C=, /ST=, /L=

Optional are: /street=, /postalCode=

Validation period does not exceed 27 month

See LIMITATIONS also.

Target (server) HTTP(S) Support

STS header (see RFC 6797)

Using STS is no perfect security. While the very first request using

http: is always prone to a MiTM attack, MiTM is possible to following

requests again, if STS is not well implemented on the server.

Request with http: should be redirected to https:
Redirects should use status code 301 (even others will work)
Redirect's Location header must contain schema https:
Redirect's Location header must redirect to same FQDN
Redirect may use Refresh instead of Location header (not RFC6797)
Redirects from HTTP must not contain STS header
Answer from redirected page (HTTPS) must contain STS header
Answer from redirected page for IP must not contain STS header
STS header must contain includeSubDirectoy directive
STS header max-age should be less than 1 month
STS must not be set in http-equiv attribute of a meta TAG

STS header preload attribute (+preload)

To satisfy the requirements on https://hstspreload.appspot.com/ the

HSTS header must:

have the max-age with at least 18 weeks (10886400 seconds)
have the includeSubDomains attribute
have the preload attribute
redirect to https first, then to sub-domains (if redirected)
have an HSTS header in each redirect to https.

Additionally, the site must have:

a valid certificate
serve all subdomains over https.

Except the last requirement, +preload will do the checks.

Note that +preload is defined in .o-saft.pl only.

Public Key Pins header

TBD - to be described ...

Sizes

Mainly in the certificate various counts, lengths and sizes of values

are checked and reported. All commands for these checks start with

+cnt_ or +len_. Up to now, there is no yes or no value

for these checks.

Following commands will check the value to be in a specific range to

become yes or no:

+sts_maxage1d - yes if HSTS maxage < 1 day
+sts_maxage1m - yes if HSTS maxage < 1 month
+sts_maxage1y - yes if HSTS maxage < 1 year
+sts_maxage18 - yes if HSTS maxage < 18 weeks (5 months)
+sts_maxagexy - yes if HSTS maxage > 1 year
+modulus_exp_1 - Public Key Modulus Exponent <>1
+modulus_exp_65537 - Public Key Modulus Exponent =65537
+modulus_exp_oldssl - Public Key Modulus Exponent <65537
+modulus_size_oldssl - Public Key Modulus <16385 bits

For some details of these checks, please see the description above at

"Public Key Modulus Exponent size"

The recommendations for DH parameters (RSA and ecliptice curve) are

are checked as follows:

+dh_512 - DH Parameter >= 512 bits
+dh_2048 - DH Parameter >= 2048 bits
+ecdh_256 - DH Parameter >= 256 bits (ECDH)
+ecdh_512 - DH Parameter >= 512 bits (ECDH)

Note that only one of the checks +dh_* and +ecdh_* can return

yes.

ALPN and NPN

The commands for the checks to report yes or no, are +hasalpn

and +hasnpn.

Both, the Application Layer Protocol Negotiation (ALPN) and the Next

Protocol Negotiation (NPN) will be tested. The commands for that are:

+alpns
+npns

Each, ALPN and NPN, is tested separately with all known protocols.

The test sets only one protocol, tries to make a connection and then

checks if the protocol was accepted by the server. The collected list

of protocols will be printed with the aforementioned commands, or the

+info command. Note the difference for the commands +next_protocols

and +alpns, where +next_protocols simply reports what the server

itself advertises, while +alpns reports what the server supports if

asked for.

Compliances

Note that it is not possible to satisfy all following compliances. Best

match is: PSF and ISM and PCI and lazy BSI TR-02102-2.

In general it is difficult to satisfy all conditions of a compliances,

and it is also difficult to check all these conditions. That's why some

of the compliances checks are not completely implemented, for details

please see blow.

Note that output of results of some checks is disabled in the RC-FILE

by default. A "!!Hint:" message will be printed, if any of these checks

are used.

FIPS-140
ISM
PCI
BSI TR-02102 (2016-01)
BSI TR-03116-4
RFC 2818
RFC 6125
RFC 6797
RFC 7525

BSI TR-02102-2 (+tr-02102+ tr-02102- +bsi)

Checks if connection and ciphers are compliant according TR-02102-2,

see https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen

/TechnischeRichtlinien/TR02102/BSI-TR-02102-2_pdf.pdf?__blob=publicationFile

(following headlines are taken from TR-02102-2 Version 2016-01)

3.1.3 Schlüssellängen bei EC-Verfahren

3.2 SSL/TLS_Versionen

Only TLSv1.2 allowed (except for +tr-02102- which also allows

TLSv1.1)

3.3.1 Empfohlene Cipher Suites

Allows only *DHE-*-SHA256, *DHE-*-SHA384, *DH-*-SHA256 and

*DH-*-SHA384 ciphers and PSK ciphers with ephermeral keys.

For +tr-02102+ they must be AES-GCM, +tr02102- also allows

AES-CBC.

3.3.2 Übergangsregelungen

SHA1 temporary allowed. SHA256 and SHA384 recommended.

RC4 not reocmmended.

Use of SHA1 will only be checked for +tr-02102+

3.4.1 Session Renegotation

Only server-side (secure) renegotiation allowed (see RFC5280).

3.4.2 Verkürzung der HMAC-Ausgabe

Truncated HMAC according RFC 6066 not recommended.

3.4.3 TLS-Kompression und der CRIME-Angriff

No TLS compression.

3.4.4 Der Lucky 13-Angriff
3.4.5 Die "Encrypt-thn-MAC"-Erweiterung

Use of AES-GCM ciphers only.

Use of Encrypt-then-MAC according RFC 7366 cannot be checked.

3.4.6 Die Heartbeat-Erweiterung

Target must not support the heartbeat extension.

3.4.7 Die Extended Master Secret Extension

Use of Extended Master Secret Extension according RFC 7627 cannot

be checked.

3.5 Authentisierung der Kommunikationspartner

Not checked as only applicable for VPN connections.

3.6 Domainparameter und Schlüssellängen

Check if signature key is > 2000 bits.

3.6.1 Verwendung von elliptischen Kurven

**NOT YET IMPLEMENTED**

Use only following curves according RFC 5639 and RFC 7027:

brainpoolP256r1, brainpoolP384r1, brainpoolP512r1

Use of secp256r1 and secp384r1 temporary allowed.

4.1 Schlüsselspeicherung

This requirement is not testable from remote.

4.1 Umgang mit Ephemeralschlüsseln

This requirement is not testable from remote.

4.3 Zufallszahlen

This requirement is not testable from remote.

BSI TR-03116-4 (+tr-03116+ +tr-03116- +bsi)

Checks if connection and ciphers are compliant according TR-03116-4,

see https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen

/TechnischeRichtlinien/TR03116/BSI-TR-03116-4.pdf?__blob=publicationFile

(following headlines are taken from there)

2.1.1 TLS-Versionen und Sessions

Allows only TLS 1.2.

2.1.2 Cipher Suites

Cipher suites must be ECDHE-ECDSA or -RSA with AES128 and SHA265.

For curiosity, stronger cipher suites with AES256 and/or SHA384 are

not not allowed. To follow this curiosity the +bsi-tr-03116- (lazy)

check allows the stronger cipher suites ;-)

2.1.1 TLS-Versionen und Sessions

The TLS session lifetime must not exceed 2 days.

2.1.4.2 Encrypt-then-MAC-Extension

2.1.4.3 OCSP-Stapling

MUST have OCSP Stapling URL.

4.1.1 Zertifizierungsstellen/Vertrauensanker

Certificate must provide all root CAs. (NOT YET IMPLEMENTED).

Should use a small certificate trust chain.

4.1.2 Zertifikate

Must have CRLDistributionPoint or AuthorityInfoAccess.

End-user certificate must not be valid longer than 3 years.

Root-CA certificate must not be valid longer than 5 years.

Certificate extension pathLenConstraint must exist, and should be

a small value ("small" is not defined).

All certificates must contain the extension KeyUsage.

Wildcards for CN or Subject or SubjectAltName are not allowed

in any certificate.

EV certificates are recommended (NOT YET checked properly).

4.1.3 Zertifikatsverifikation

Must verify all certificates in the chain down to their root-CA.

(NOT YET IMPLEMENTED).

Certificate must be valid according issue and expire date.

All Checks must be doen for all certificates in the chain.

4.1.4 Domainparameter und Schlüssellängen

This requirement is not testable from remote.

4 5.2 Zufallszahlen

This requirement is not testable from remote.

RFC 2818 (+rfc2818)

Check if the FQDN is listed in the certificates subjectAltname.

RFC 6125 (+rfc6125)

Checks values CommonName, Subject and SubjectAltname of the

certificate for:

must all be valid characters for DNS
must not contain more than one wildcards
must not contain invalid wildcards
must not contain invalid IDN characters

RFC 6797 (+rfc6797)

Same as STS header +hsts .

RFC 7525 (+rfc7525)

Checks if connection and ciphers are compliant according RFC 7525.

See http://tools.ietf.org/rfc/rfc7525.txt

(following headlines are taken from there)

3.1.1. SSL/TLS Protocol Versions

SSLv2 and SSLv3 must not be supportetd.

TLSv1 should only be supported if there is no TLSv1.1 or TLSv1.2.

Either TLSv1.1 or TLSv1.2 must be supported, prefered is TLSv1.2.

3.1.2. DTLS Protocol Versions

DTLSv1 and DTLSv1.1 must not be supported.

3.1.3. Fallback to Lower Versions

(check implecitely done by 3.1.1, see above)

3.2. Strict TLS

Check if server provides Strict Transport Security.

(STARTTLS check NOT YET IMPLEMENTED).

3.3. Compression

Compression on TLS must not be supported.

3.4. TLS Session Resumption

Server must support resumtion and random session tickets.

(Randomnes of session tickets implemented YET experimental.)

Check if ticket is authenticated and encrypted NOT YET IMPLEMENTED.

3.5. TLS Renegotiation

Server must support renegotiation.

3.6. Server Name Indication

(Check for SNI support implemented experimental.)

4. Recommendations: Cipher Suites

4.1. General Guidelines
4.2. Recommended Cipher Suites

Check for recommended ciphers.

4.3. Public Key Length

DH parameter must be at least 256 bits or 2048 its with EC.

(Check currently, 4/2016, based on openssl which may not provide DH

parameters for all ciphers.)

4.5. Truncated HMAC

TLS extension "truncated hmac" must not be used.

6. Security Considerations
6.1. Host Name Validation

Given hostname must matches hostname in certificate's subject.

6.2. AES-GCM
6.3. Forward Secrecy
6.4. Diffie-Hellman Exponent Reuse

(NOT YET IMPLEMENTED).

6.5. Certificate Revocation

OCSP and CRL Distrbution Point in cetificate must be defined.

OUTPUT

All output is designed to make it easily parsable by postprocessors.

Following rules are used:

Lines for formatting or header lines start with =.
Lines for verbosity or tracing start with #.
Errors and warnings start with **, hints start with !!.
Empty lines are comments ;-)
Label texts end with a separation character; default is :.
Label and value for all checks are separated by at least one TAB character.
Texts for additional information are enclosed in << and >>.
N/A is used when no proper informations was found or provided.

Replace N/A by whatever you think is adequate: "No answer",

"Not available", "Not applicable", ...

Lines not described above, will have the form (be default):

        Label for information or check:  TABresult

For more details on these lines, please refer to RESULTS above.

When used in --legacy=full or --legacy=simple mode, the output

may contain formatting lines for better (human) readability.

Errors, Warnings, Hints

Errors, warnings and hints may be part of the output as needed. While

errors and warnings are printed immediately as they occour during the

program flow, hints are printed right after the corresponding result.

Errors and warnings start with a unique 3-digit number.

Hints print an additional explanation of a specific result. They are

are defined statically in the program code, or can be added on demand

by using the option --cfg-hint=KEY=TEXT .

Postprocessing Output

It is recommended to use the --legacy=quick option, if the output

should be postprocessed, as it omits the default separation character

(: , see above) and just uses on single tab character (0x09, \t or

TAB) to separate the label text from the text of the result. Example:

        Label of the performed checkTABresult

More examples for postprocessing the output can be found here:

https://github.com/OWASP/O-Saft/blob/master/contrib

CUSTOMIZATION

This tools can be customized as follows:

Using command line options

This is a simple way to redefine specific settings. Please see

CONFIGURATION OPTIONS below.

Using Configuration file

A configuration file can contain multiple configuration settings.

Syntax is simply KEY=VALUE. Please see CONFIGURATION FILE below.

Using resource files

A resource file can contain multiple command line options. Syntax

is the same as for command line options iteself. Each directory

may contain its own resource file. Please see RC-FILE below.

Using debugging files

These files are --nomen est omen-- used for debugging purposes.

However, they can be (mis-)used to redefine all settings too.

Please see DEBUG-FILE below.

Using user specified code

This file contains user specified program code. It can also be

(mis-)used to redefine all settings. Please see USER-FILE below.

Customization is done by redefining values in internal data structure

which are: %cfg, %data, %checks, %text, %scores .

Unless used in DEBUG-FILE or USER-FILE, there is no need to know

these internal data structures or the names of variables; the options

will set the proper values. The key names being part of the option,

are printed in output with the --trace-key option.

I.g. texts (values) of keys in %data are those used in output of the

Informations section. Texts of keys in %checks are used for output

in Performed Checks section. And texts of keys in %text are used

for additional information lines or texts (mainly beginning with =).

Configuration File vs. RC-FILE vs. DEBUG-FILE

CONFIGURATION FILE

Configuration Files must be specified with one of the --cfg_*

options. The specified file can be a valid path. Please note that

only the characters: -zA-Z_0-9,.\/()- are allowed as pathname.

Syntax in configuration file is: KEY=VALUE where KEY is any

key as used in internal data structure.

the keys in output).

RC-FILE

Resource files are searched for and used automatically.

For details see RC-FILE below.

DEBUG-FILE

Debug files are searched for and used automatically.

For details see DEBUG-FILE below.

USER-FILE

The user program file is included only if the --usr option was

used. For details see USER-FILE below.

CONFIGURATION OPTIONS

Configuration options are used to redefine texts and labels or score

settings used in output. The options are:

--cfg-cmd=CMD=LIST
--cfg-checks=KEY=TEXT
--cfg-data=KEY=TEXT
--cfg-hint=KEY=TEXT
--cfg-text=KEY=TEXT
--cfg-cipher=CIPHER=TEXT

KEY is the key used in the internal data structure, and TEXT is the

value to be set for this key. Note that unknown keys will be ignored

silently.

If KEY=TEXT is an exiting filename, all lines from that file are

read and set. For details see CONFIGURATION FILE below.

CIPHER must be a valid cipher suite name as shown with:

   o-saft.pl ciphers

NOTE that such configuration options should be used before any --help

or --help=* option, otherwise the changed setting is not visible.

CONFIGURATION FILE

Note that the file can contain KEY=TEXT pairs for any kind of the

configuration as given by the --cfg_CFG option.

For example when used with --cfg_text=FILE only values for %text

will be set, when used with #--cfg_data=FILE--cfg_data=FILE only values for %data

will be set, and so on. KEY is not used when KEY=TEXT is an existing

filename. Though, it's recommended to use a non-existing key, i.e.:

--cfg-text=my_file=some/path/to/private/file .

RC-FILE

The rc-file will be searched for in the working directory only.

The name of the rc-file is the name of the program file prefixed by a

. (dot), for example: .o-saft.pl.

A rc-file can contain any of the commands and options valid for the

tool itself. The syntax for them is the same as on command line. Each

command or option must be in a single line. Any empty or comment line

will be ignored. Comment lines start with # or =.

Note that options with arguments must be used as KEY=VALUE instead

of KEY VALUE.

Configurations options must be written like --cfg-CFG=KEY=VALUE

where CFG is any of: cmd, check, data, text and KEY is

any key from internal data structure (see above).

All commands and options given on command line will overwrite those

found in the rc-file.

DEBUG-FILE

All debugging functionality is defined in o-saft-dbx.pm, which will

be searched for using paths available in @INC variable.

Syntax in this file is Perl code. For details see DEBUG below.

USER-FILE

All user functionality is defined in o-saft-usr.pm, which will be

searched for using paths available in @INC variable.

Syntax in this file is Perl code.

All functions defined in o-saft-usr.pm are called when the option

--usr was given. The functions are defined as empty stub, any code

can be inserted as need. Please see perldoc o-saft-usr.pm to see

when and how these functions are called.

SHELL TWEAKS

Configuring the shell environment where the tool is startet, must be

done before the tools starts. It is not really a task for the tool

itself, but it can simplify your life, somehow.

There exist customizations for some commonly used shells, please see

the files in the ./contrib/ directory.

COMMANDS

The option --cfg-cmd=CMD=LIST can be used to define own commands.

When configuring own commands, CMD must not be one of the commands

listed with --help=intern and CMD must constist only of digits and

letters.

Examples in .o-saft.pl are +preload and +ciphercheck .

CIPHER NAMES

While the SSL/TLS protocol uses integer numbers to identify ciphers,

almost all tools use some kind of `human readable' texts for cipher

names.

These numbers (which are most likely written as hex values in source

code and documentations) are the only true identifier, and we have to

rely on the tools that they use the proper integers.

As such integer or hex numbers are difficult to handle by humans, we

decided to use human readable texts. Unfortunately no common standard

exists how to construct the names and map them to the correct number.

Some, but by far not all, oddities are described in Name Rodeo.

The rules for specifying cipher names are:

1. textual names as defined by IANA (see [IANA])
2. mapping of names and numbers as defined by IANA (see [IANA])
3. - and _ are treated the same
4. abbreviations are allowed, as long as they are unique
5. beside IANA, openssl's cipher names are preferred
6. name variants are supported, as long as they are unique
7. hex numbers can be used

[IANA] http://www.iana.org/assignments/tls-parameters/tls-parameters.txt September 2013

[openssl] ... openssl 1.0.1

If in any doubt, use +list to get an idea about the mapping.

Use --help=regex to see which regex are used to handle all these

variants herein.

Mind the traps and dragons with cipher names and what number they are

actually mapped to. In particular when --lib, --exe or --openssl

options are in use. Always use these options with +list command too.

Name Rodeo

As said above, the SSL/TLS protocol uses integer numbers to identify

ciphers, but almost all tools use some kind of human readable texts

for cipher names.

For example the cipher commonly known as DES-CBC3-SHA is identified

by 0x020701c0 (in openssl) and has SSL2_DES_192_EDE3_CBC_WITH_SHA

as constant name. A definition is missing in IANA, but there is

TLS_RSA_WITH_3DES_EDE_CBC_SHA . Thers is also 0x000A for the same

cipher DES-CBC3-SHA. Both are valid, first one when used with SSLv2,

and second one when used with SSLv3.

It's the responsibility of each tool to map the human readable cipher

name to the correct (hex, integer) identifier.

For example Firefox uses dhe_dss_des_ede3_sha, which is what?

Furthermore, there are different acronyms for the same thing in use.

For example DHE and EDH both mean "Ephemeral Diffie-Hellman".

Comments in the openssl(1) sources mention this. And for curiosity

these sources use both in cypher names but allow EDH as shortcut

only in openssl's "ciphers" command. Wonder about (up to 1.0.1h):

   openssl ciphers -V EDH
   openssl ciphers -V DHE
   openssl ciphers -V EECDH
   openssl ciphers -V ECDHE

Next example is ADH which is also known as DH_anon or DHAnon

or DHA or ANON_DH.

You think this is enough? Then have a look how many acronyms are used

for "Tripple DES".

Compared to above, the interchangeable use of - vs. _ in human

readable cipher names is just a very simple one. However, see openssl

again what following means (returns):

   openssl ciphers -v RC4-MD5
   openssl ciphers -v RC4+MD5
   openssl ciphers -v RC4:-MD5
   openssl ciphers -v RC4:!MD5
   openssl ciphers -v RC4!MD5

Looking at all these oddities, it would be nice to have a common unique

naming scheme for cipher names. We have not. As the SSL/TLS protocol

just uses a number, it would be natural to use the number as uniq key

for all cipher names, at least as key in our internal sources.

Unfortunately, the assignment of ciphers to numbers changed over the

years, which means that the same number refers to a different cipher

depending on the standard, and/or tool, or version of a tool you use.

As a result, we cannot use human readable cipher names as identifier

(aka unique key), as there are to many aliases for the same cipher.

And also the number cannot be used as unique key, as a key may have

multiple ciphers assigned.

KNOWN PROBLEMS

This section describes knwon problems, and known error messages which

may occour when using o-saft.pl. This sections can be used as FAQ too

as it gives hints and workarounds.

Segmentation fault

Sometimes the program terminates with a Segmentation fault. This

mainly happens if the target does not return certificate information.

If so, the --no-cert option may help.

**WARNING: empty result from openssl; ignored at ...

This most likely occurs when the provided cipher is not accepted by

the server, or the server expects client certificates.

**WARNING: unknown result from openssl; ignored at ...

This most likely occurs when the openssl executable is used with a

very slow connection. Typically the reason is a connection timeout.

Try to use --timeout=SEC option.

To get more information, use --v --v and/or --trace also.

**WARNING: undefined cipher description

May occour if ciphers are checked, but no description is available for

them herein. This results in printed cipher checks like:

        EXP-KRB5-RC4-MD5                no       <undef>>

instead of:

        EXP-KRB5-RC4-MD5                no       weak

**WARNING: Can't make a connection to your.tld:443; no initial data

**WARNING: Can't make a connection to your.tld:443; target ignored

This message occours if the underlaying SSL library (i.e. libssl.a)

was not able to connect to the target. Known observed reasons are:

target does not support SSL protocol on specified port
target expects a client certificate in ClientHello message

More details why the connection failed can be seen using --trace=2 .

If the targets supports SSL, it should be at least possible to check

for supported ciphers using +cipherall instead of +cipher .

Use of uninitialized value $headers in split ... do_httpx2.al)

The warning message (like follows or similar):

Use of uninitialized value $headers in split at blib/lib/Net/SSLeay.pm

(autosplit into blib/lib/auto/Net/SSLeay/do_httpx2.al) line 1290.

occurs if the target refused a connection on port 80.

This is considered a bug in Net::SSLeay.

Workaround to get rid of this message: use --no-http option.

invalid SSL_version specified at ... IO/Socket/SSL.pm

This error may occur on systems where a specific SSL version is not

supported. Subject are mainly SSLv2, SSLv3 TLSv1.3 and DTLSv1.

For DTLSv1 the full message looks like:

      invalid SSL_version specified at C:/programs/perl/perl/vendor/lib/IO/Socket/SSL.

Use of uninitialized value $_[0] in length at (eval 4) line 1.

This warning occours with IO::Socket::SSL 1.967, reason is unknown.

It seems not to harm functionality, hence no workaround, just ignore.

Use of uninitialized value in subroutine entry at lib/IO/Socket/SSL.pm line 430.

Some versions of IO::Socket::SSL return this error message if *-MD5

ciphers are used with other protocols than SSLv2.

Workaround: use --no-md5-cipher option.

Can't locate auto/Net/SSLeay/CTX_v2_new.al in @INC ...

Underlaying library doesn't support the required SSL version.

Read error: Connection reset by peer (,199725) at blib/lib/Net/SSLeay.pm (autosplit into blib/lib/auto/Net/SSLeay/tcp_read_all.al) line 535.

Error reported by some Net::SSLeay versions. Reason may be a timeout.

This error cannot be omitted or handled properly.

Workaround: try to use same call again (no guarantee, unfortunatelly)

Odd number of elements in anonymous hash at Net/SSLinfo.pm line 1613.

This warning from perl have been observed when the connection to the

target to check for supported ciphers cannot be established.

This message can be ignored.

openssl: ...some/path.../libssl.so.1.0.0: no version information available (required by openssl)

Mismatch of openssl executable and loaded underlaying library. This

most likely happens when options --lib=PATH and/or --exe=PATH are

used. See also Note on SSL versions .

Hint: use following commands to get information about used libraries:

  o-saft.pl +version
  o-saft.pl --v --v +version

Integer overflow in hexadecimal number at ...

This error message may occour on 32-bit systems if perl was not com-

piled with proper options. I.g. perl automatically converts the value

to a floating pont number.

Please report a bug with output of following command:

  o-saft.pl +s_client +dump your.tld

<<openssl did not return DH Paramter>>

Text may be part of a value. This means that all checks according DH

parameters and logkam attack cannot be done.

Workaround: try to use --openssl=TOOL option.

This text may appears in any of the compliance checks (like +rfc7525)

which may be a false positive. For these checks openssl is also used

to get the DH Parameter.

Workaround: not available yet

No output with +help and/or --help=todo

On some (mainly Windows-based) systems using

  o-saft.pl +help
  o-saft.pl --help

does not print anything.

Workaround: use --v option.

  o-saft.pl +help --v

or

  o-saft.pl +help | more

Character set (like UTF-8) not recognized in some tools

Some tools do not diplay all characters properly, i.e. some versions

of podviewer. It is not the obligation of this tool to fix well known

bugs in other tools. However, we can offer workarounds.

Workaround: generate the affected output using --std-format=* options

For example:

   o-saft.pl --no-rc --std-format=raw --help=gen-pod

**WARNING: on MSWin32 additional option --v required, sometimes ...

On some (mainly Windows-based) systems this may happen when calling

for example:

  o-saft.pl --help=FAQ

which then may produce:

  **WARNING: on MSWin32 additional option  --v  required, sometimes ...
  === reading: ./.o-saft.pl (RC-FILE done) ===
  === reading: Net/SSLinfo.pm (O-Saft module done) ===
  **USAGE: no command given
  # most common usage: 
    o-saft.pl +info   your.tld
    o-saft.pl +check  your.tld
    o-saft.pl +cipher your.tld
  # for more help use:
    o-saft.pl --help

Workaround: use full path to perl.exe, for example

  C:\Programs\perl\bin\perl.exe o-saft.pl --help=FAQ

Performance Problems

There are various reasons when the program responds slow, or seems to

hang. Performance issues are most likely a target-side problem. Most

common reasons are (no specific order):

a) DNS resolver problems

Try with --no-dns

b) target does not accept connections for https

Try with --no-http

c) target's certificate is not valid

Try with --no-cert

d) target expects that the client provides a client certificate

No option provided yet ...

e) target does not handle Server Name Indication (SNI)

Try with --no-sni

f) use of external openssl(1) executable

Use --no-openssl

g) target does not respond at all and/or blocks

Use --ssl-error

For a detailed description, please see Connection Problems.

Other options which may help to get closer to the problem's cause:

--trace-time, --timeout=SEC, --trace, --trace-cmd

Using --trace=time should show following times:

DNS: 1 - 10 sec
no SNI: 1 - 10 sec
connection test: 1 - 5 sec
need_default: <5 sec
need_cipher: 1 - 60 sec (+cipher with socket)
need_cipher: 1 - 20 sec (+cipherraw)
prepare checks: 2 - 20 sec
info: <1 sec
check: <1 sec

LIMITATIONS

Commands

Some commands cannot be used together with others, for example:

+cipher, +ciphers, +list, +libversion, +version, +check, +help,

+protocols .

+quick should not be used together with other commands, it returns

strange output then.

+protocols requires openssl(1) with support for -nextprotoneg

option. Otherwise the value will be empty.

Options

The option --port=PORT must preceed --host=HOST for a target like

HOST:PORT .

The characters + and = cannot be used for --separator==CHAR option.

Following strings should not be used in any value for options:

+check, +info, +quick, --header

as they my trigger the ---header option unintentional.

The used timeout(1) command cannot be defined with a full path like

openssl(1) can with the --openssl=path/to/openssl.

--cfg_text=FILE cannot be used to redefine the texts yes and no

as used in the output for +cipher command.

Checks (general)

+constraints

This check is only done for the certificate provided by the target.

All other certificate in the chain are not checked.

This is currently (2018) a limitation in o-saft.pl.

Broken pipe

This error message most likely means that the connection to specified

target was not possible (firewall or whatever reason).

Target Certificate Chain Verification

The systems default capabilities i.e. libssl.so, openssl, are used to

verify the target's certificate chain. Unfortunately various systems

have implemented different approaches and rules how identify and how

to report a successful verification. As a consequence this tool can

only return the same information about the chain verification as the

used underlying tools. If that information is trustworthy depends on

how trustworthy the tools are.

These limitations apply to following commands:

+verify
+selfsigned

Following commands and options are useful to get more information:

+chain_verify, +verify, +error_verify, +chain, +s_client
--ca-file, --ca-path, --ca-depth

User Provided Files

Please note that there cannot be any guarantee that the code provided

in the DEBUG-FILE o-saft-usr.pm or USER-FILE o-saft-usr.pm

will work flawless. Obviously this is the user's responsibility.

Problems and Errors

Checking the target for supported ciphers may return that a cipher is

not supported by the server misleadingly. Reason is most likely an

improper timeout for the connection. See --timeout=SEC option.

If the specified targets accepts connections but does not speak SSL,

the connection will be closed after the system's TCP/IP-timeout. This

script will hang (about 2-3 minutes).

If reverse DNS lookup fails, an error message is returned as hostname,

like: <<gethostbyaddr() failed>>.

Workaround to get rid of this message: use --no-dns option.

All checks for EV are solely based on the information provided by the

certificate.

Some versions of openssl (< 1.x) may not support all required options

which results in various error messages or --more worse-- may not be

visibale at all. Available functionalitity of openssl will be checked

for right at the beginning Proper Warnings and hints are printed.

Following table shows the openssl option and how to disbale it within

o-saft:

-nextprotoneg --no-nextprotoneg
-reconnect --no-reconnect
-tlsextdebug --no-tlsextdebug
-alpn --no-alpn

Connection Problems

Sometimes the connection cannot be established. This may have various

reasons. Unfortunaly this script seems to hang then. In particular

when checking for ciphers with +cipher or +cipherall . The reason

is most likely that the server does not respond to the TCP/IP request

and hence the script closes the connection after the configured time-

out (see --timeout=SEC option).

Continous connection attempts can be inhibited with the --ssl-error

option, which is set by default. Avoiding further connections results

in a loss of information and consequentely leading to wrong checks.

It is a trade-off to wait for all information done accurately, or to

get the results quickly. The logic to stop connecting for --ssl-error

can be controlled with following additional options:

--ssl-error-max=CNT - max. continous errors
--ssl-error-timeout=SEC - timeout when to treat a failure as error
--ssl-error-total=CNT - max. amount of errors

This means that no more connections are made when more than

--ssl-error-max errors occour sequentialy

or

--ssl-error-total errors occoured

Examples:

--ssl-error-max=3
--ssl-error-timeout=6
--ssl-error-total=6

no more connections are made if for example any sequence of timeouts

occour:

 0 5 2 2                   - --ssl-error-max matches 
 0 1 3 0 0 0 4 1 2 2 2     - --ssl-error-max matches
 0 5 0 2 0 2 2 0 2 0 2     - --ssl-error-total matches

This allows to fine-tune the condition when to stop connecting to the

target. For example, continous but not consecutive timeouts may indi-

cate a bad or instable network connection, but not that the target to

be connected blocks. In such a case sequence of timeouts like follows

may be observed (assuming --ssl-error-max=3):

 0 5 1 2 2 2 4 2 3 2 3 3 3 2
       ^                 ^____ stop for --ssl-error-timeout=3
       |______________________ stop for --ssl-error-timeout=2

On normal (even slow) network connections dozens of connections per

second are usual, hence the timeout is always 0 or 1. Based on that

experience --ssl-error is enabled and set with defaults as follows:

--ssl-error-max=5
--ssl-error-timeout=1
--ssl-error-total=10

Poor Systems

Use of openssl(1) is disabled by default on Windows due to various

performance problems. It needs to be enabled with --openssl option.

On Windows the usage of openssl s_client needs to be enabled using

--s_client option.

On Windows it's a pain to specify the path for --openssl=TOOL option.

Variants are:

--openssl=/path/to/openssl.exe
--openssl=X:/path/to/openssl.exe
--openssl=\path\to\openssl.exe
--openssl=X:\path\to\openssl.exe
--openssl=\\path\\to\\openssl.exe
--openssl=X:\\path\\to\\openssl.exe

You have to fiddle around to find the proper one.

Debug and Trace Output

When both --trace-key and --trace-cmd options are used, output is

mixed, obviously. Hint: output for --trace-cmd always contains "CMD".

Any --trace* option implies --trace-time .

DEPENDENCIES

All Perl modules and all private moduels and files will be searched

for using paths available in the @INC variable. @INC will

be prepended by following paths:

.
./lib
INSTALL_PATH
INSTALL_PATH/lib

Where INSTALL_PATH is the path where the tool is installed.

To see which files have been included use:

   o-saft.pl +version --v --user

Perl Modules

IO::Socket::SSL(3pm)
IO::Socket::INET(3pm)
Net::SSLeay(3pm)
Net::SSLinfo
Net::SSLhello

Perl modules loaded and used for some options only:

Net::DNS(3pm)
Time::Local(3pm)

Additional Files used if requested

.o-saft.pl
o-saft-dbx.pm
o-saft-man.pm
o-saft-usr.pm
o-saft-README
o-saft-docker

INSTALLATION

The tool can be installed in any path. It just requres the modules as

described in DEPENDENCIES above. However, it's recommended that the

modules Net::SSLhello and Net::SSLinfo are found in the directory

./Net/ where o-saft.pl is installed.

For security reasons, most modern libraries disabled or even removed

insecure or "dirty" functionality. As this tool's purpose is to find

such insecure settings, functions, etc., it needs these dirty things

enabled. What we need is (incomplete list):

insecure protocols like SSLv2, SSLv3
more more ciphers enabled, like NULL-MD5, AECDH-NULL-SHA, etc.
some SSL extensions and options

Therefore we recommend to compile and install at least following:

openssl with SSLv2, SSLv3 and more ciphers enabled
Net::SSLeay compiled with openssl version as described before.

Please read the SECURITY section first before following the install

instructions below.

OpenSSL

Currently (since 18.06.18) it is recommend to build openssl using

   contrib/install_openssl.sh

Other possibilities are:

compiling openssl using following sources

https://github.com/PeterMosmans/openssl/

see Example: Compile OpenSSL,

use any of the precomiled versions provided by https://testssl.sh/

The sources are available at

https://github.com/PeterMosmans/openssl/archive/1.0.2-chacha.zip

A precomiled static versions are available at

https://github.com/drwetter/testssl.sh/tree/master/bin

For all following installation examples we assume:

openssl-1.0.2-chacha.zip or openssl-1.0.2d.tar.gz
/usr/local as bae installation directory
a bourne shell (sh) compatible shell

Example: Precompiled OpenSSL

Simply download the tarball or zip file for your platform, unpack it,

and install (copy) the binaries into a directory of your choice.

Example: Compile OpenSSL

OpenSSL can be used from http://openssl.org/ or, as recommended, from

https://github.com/PeterMosmans/openssl/ .

OpenSSL-chacha

Compiling and installing the later is as simple as:

   unzip openssl-1.0.2-chacha.zip
   cd openssl-1.0.2-chacha
   ./config --shared -Wl,-rpath=/usr/local/lib
   make
   make test
   make install

which will install openssl, libssl.so, libcrypto.so and some include

files as well as the include files in /usr/local/ .

The shared version of the libraries are necessary for Net::SSLeay.

OpenSSL.org

Building openssl from the offical openssl.org sources requires some

patching before compiling and installing the libraries and binaries.

Example with openssl-1.0.2d:

  echo == unpack tarball
  tar xf openssl-1.0.2d.tar.gz
  cd openssl-1.0.2d

  echo == backup files to be modified
  cp ssl/s2_lib.c{,.bak}
  cp ssl/s3_lib.c{,.bak}
  cp ssl/ssl3.h{,.bak}
  cp ssl/tls1.h{,.bak}

  echo == patch files
  vi ssl/tls1.h         +/TLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES/
           # define TLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES  1
  vi ssl/ssl3.h ssl/s{2,3}_lib.c   +"/# *if 0/"
           #==> remove all   # if 0  and corresponding  #endif
           #    except if lines contain:
           #        _FZA
           #        /* Fortezza ciphersuite from SSL 3.0
           #        /* Do not set the compare functions,
           #        if (s->shutdown & SSL_SEND_SHUTDOWN)

  echo == configure with static libraries
  echo omitt the zlib options if zlib-1g-dev is not installed
  echo omitt the krb5 options if no kerberos libraries available
  ./config --prefix=/usr/local --openssldir=/usr/local/ssl \
      enable-zlib zlib zlib-dynamic enable-ssl2 \
      enable-krb5 --with-krb5-flavor=MIT \
      enable-mdc2 enable-md2  enable-rc5  enable-rc2 \
      enable-cms  enable-ec   enable-ec2m enable-ecdh enable-ecdsa \
      enable-gost enable-seed enable-idea enable-camellia \
      enable-rfc3779 enable-ec_nistp_64_gcc_128 \
      experimental-jpake -fPIC \
      -DTEMP_GOST_TLS -DTLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES \
      shared

  echo == make binaries and libraries
  make depend
  make
  make test
  make install

  echo == if you want static binaries and libraries
  make clean
  echo same ./config as before but without shared option
  ./config --prefix=/usr/local --openssldir=/usr/local/ssl \
      enable-zlib zlib zlib-dynamic enable-ssl2 \
      enable-krb5 --with-krb5-flavor=MIT \
      enable-mdc2 enable-md2 enable-rc5 enable-rc2 \
      enable-cms  enable-ec   enable-ec2m enable-ecdh enable-ecdsa \
      enable-gost enable-seed enable-idea enable-camellia \
      enable-rfc3779 enable-ec_nistp_64_gcc_128 \
      experimental-jpake -fPIC \
      -DTEMP_GOST_TLS -DTLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES
  make depend
  make
  make test
  echo next make will overwrite the previously installed dynamic
  echo shared openssl binary with the static openssl binary
  make install

Example: Compile Net::SSLeay

To enable support for ancient protocol versions, Net::SSLeay must be

compiled manually after patching 'SSLeay.xs' (see below).

Reason is, that Net::SSLeay enables some functionality for SSL/TLS

according the identified openssl version. There is, currently (2015),

no possibility to enable this functionality by passing options on to

the configuration script perl Makefile.PL.

   echo == unpack tarball
   tar xf Net-SSLeay-1.72.tar.gz
   cd Net-SSLeay-1.72

   echo == patch files
   echo "edit SSLeay.xs and change some #if as described below"
   env OPENSSL_PREFIX=/usr/local perl Makefile.PL PREFIX=/usr/local \
         INC=/usr/local/include  DEFINE=-DOPENSSL_BUILD_UNSAFE=1
   make
   make install
   cd /tmp && o-saft.pl +version

SSLeay.xs needs to be changed as follows:

search for

   #ifndef OPENSSL_NO_SSL2
   #if OPENSSL_VERSION_NUMBER < 0x10000000L
 
   const SSL_METHOD *
   SSLv2_method()
 
   #endif
   #endif
 
   #ifndef OPENSSL_NO_SSL3
   #if OPENSSL_VERSION_NUMBER < 0x10002000L

   const SSL_METHOD *
   SSLv3_method()

   #endif
   #endif

and replace by

   const SSL_METHOD *
   SSLv2_method()

   const SSL_METHOD *
   SSLv3_method()

Note that Net::SSLeay will be installed in /usr/local/ then. This

can be adapted to your needs by passing another path to the PREFIX

and DESTDIR parameter.

Following command can be used to check which methods are avilable in

Net::SSLeay, hence above patches can be verified:

    perl -MLNet::SSLinfo -le print Net::SSLinfo::ssleay_test();

Testing OpenSSL

After installation as descibed above finished, openssl may be tested:

   echo already installed openssl (found with PATH environment)
   openssl ciphers -v
   openssl ciphers -V -ssl2
   openssl ciphers -V -ssl3
   openssl ciphers -V ALL
   openssl ciphers -V ALL:COMPLEMENTOFALL
   openssl ciphers -V ALL:eNULL:EXP

   echo own compiled and installed openssl 
   /usr/local/openssl ciphers -v
   /usr/local/openssl ciphers -V -ssl2
   /usr/local/openssl ciphers -V -ssl3
   /usr/local/openssl ciphers -V ALL
   /usr/local/openssl ciphers -V ALL:COMPLEMENTOFALL
   /usr/local/openssl ciphers -V ALL:eNULL:EXP

The difference should be obvious. Note, the commands using ALL:COMPLEMENTOFALL and ALL:eNULL:EXP should return the same result.

Testing Net::SSLeay

As we want to test the separately installed Net::SSLeay, it is best

to do it with o-saft.pl itself:

   o-saft.pl +version

we should see a line similar to follwong at the end of the output:

   Net::SSLeay   1.72  /usr/local/lib/x86_64-linux-gnu/perl/5.20.2/Net/SSLeay.pm

Now check for supported (known) ciphers:

   o-saft.pl ciphers -V

we should see lines similar to those of the last /usr/local/openssl

call. However, it should contain more cipher lines.

Stand-alone Executable

Some people asked for a stand-alone executable (mainly for Windows).

Even Perl is a scripting language there are situations where a stand-

alone executable would be nice, for example if the installed perl and

its libraries are outdated, or if perl is missing at all.

Currently (2016) there are following possibilities to generate such a

stand-alone executable:

perl with PAR::Packer module

     pp -C -c o-saft.pl
     pp -C -c o-saft.pl -M Net::DNS -M Net::SSLeay -M IO::Socket \
                        -M Net::SSLinfo -M Net::SSLhello -M osaft
     pp -C -c checkAllCiphers.pl
     pp -C -c checkAllCiphers.pl -M Net::DNS

ActiveState perl with its perlapp

     perlapp --clean o-saft.pl
     perlapp --clean o-saft.pl -M Net::DNS -M Net::SSLeay -M IO::Socket \
                 -M Net::SSLinfo -M Net::SSLhello -M osaft
     perlapp --clean checkAllCiphers.pl
     perlapp --clean checkAllCiphers.pl -M Net::DNS -M osaft

perl2exe from IndigoSTar

     perl2exe o-saft.pl
     perl2exe checkAllCiphers.pl

For details on building the executable, for example how to include

all required modules, please refer to the documentation of the tool.

Note that pre-build executables (build by perlapp, perl2exe) cannot

be provided due to licence problems.

Also note that using stand-alone executable have not been tested the

same way as the o-saft.pl itself. Use them at your own risk.

DOCKER

The tool can be used inside a Docker image. To start o-saft.pl inside

the Docker image, use following:

  o-saft-docker +info some.tld

or

  docker run --rm -it owasp/o-saft +info some.tld

For more details, please refer to:

  o-saft-docker -help
  o-saft-docker usage

BUILD DOCKER IMAGE

The Docker image can be installed as follows:

  docker pull owasp/o-saft

The image can also easily be build from the Dockerfile (which is part

of the distribution) as follows:

  o-saft-docker build

To build the image from the Dockerfile with docker commands, see:

  o-saft-docker -n build

For more details, please refer to:

  o-saft-docker -help

HACKER's INFO

Note on SSL versions

Automatically detecting the supported SSL versions of the underlaying

system is a hard job and not always possible. Reasons could be:

used Perl modules (Socket::SSL, Net::SSLeay) does not handle errors

properly. Erros may be:

  invalid SSL_version specified at ... IO/Socket/SSL.pm

  Use of uninitialized value in subroutine entry at lib/IO/Socket/SSL.pm

the underlaying libssl does not support the version, which then may

result in segmentation fault

the underlaying libssl is newer than the Perl module and the module

has not been reinstalled. This most often happens with Net::SSLeay

This can be detected with (see version numbers for Net::SSLeay):

   o-saft.pl +version

perl (in particular a used module, see above) may bail out with a

compile error, like

   Can't locate auto/Net/SSLeay/CTX_v2_new.al in @INC ...

We try to detect unsupported versions and disable them automatically,

a warning like follwoing is shown then:

   **WARNING: SSL version SSLv2 not supported by openssl

If problems occour with SSL versions, following commands and options

may help to to get closer to the reason or can be used as workaround:

   o-saft.pl +version
   o-saft.pl +version | grep versions
   o-saft.pl +version | grep 0x
   o-saft.pl +protocols your.tld
   o-saft.pl +protocols your.tld --no-rc

If problems occour with SSL versions, following commands and options

Checking for SSL version is done at one place in the code, search for

    supported SSL versions

Using private libssl.so and libcrypt.so

For all cryptographic functionality the libraries installed on the

system will be used. This is in particular Perl's Net:SSLeay module,

the system's libssl.so and libcrypt.so and the openssl executable.

It is possible to provide your own libraries, if the P module and

the executable are linked using dynamic shared objects (aka shared

library, position independent code).

The appropriate option is --lib=PATH .

On most systems these libraries are loaded at startup of the program.

The runtime loader uses a preconfigured list of directories where to

find these libraries. Also most systems provide a special environment

variable to specify additional paths to directories where to search

for libraries, for example the LD_LIBRARY_ variable.

This is the default environment variable used herein. If your system

uses another name it must be specified with the --envlibvar=NAME

option, where NAME is the name of the environment variable.

Understanding --exe=PATH, --lib=PATH, --openssl=FILE

If any of --exe=PATH or --lib=PATH is provided, the pragram calls

(exec) itself recursively with all given options, except the option

itself. The environment variables LD_LIBRARY_PATH and PATH are

set before executing as follows:

prepend PATH with all values given with --exe=PATH
prepend LD_LIBRARY_PATH with all values given with --lib=PATH

This is exactly, what Cumbersome Approach below describes. So these

option simply provide a shortcut for that.

Note that --openssl=TOOL is a full path to the openssl executable

and will not be changed. However, if it is a relative path, it might

be searched for using the previously set PATH (see above).

Note that LD_LIBRARY_PATH is the default. It can be changed with

the --envlibvar=NAME option.

While --exe mainly impacts the openssl executable, --lib also

impacts o-saft.pl itself, as it loads other shared libraries if found.

Bear in mind that all these options can affect the behaviour of the

openssl subsystem, influencing both which executable is called and

which shared libraries will be used.

NOTE that no checks are done if the options are set proper. To verify

the settings, following commands may be used:

   o-saft.pl --lib=YOU-PATH --exe=YOUE-EXE +version
   o-saft.pl --lib=YOU-PATH --exe=YOUE-EXE --v +version
   o-saft.pl --lib=YOU-PATH --exe=YOUE-EXE --v --v +version

Why so many options? Exactly as described above, these options allow

the users to tune the behaviour of the tool to their needs. A common

use case is to enable the use of a separate openssl build independent

of the openssl package used by the operating system. This allows the

user fine grained control over openssl's encryption suites which are

compiled/available, without affecting the core system.

Caveats

Depending on your system and the used modules and executables, it can

be tricky to replace the configured shared libraries with own ones.

Reasons are:

a) the linked library name contains a version number,

b) the linked library uses a fixed path,

c) the linked library is searched at a predefined path,

d) the executable checks the library version when loaded.

Only the first one a) can be circumvented. The last one d) can often

be ignored as it only prints a warning or error message.

To circumvent the "name with version number" problem try following:

1. use ldd (or a similar tool) to get the names used by openssl:

ldd /usr/bin/openssl

which returns something like:

libssl.so.0.9.8 => /lib/libssl.so.0.9.8 (0x00007f940cb6d000)

libcrypto.so.0.9.8 => /lib/libcrypto.so.0.9.8 (0x00007f940c7de000)

libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007f940c5d9000)

libz.so.1 => /lib/x86_64-linux-gnu/libz.so.1 (0x00007f940c3c1000)

libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f940c02c000)

/lib64/ld-linux-x86-64.so.2 (0x00007f940cdea000)

Here only the first two libraries are important. Both, libcrypto.so

and libssl.so need to be version "0.9.8" (in this example).

2. create a directory for your libraries, i.e.:

mkdir /tmp/dada

3. place your libraries there, assuming they are:

/tmp/dada/libssl.so.1.42

/tmp/dada/libcrypto.so.1.42

4. create symbolic links in that directory:

ln -s libssl.so.1.42 libssl.so.0.9.8

ln -s libcrypto.so.1.42 libcrypto.so.0.9.8

5. test program with following option:

   o-saft.pl +libversion --lib=/tmp/dada
   o-saft.pl +list --v   --lib=/tmp/dada

or:

   o-saft.pl +libversion --lib=/tmp/dada -exe=/path/to-openssl
   o-saft.pl +list --v   --lib=/tmp/dada -exe=/path/to-openssl

6. start program with your options, i.e.:

   o-saft.pl --lib=/tmp/dada +ciphers

This works if openssl(1) uses the same shared libraries as

Net:SSLeay(3pm), which most likely is the case.

It's tested with Unix/Linux only. It may work on other platforms also

if they support such an environment variable and the installed

Net::SSLeay(3pm) and openssl(1) are linked using dynamic shared

objects.

Depending on compile time settings and/or the location of the used

tool or lib, a warning like following may occur:

  WARNING: can't open config file: /path/to/openssl/ssl/openssl.cnf

This warning can be ignored, usually as req or ca sub commands of

openssl is not used here.

To fix the problem, either use --openssl-cnf=FILE option or set the

the environment variable OPENSSL_CONF properly.

Cumbersome Approach

A more cumbersome approach to call this program is to set following

environment variables in your shell:

  PATH=/tmp/dada-1.42/apps:$PATH
  LD_LIBRARY_PATH=/tmp/dada-1.42

Windows Caveats

I.g. the used libraries on Windows are libeay32.dll and ssleay32.dll.

Windows also supports the LD_LIBRARY_PATH environment variable. If it

does not work as expected with that variable, it might be possible to

place the libs in the same directory as the corresponding executable

(which is found by the PATH environment variable).

Using CGI mode

This script can be used as CGI application. Output is the same as in

common CLI mode, using 'Content-Type:text/plain'. Keep in mind that

the used modules like Net::SSLeay will write some debug messages

on STDERR instead STDOUT. Therefore multiple --v and/or --trace

options behave slightly different.

No additional external files like RC-FILE or DEBUG-FILE are read

in CGI mode; they are silently ignored.

Some options are disabled in CGI mode because they are dangerous or

don't make any sense.

WARNING

There are no input data validation checks implemented herein. All

input data is url-decoded once and then used verbatim.

More advanced checks must be done outside before calling this tool.

It's not recommended to run this tool in CGI mode.

You have been warned!

Using user specified code

There are some functions called within the program flow, which can be

filled with any Perl code. Empty stubs of the functions are prepared

in o-saft-usr.pm. See also USER-FILE.

DEBUG

Debugging, Tracing

Following options and commands are useful for hunting problems with

SSL connections and/or this tool. Note that some options can be given

multiple times to increase amount of listed information. Also keep in

mind that it's best to specify --v as very first argument.

Note that the file o-saft-dbx.pm is required, if any --trace*

or --v option is used.

Commands

+dump
+libversion
+s_client
+todo
+version

Options

--v
--v--
--trace
--trace-arg
--trace-cmd
--trace-key

Empty or undefined strings are written as <<undefined>> in texts.

Some parameters, in particular those of HTTP responses, are written

as <<response>>. Long parameter lists are abbreviated with ....

Output

When using --v and/or --trace options, additional output will

be prefixed with a # (mainly as first, left-most character.

Following formats are used:

#[space]

Addition text for verbosity (--v options).

#[variable name][TAB]

Internal variable name (--trace-key options).

#o-saft.pl::
#Net::SSLinfo::

Trace information for --trace options.

#{

Trace information from NET::SSLinfo for --trace options.

These are data lines in the format: #{ variable name : value #}

Note that value here can span multiple lines and ends with #}

Using outdated modules

The tools was designed to work with old Perl modules too. When using

old modules, a proper **WARNING: will be printed. These warinings

cannot be switched of using --no-warning .

The warning also informs about the missing functionality or check.

I.g. it is best to install newer versions of the module if possible.

A good practice to check if modules are available in a proper version

is to call:

 o-saft.pl +version
 o-saft.pl +version --v --v

Following example shows the result without warnings:

     === reading: ./.o-saft.pl (RC-FILE done) ===
     === reading: Net/SSLhello.pm (O-Saft module done) ===
     === reading: Net/SSLinfo.pm (O-Saft module done) ===
     === ./o-saft.pl 16.09.09 ===
         Net::SSLeay::
            ::OPENSSL_VERSION_NUMBER()    0x268443744
            ::SSLeay()                    0x268443744
         Net::SSLeay::SSLeay_version()    OpenSSL 1.0.2-chacha (1.0.2f-dev)
     = openssl =
         version of external executable   OpenSSL 1.0.2-chacha (1.0.2f-dev)
         external executable              /opt/openssl-chacha/bin/openssl
         used environment variable (name) LD_LIBRARY_PATH
         environment variable (content)   <<undef>>
         path to shared libraries         
         full path to openssl.cnf file    <<undef>>
         common openssl.cnf files         /usr/lib/ssl/openssl.cnf \
                                          /etc/ssl/openssl.cnf \
                                          /System//Library/OpenSSL/openssl.cnf \
                                          /usr/ssl/openssl.cnf
         URL where to find CRL file       <<undef>>
         directory with PEM files for CAs /opt/tools/openssl-chacha/ssl/certs
         PEM format file with CAs         /etc/ssl/certs/ca-certificates.crt
         common paths to PEM files for CAs /etc/ssl/certs /usr/lib/certs \
                                           /System/Library/OpenSSL
         common PEM filenames for CAs     ca-certificates.crt \
                                          certificates.crt certs.pem
         number of supported ciphers      177
         openssl supported SSL versions   SSLv3 TLSv1 TLSv11 TLSv12
         o-saft.pl known SSL versions     SSLv2 SSLv3 TLSv1 TLSv11 TLSv12 TLSv13 \
                                          DTLSv09 DTLSv1 DTLSv11 DTLSv12 DTLSv13
     = o-saft.pl +cipherall =
         default list of ciphers          0x03000000 .. 0x030000FF, 0x0300C000 .. 0x0300C0FF, \
                                          0x0300CC00 .. 0x0300CCFF, 0x0300FE00 .. 0x0300FFFF,
                                          
     = Required (and used) Modules =
         @INC                 ./ ./lib . /bin /usr/share/perl5 \
                              /usr/lib/x86_64-linux-gnu/perl5/5.20 \
                              /usr/lib/x86_64-linux-gnu/perl/5.20 \
                              /usr/share/perl/5.20 /usr/local/lib/site_perl .
     =   module name            VERSION  found in
     =   ----------------------+--------+------------------------------------------
         IO::Socket::INET       1.35     /usr/lib/x86_64-linux-gnu/perl/5.20/IO/Socket/INET.pm
         IO::Socket::SSL        2.002    /usr/share/perl5/IO/Socket/SSL.pm
         Net::DNS               0.81     /usr/lib/x86_64-linux-gnu/perl5/5.20/Net/DNS.pm
         Net::SSLeay            1.72     /usr/lib/x86_64-linux-gnu/perl5/5.20/Net/SSLeay.pm
         Net::SSLinfo           16.06.01 Net/SSLinfo.pm
         Net::SSLhello          16.05.16 Net/SSLhello.pm
         osaft                  16.05.10 osaft.pm

Following example shows the result with warnings:

     === reading: ./.o-saft.pl (RC-FILE done) ===
     === reading: ./Net/SSLhello.pm (O-Saft module done) ===
     **WARNING: ancient Net::SSLeay 1.35 < 1.49; cannot use ::initialize at /Net/SSLinfo.pm line 481.
     === reading: ./Net/SSLinfo.pm (O-Saft module done) ===
     **WARNING: ancient perl has no 'version' module; version checks may not be accurate; at o-saft.pl line 1662.
     **WARNING: ancient Net::SSLeay 1.35 < 1.49 detected; at o-saft.pl line 1687.
     **WARNING: ancient IO::Socket::SSL 1.22 < 1.37 detected; at o-saft.pl line 1687.
     **WARNING: ancient version IO::Socket::SSL 1.22 < 1.90 does not support SNI or is known to be buggy; SNI disabled; at o-saft.pl line 5905.
     !!Hint: --force-openssl can be used to disables this check
     **WARNING: ancient version Net::SSLeay 1.35 < 1.49  may throw warnings and/or results may be missing; at o-saft.pl line 5934.
     **WARNING: SSL version 'TLSv11': not supported by Net::SSLeay; not checked
     **WARNING: SSL version 'TLSv12': not supported by Net::SSLeay; not checked
     **WARNING: SSL version 'TLSv13': not supported by Net::SSLeay; not checked
     === o-saft.pl 16.09.09 ===
         Net::SSLeay::
            ::OPENSSL_VERSION_NUMBER()    0x9470143
     **WARNING: ancient version Net::SSLeay 1.35 < 1.49; cannot compare SSLeay with openssl version at o-saft.pl line 4778.
            ::SSLeay()                    0x1.35
     **WARNING: ancient version Net::SSLeay 1.35 < 1.49; detailed version not available at o-saft.pl line 4806.
     = openssl =
         version of external executable   OpenSSL 0.9.8y 5 Feb 2013
         external executable              /usr/bin/openssl
         used environment variable (name) LD_LIBRARY_PATH
         environment variable (content)   <<undef>>
         path to shared libraries
         full path to openssl.cnf file    <<undef>>
         common openssl.cnf files         /usr/lib/ssl/openssl.cnf \
                                          /etc/ssl/openssl.cnf \
                                          /System//Library/OpenSSL/openssl.cnf \
                                          /usr/ssl/openssl.cnf
         URL where to find CRL file       <<undef>>
         directory with PEM files for CAs /System/Library/OpenSSL/certs
         PEM format file with CAs         <<undef>>
         common paths to PEM files for CAs /etc/ssl/certs /usr/lib/certs /System/Library/OpenSSL
         common PEM filenames for CAs     ca-certificates.crt certificates.crt certs.pem
         number of supported ciphers      43
         openssl supported SSL versions   SSLv2 SSLv3 TLSv1
         o-saft.pl known SSL versions     SSLv2 SSLv3 TLSv1 TLSv11 TLSv12 TLSv13 \
                                          DTLSv09 DTLSv1 DTLSv11 DTLSv12 DTLSv13
     **WARNING: ancient version Net::SSLeay 1.35 < 1.49; cannot compare SSLeay with openssl version at o-saft.pl line 4778.
     **WARNING: used openssl version '9470143' differs from compiled Net:SSLeay '1.35'; ignored
     = o-saft.pl +cipherall =
         default list of ciphers          0x03000000 .. 0x030000FF, 0x0300C000 .. 0x0300C0FF,
                                          0x0300CC00 .. 0x0300CCFF, 0x0300FE00 .. 0x0300FFFF,
     = Required (and used) Modules =
         @INC                 ./ ./lib /bin /Library/Perl/Updates/5.10.0 \
                              /System/Library/Perl/5.10.0/darwin-thread-multi-2level \
                              /System/Library/Perl/5.10.0 \
                              /Library/Perl/5.10.0/darwin-thread-multi-2level \
                              /Library/Perl/5.10.0 \
                              /Network/Library/Perl/5.10.0/darwin-thread-multi-2level \
                              /Network/Library/Perl/5.10.0 \
                              /Network/Library/Perl \
                              /System/Library/Perl/Extras/5.10.0/darwin-thread-multi-2level \
                              /System/Library/Perl/Extras/5.10.0 .
     =   module name            VERSION  found in
     =   ----------------------+--------+------------------------------------------
         IO::Socket::INET       1.31     /System/Library/Perl/5.10.0/darwin-thread-multi-2level/IO/Socket/INET.pm
         IO::Socket::SSL        1.22     /System/Library/Perl/Extras/5.10.0/IO/Socket/SSL.pm
         Net::DNS               0.65     /System/Library/Perl/Extras/5.10.0/darwin-thread-multi-2level/Net/DNS.pm
         Net::SSLeay            1.35     /System/Library/Perl/Extras/5.10.0/darwin-thread-multi-2level/Net/SSLeay.pm
         Net::SSLinfo           16.06.01 ./Net/SSLinfo.pm
         Net::SSLhello          16.05.16 ./Net/SSLhello.pm
         osaft                  16.05.10 /osaft.pm

Please keep in mind that the shown version numbers and the shown line

numbers are examples and may differ on your system.

When starting o-saft.pl with outdated modules, more **WARNING: will

be shown. The warnings depend on the installed version of the module.

o-saft.pl is known to work with at least:

IO::Socket::INET 1.31, IO::Socket::SSL 1.22, Net::DNS 0.66, Net::SSLeay 1.30

TESTING

When talking about "testing the tool", functionl tests are meant. So

this section describes "developer" rather than "user" options.

Testing the tool is a challenging task. Beside the oddities described

elsewhere, for example Name Rodeo, there are a bunch of problems

and error which may occour during runtime.

Makefiles are used for testing functionality and code quality during

development. These tests are implemented in the ./t/ directory, see

the Makefile.* there.

Following options and commands for o-saft.pl are available to improve

testing. They mainly can simulate error conditions or stop execution

properly (they are not intended for other use cases):

+quit

Stop execution after processing all arguments and before precessing

any target. The runtime configuration is complete at this point.

--exit=KEY

Terminate o-saft.pl at specified KEY. For available KEY please see:

   o-saft.pl --help=exit
   grep exit= o-saft.pl

--cfg-init=KEY=VALUE

With this option values in the internal %cfg hash can be set:

   $cfg{KEY} = VALUE

Only (perl) scalars or arrays can be set. The type will be detected

automatically.

Example, this option can be used to change the text used as prefix

in each output line triggerd by the --v option:

   o-saft.pl --cfg-init=prefix_verbose="#VERBOSE: "

or the text used as prefix triggerd by the --trace option:

   o-saft.pl --cfg-init=prefix_trace="#TRACE: "

--v

Print more information about checks.

--trace

Print debugging messages.

For more details, please see Options for tracing and debugging .

Internal testing

Following options and commands for o-saft.pl are for internal testing.

They provide informations about internal data structures and alike.

--test-data

Print overview of all available commands and checks.

--test-maps

Print internal data strucures %cfg{openssl}, %cfg{ssleay}.

--test-prot

Print internal data according protocols.

--test-regex

Print results for applying various texts to defined regex.

--test-subs

Print formatted list of internal functions with their description.

Not to be intended in conjunction with any target check.

--test-cipher-list

Print list of hex keys of known ciphers.

--test-cipher-show

Print complete list of ciphers.

--test-cipher-sorted

Print list of ciphers sorted according strength.

EXAMPLES

($0 in all following examples is the name of the tool)

General

   o-saft.pl +cipher some.tld
   o-saft.pl +info   some.tld
   o-saft.pl +check  some.tld
   o-saft.pl +quick  some.tld
   o-saft.pl +help=commands
   o-saft.pl +list
   o-saft.pl +list --v
   o-saft.pl +certificate  some.tld
   o-saft.pl +fingerprint  some.tld 444
   o-saft.pl +after +dates some.tld

Some Specials

Get an idea how messages look like

   o-saft.pl +check --cipher=RC4 some.tld

Check for Server Name Indication (SNI) usage only

   o-saft.pl +sni some.tld

Check for SNI and print certificate's subject and altname

   o-saft.pl +sni +cn +altname some.tld

Check for all SNI, certificate's subject and altname issues

   o-saft.pl +sni_check some.tld

Only print supported ciphers

   o-saft.pl +cipher --enabled some.tld

Only print unsupported ciphers

   o-saft.pl +cipher --disabled some.tld

Test for a specific ciphers

   o-saft.pl +cipher --cipher=ADH-AES256-SHA some.tld

Test all ciphers, even if not supported by local SSL implementation

   o-saft.pl +cipherraw some.tld
   o-saft.pl +cipherall some.tld
   o-saft.pl +cipherall some.tld --range=full
   checkAllCiphers.pl example.tld --range=full --v

Show supported (enabled) ciphers with their DH parameters:

   o-saft.pl +cipher-dh some.tld

Test using a private libssl.so, libcrypto.so and openssl

   o-saft.pl +cipher --lib=/foo/bar-1.42 --exe=/foo/bar-1.42/apps some.tld

Test using a private openssl

   o-saft.pl +cipher --openssl=/foo/bar-1.42/openssl some.tld

Test using a private openssl also for testing supported ciphers

   o-saft.pl +cipher --openssl=/foo/bar-1.42/openssl --force-openssl some.tld

Show current score settings

   o-saft.pl --help=score

Change a single score setting

   o-saft.pl --cfg_score=http_https=42   +check some.tld

Use your private score settings from a file

   o-saft.pl --help=score > magic.score

# edit as needed: magic.score

   o-saft.pl --cfg_score    magic.score  +check some.tld

Use your private texts in output

   o-saft.pl +check some.tld --cfg_text=desc=my special description

Use your private texts from RC-FILE

   o-saft.pl --help=cfg_text >> .o-saft.pl

# edit as needed: .o-saft.pl

   o-saft.pl +check some.tld

Use your private hint texts in output

   o-saft.pl +check some.tld --cfg-hint=renegotiation="my special hint text"

Get the certificate's Common Name for a bunch of servers:

   o-saft.pl +cn example.tld some.tld other.tld
   o-saft.pl +cn example.tld some.tld other.tld --showhost --no-header

Generate simple parsable output

   o-saft.pl --legacy=quick --no-header +info  some.tld
   o-saft.pl --legacy=quick --no-header +check some.tld
   o-saft.pl --legacy=quick --no-header --trace-key +info  some.tld
   o-saft.pl --legacy=quick --no-header --trace-key +check some.tld

Generate simple parsable output for multiple hosts

   o-saft.pl --legacy=quick --no-header --trace-key --showhost +check some.tld other.tld

Just for curiosity

   o-saft.pl some.tld +fingerprint --format=raw
   o-saft.pl some.tld +certificate --format=raw | openssl x509 -noout -fingerprint

Testing with exit code

Test SSL/TLS connection and return exit code

   o-saft.pl +check  --exitcode  some.tld

Test ciphers and return exit code with details about exit code

   o-saft.pl +cipher --exitcode --exitcode-v  some.tld

Test ciphers and return exit code for ciphers only

   o-saft.pl +cipher --exitcode --exitcode-no-prot  some.tld

Test with exit code but avoid checks considered 'yes' even if 'no'

   o-saft.pl +check  --exitcode --ignore-out=ev- --ignore-out=rfc_7525 some.tld

Specials for hunting problems with connections etc.

Show command line argument processing

   o-saft.pl +info some.tld --trace-arg

Simple tracing

   o-saft.pl +cn   some.tld --trace
   o-saft.pl +info some.tld --trace

A bit more tracing

   o-saft.pl +cn   some.tld --trace --trace

Show internal variable names in output

   o-saft.pl +info some.tld --trace-key

Show internal argument processeing

   o-saft.pl +info --trace-arg some.tld

Show internal control flow

   o-saft.pl +info some.tld --trace-cmd

Show internal timing

   o-saft.pl +info some.tld --trace-time

Show checking ciphers

   o-saft.pl +cipher some.tld --v --v

Show values retrieved from target certificate directly

   o-saft.pl +info some.tld --no-cert --no-cert --no-cert-text=Value-from-Certificate

Show certificate CA verifications

   o-saft.pl some.tld +chain_verify +verify +error_verify +chain

Avoid most performance and timeout problems (don't use --v)

   o-saft.pl +info some.tld --no-dns --no-sni --ignore-no-conn
   o-saft.pl +info some.tld --no-dns --no-sni --no-cert --no-http --no-openssl

Identify timeout problems

   o-saft.pl +info some.tld --trace-cmd

this will show lines containing:

    #O-Saft  CMD: test ...

DOCUMENTATION

User Documentation

Documentation is mainly intented for the user, which is provided with

 o-saft.pl --help

But it may be difficult to find the proper information there. To get

more selective documentations, the --help=* options can be used. To

get an overview which --help=* options are available, use:

 o-saft.pl --help=HELP

This only provides the complete user documentation, or the well known

parts specified by the keyword, (HELP in example above). To find any

text with some lines of context, following could be used:

 o-saft.pl --help | egrep -i -C 3 "some text"

This is simply avaiable with:

 o-saft -help="some text"

In the GUI a more sophisticate search is implemented, see the "Help"

window there:

 o-saft.tcl

Developer Documentation

Documentation for developers is provided in various ways. Information

for developers can be found found in:

the files itself

with: o-saft.pl --help=HELP

using: make

ATTRIBUTION

Based on ideas (in alphabetical order) of:

cnark.pl, SSLAudit.pl sslscan, ssltest.pl, sslyze.py, testssl.sh

O-Saft - OWASP SSL advanced forensic tool

Thanks to Gregor Kuznik for this title.

cipherraw and most proxy functionality implemented by Torsten Gigler.

For re-writing some docs in proper English, thanks to Robb Watson.

Code to check heartbleed vulnerability adapted from

Steffen Ullrich (08. April 2014):

https://github.com/noxxi/p5-scripts/blob/master/check-ssl-heartbleed.pl

Colouration inspired by https://testssl.sh/ .

AUTHOR

Achim Hoffmann

VERSION

@(#) 19.09.19

Content of this wiki page generated with:

o-saft.pl --no-warning --no-header --help=gen-wiki

@@ Line 36: / Line 36: @@
 :       All  commands  and  options  can also be specified in a  rc-file, see
 :       [[#RC-FILE|RC-FILE]]  below.
+:       I.g. all commands start with a  <code>+</code>  character and options start with
+:       <code>-</code>  or  <code>--</code>  characters. Anything else is treated as target name.
 ====QUICKSTART====
@@ Line 70: / Line 73: @@
      o-saft.pl --help=examples
-:*       List all available commands:
+:* List all available commands:
      o-saft.pl --help=commands
@@ Line 79: / Line 82: @@
      o-saft.pl --help=SECURITY
-:*       Start the simple GUI
+:* Show all  --help=*  commands
+    o-saft.pl --help=HELP
+:* Search for text in O-Saft's help and show with context
+    o-saft -help=your-text
+:* Start the simple GUI
      o-saft.tcl
+:* Start the simple GUI which uses ''o-saft.pl'' in a Docker image
+    o-saft.tcl --docker
 :       For more specialised test cases, refer to the [[#COMMANDS|COMMANDS]] and [[#OPTIONS|OPTIONS]]
@@ Line 88: / Line 100: @@
 ==== WHY? ====
-:       Why a new tool for checking SSL security and configuration  when there
+:       Why a new tool for checking SSL security and configuration when there
-:       are already a dozen or more such good tools in existence (circa 2012)?
+:       are already a dozen or more such good tools in existence (in 2012)?
 :       '''Unique features:'''
@@ Line 116: / Line 128: @@
 :       For more, please see  [[#EXAMPLES|EXAMPLES]]  section below.
+:       If it should run on systems with old software (perl or Perl modules),
+:       please see  [[#DEBUG|DEBUG]]  section below.
 ==== SECURITY====
@@ Line 127: / Line 141: @@
 :Care should be taken, when additional tools and modules are installed
-:as described in  [[#INSTALLATION|INSTALLATION]]  below.  In particular  we recommend to
+:as described in  [[#INSTALLATION|INSTALLATION]]  below. In particular it is recommended
-:do such installations into directoies specially prepared for use with
+:to do these installations into directoies  specially prepared for use
-:<code>o-saft.pl</code> . No other tools of your system should use these installations
+:with <code>o-saft.pl</code> . No other tools of your system should use these installations
 :i.e. by accident or because your environment variables point to them.
@@ Line 140: / Line 154: @@
 :'''DO NOT USE THESE INSTALLATIONS ON PRODUCTIVE SYTEMS.'''
+====CONCEPTS====
+:The purpose of  O-Saft  is to do the work,  not to force the user  to
+:learn a new tool or to install "newer" software first.
+:However, the user "should do something" if necessary depending on the
+:reported results.
+=====Results=====
+:Results of checks are marked  <code>yes</code>  or <code>no</code>.  This leaves the proper
+:interpretation, if the result is "good" or "bad", to the user.
+:Background:  it is not always possible to rate a result as  "good" or
+:"bad" or "insecure" or whatever. That's why  O-Saft  can not give the
+:"the best" or a "proper" recommendation. In practice it depends on
+:the context what a recommendation or countermeasure should be. That's
+:why results are marked  <code>yes</code>  or  <code>no</code>  if considered "questionable"
+:or "not good" (for example according other checks).
+:... more comming soon ...
 ==== TECHNICAL INFORMATION====
@@ Line 146: / Line 180: @@
 :data returned by underlaying (used) libraries and the information
 :computed directly.
+===== Version 19.11.19 and later=====
+:Starting with version 19.11.19 the  +cipher  command does not use any
+:external library. Checking for ciphers is done using plain Perl code.
+:Only other collected SSL/TLS related information requires an external
+:library, in general libssl.
+:The description about OpenSSL and libssl below  applies only if any of
+:to the options <code>--ciphermode=openssl</code>  or  <code>--siphermode=ssleay</code> are given
+:with the <code>+cipher</code> command.
+:Therefore following commands and options changed:
+* <code>+cipher</code>     uses internal method
+* <code>+cipherall</code>  command obsolete, automatically changed to  <code>+cipher</code>
+* <code>+cipherraw</code>  command obsolete, automatically chnaged to  <code>+cipher</code>
+* <code>--openssl-ciphers</code>  <code>--force-openssl</code>  changed to  <code>--ciphermode=openssl</code>
+* <code>--openssl=TOOL</code>  TOOL only used for  <code>+cipher --ciphermode=openssl</code>
+* <code>--legacy=owasp</code>  option obsolete
+:The commands  <code>+cipherall</code>  and  <code>+cipherraw</code>  are "converted" to the new
+:syntax, as follows:
+  VERSION < 19.11.19           VERSION > 19.11.19
+  ----------------------------+-------------------------------
+  +cipher                      +cipher --ciphermode=ssleay
+  +cipher --force-openssl      +cipher --ciphermode=openssl
+  +cipherall                   +cipher
+  +cipherraw                   +cipher --ciphermode=intern
+  ----------------------------+-------------------------------
+===== Version < 19.11.19=====
+:Up to version 19.11.19 the default behaviour for the  <code>+cipher</code> command
+:was to use libssl. The commands  <code>+cipherall</code>  and  <code>+cipherraw</code>  did not
+:use any other library as described below.
 ===== OpenSSL, libssl, libcrypto =====
-:In general the tool uses perl's  ''Net::SSLeay(1)'' module which itself
+:In general the tool uses Perl's  ''Net::SSLeay(3pm)'' module which itself
 :is based on libssl and/or libssleay library of the operating system.
 :It's possible to use other versions of these libraries, see options:
@@ Line 162: / Line 231: @@
 :*  --openssl=TOOL
 :*  --no-openssl
-:*  --force-openssl
+:*  --openssl-ciphers  --force-openssl
 :*  --exe-path=PATH --exe=PATH
+:*  --openssl-cnf=PATH
-:Above applies to all commands except ''+cipherall'' which uses no other
+:*  --openssl-s_client --s_client
-:libraries.
 :OpenSSL is recommended to be used for libssl and libcrypto.  Versions
 :0.9.8k to 1.0.2e (Jan. 2016) are known to work. However, versions be-
 :for 1.0.0 may not provide all informations.
+:Some functionality (checks) of  O-Saft  may be missing or fail,  when
+:openssl versions 1.1.x are used (because functionality was removed).
 :LibreSSL is not recommended, because  some functionallity  considered
 :insecure, has been removed.
@@ Line 177: / Line 247: @@
 ===== Certificates and CA=====
 :All checks according the validity of the certificate chain  are based
-:on the root CAs installed on the system.  NOTE that  ''Net::SSLeay(1)''
+:on the root CAs installed on the system. Note that  ''Net::SSLeay(3pm)''
 :and  ''openssl(1)''  may have their own rules how and where to find the
 :root CAs.  Please refer to the documentation on your system for these
@@ Line 207: / Line 277: @@
 :following modules (minimal version) is required:
-:* IO             1.25 (2011)
+:* IO              1.25 (2011)
-:* IO::Socket:SSL 1.37 (2011)
+:* IO::Socket:INET 1.37 (2011)
-:* IO::Socket:SSL 1.90 (2013)
+:* IO::Socket:SSL  1.90 (2013)
-:* Net::DNS       0.66 (2011)
+:* Net::DNS        0.66 (2011)
-:* Net::SSLeay    1.49 (2012)
+:* Net::SSLeay     1.49 (2012)
 :However, it is recommended to use the most recent version of the mod-
-:ules which then gives more accurate results and less warnings.  Also
+:ules which then gives more accurate results and less warnings. If the
-:an ''openssl(1)'' executable should be available, but is not mandatory.
+:modules are missing, they can be installed i.e. with:
+   cpan Net::SSLeay
+:Note: if you want to use advanced features of openssl or Net::SSLeay,
+:please see  [[#INSTALLATION|INSTALLATION]]  section how to compile and install the tools
+:fully customized.
+:Also an ''openssl'' executable should be available, but is not mandatory.
 :For checking DH parameters of ciphers, openssl 1.0.2  or newer should
 :be available. If an older version of openssl is found, we try hard to
-:extract the DH parameters from the data returned by the server.
+:extract the DH parameters from the data returned by the server, see
+:''+cipher-dh''  command.
+:If you need to run on systems with older perl or Perl module versions
+:please refer to the  [[#DEBUG|DEBUG]]  section for more information.
 ==== RESULTS====
-:All output is designed to make be easily parsed by postprocessors. Please
+:All output is designed to be easily parsed by postprocessors. Please
 :see  [[#OUTPUT|OUTPUT]]  section below for details.
@@ Line 253: / Line 334: @@
 :** all *NULL* ciphers
 :** all *RC4*  ciphers
-:** all *EXPORT*  ciphers
+:** all *EXPORT* ciphers
 :** all *anon* (aka ADH aka DHA) ciphers
+:** all *CBC* and *CBC3* (aka 3DES) ciphers
 :* low:
-:** all *CBC*  ciphers
 :* high:
-:** all *CBC3* (aka 3DES) ciphers
 :** all *AES(128|256)* ciphers
 :** all *CAMELLIA* ciphers
@@ Line 303: / Line 383: @@
 : A list of all available commands will be printed with
-     o-saft.pl --help=cmd
+     o-saft.pl --help=cmds
 : The description of all other commands will be printed with
@@ Line 372: / Line 452: @@
 ====== +quit======
-:Show internal data and exit, used for debugging only.
+:Show internal data and exit, used for testing and debugging only.
+:Please see  [[#NTESTING|TESTING]]  below.
 ===== Commands to check SSL details=====
@@ Line 383: / Line 464: @@
 ====== +check======
-:    Check the SSL connection for security issues. This is the same as
+:    Check the SSL connection for security issues. Implies  ''+cipher'' .
-:     ''+info +cipher +sizes --sslv2 --sslv3 --tlsv1 --tlsv11 --tlsv12''
-:    but also gives some kind of scoring for security issues if any.
+====== +host +target======
+:Print details about the targets hostname, DNS, etc.
+:These details are usually printed only for the  ''+check''  and  ''+info''
+:command, but not for any individual command.
 ====== +http======
@@ Line 407: / Line 492: @@
 ====== +quick======
-:     Quick overview of checks. Implies ''--enabled''  and  ''--short''.
+:     Quick overview of checks. Implies ''--enabled''  and  ''--label=short''.
 ====== +pfs======
 : Check if servers offers ciphers with prefect forward secrecy (PFS)
+====== +protocols======
+: Check for protocols supported by target.
+====== +vulns======
+: Check for various vulnerabilities.
 ====== +sts +hsts======
@@ Line 462: / Line 555: @@
 ===== Commands to test ciphers provided by target=====
+: Beside the description of the commands itself here, please see also
+: [[#Notes about commands]]  below.
 ====== +cipher======
@@ Line 468: / Line 565: @@
 :     Note that ciphers  not supported  by the local SSL implementation
-:     are not checked by default, use ''+cipherall'' command for that.
+:     are not checked by default, use ''+cipherall'' or ''+cipherraw'' command for that.
-====== +cipherall +cipherraw======
+: Use  ''--v''  option to see all ciphers being checked.
+====== +cipherraw======
 :     Check target for all possible ciphers.
@@ Line 477: / Line 576: @@
 :    In contrast to  ''+cipher''  this command has some options to tweak
 :    the cipher tests, connection results, and some strange behaviours
-:    of the target. See [[#Options for +cipherall command]] for details.
+:    of the target. See [[#Options for  cipherall and cipherraw  command]] for details.
 <!-- other names: +allciphers +rawciphers +cipherall -->
-====== +cipher-SSL======
+====== +cipherall ======
-:     Get default cipher for protocol SSL.
+: Same as  ''+cipherraw''  but ouput format similat to  ''+cipher''  command.
-===== Commands to test SSL connection to target=====
+====== +cipher-default======
-: Please see:
+: Lists the cipher selected by the server for each protocol sometimes
+: referred to as "default cipher".
+: For each protocol the two selected ciphers are shown,  one returned
+: by the server if the cipher list in the  ClientHello is sorted with
+: the strongest cipher first, and one returned  if the cipher list in
+: the ClientHello is sorted with strongest cipher last.
+: See  [[#Notes about commands]]  for details.
-    o-saft.pl --help=commands
+====== +cipher-dh======
-===== Commands to show certificate details of the target=====
+: Checked target for ciphers. All ciphers supported by the server are
+: printed with their DH or ECDH paramaters (if available).
+: ciphers.
-: Please see:
+====== +cipher-null  +null======
-    o-saft.pl --help=commands
-===== Notes about commands=====
+:   Check if target accepts NULL ciphers.
-====== +extensions vs. +tlsextensions======
+====== +cipher-adh +adh======
-: ''+extensions''  shows the "Certificate extensions" and  ''+tlsextensions''
+:   Check if target accepts ciphers with anonymous key exchange.
-: will show the TLS protocol extensions.
-: Use  ''+tlsextdebug''  to show more informations about the TLS protocol
-: extensions.
-====== +http2 +spdy +spdy3 +spdy31 +spdy4 +prots======
+====== +cipher-exp +export======
-: These commands are just an alias for the  ''+protocols''  command.
+:   Check if target accepts EXPORT ciphers.
-==== OPTIONS====
+====== +cipher-cbc +cbc======
-: All options are written in lowercase. Words written in all capital in
+:   Check if target accepts CBC ciphers.
-: the description here is text provided by the user.
-===== Options for help and documentation=====
+====== +cipher-des +des======
-====== --h======
+:   Check if target accepts DES ciphers.
-====== --help======
+====== +cipher-rc4======
-:   WYSIWYG
+:   Check if target accepts RC4 ciphers.
-====== --help=cmd======
+====== +cipher-edh +edh======
-:   Show available commands.
+:   Check if target supports ephemeral ciphers.
-====== --help=commands======
+====== +cipher-pfs======
-:   Show available commands with short description.
+:   Check if target supports ciphers with PFS.
-====== --help=opt======
+====== +cipher-strong======
-:   Show available options; short form.
+:   Check if target selects strongest cipher.
-====== --help=options======
+====== +cipher-weak======
-:   Show available options with their description.
+:   Check if target selects weak cipher (oposite of ''+cipher-strong'').
-====== --help=checks======
+===== Discrete commands to test SSL connection and certificate details=====
-:   Show available checks.
+: Discrete commands, please see:
-====== --help=check-cfg --help=cfg-check======
+    o-saft.pl --help=commands
-:   Show texts used as labels in output for checks (see  ''+check'')  ready
+===== Notes about commands=====
-:   for use in  [[#RC-FILE|RC-FILE]]  or as option.
-====== --help=data======
+====== +cipher vs. +cipherall======
-:   Show available informations.
+: ''+cipher''  can only check for ciphers - more precise: cipher suites -
+: provided by the local SSL implementation (i.e. libssl).
+: ''+cipherall''  can check for any cipher,  as it just uses the cipher's
+: integer value in the range 0 .. 65532.
-====== --help=data-cfg --help=cfg-data======
+====== +cipherall vs. +cipherraw======
+: These commands are identical, just the output format is different.
-:   Show texts used  as labels in output for  data  (see  ''+info'')  ready
+====== +cipher vs. +cipher-default======
-:   for use in  [[#RC-FILE|RC-FILE]]  or as option.
-====== --help=hint======
+: Both commands show the default cipher foreach protocol.
-:   Show texts used in hint messages.
+: ''+cipher''  lists a summary of ciphers selected by the server for each
+: protocol requested by the user (for example by using options like:
+: ''--sslv3'' ''--tlsv1'' etc.).  When the  --v  option is used, all selected
+: ciphers for all known protocols are listed. This summary focuses on
+: counts for various ciphers.
-====== --help=hint-cfg --help=cfg-hint======
+: ''+cipher-default''  lists the  selected cipher by the server for each
+: protocol.
-:   Show texts used in hint messages ready for use in  [[#RC-FILE|RC-FILE]]  or as
+====== +cipher-selected vs. +cipher-default======
-:   option.
-====== --help=text======
+: ''+cipher-selected''  lists the cipher selected by the server if no particular
-:   Show texts used in various messages.
+: protocol was specified and the system's default cipher list is send
+: in the ClientHello to the server.
-====== --help=text-cfg --help=cfg-text======
+: ''+cipher-default''  lists the  selected cipher by the server for each
+: protocol.
-:    Show texts used in various messages ready for use in  [[#RC-FILE|RC-FILE]]  or
+====== +cipher-strong vs. +cipher-default======
-:    as option.
-====== --help=legacy======
+: ''+cipher-strong''  shows the result of the check if strong ciphers are
+: preferred by the server. It is a check command.
-:   Show possible legacy formats (used as value in  ''--legacy=KEY'').
+: ''+cipher-default''  lists the  cipher selected  by the server for each
+: protocol. It is a information command.
-====== --help=compliance======
+: It is not possible to check if a server uses 'SSLHonorCipherOrder'.
+: Even if it is used (switched on),  it is not possible to  check the
+: specified order of the ciphers.
-:   Show available compliance checks.
+: I. g. it is expected that the order is according the cipher suite's
+: strength, meaning the most strongest first, and the weakest last.
+: It does not make sense to use an order where a weak cipher preceeds
+: a stronger one. Such a (mis-)configuration should be detected.
-====== --help=intern======
+: Having this in mind, the algorithm to detect a  proper cipher order
+: is as simply as follows:
+. pass sorted cipher list with strongest cipher first
+. pass sorted cipher list with strongest cipher last
+: if the server returns the same cipher for both checks, it's assumed
+: that it prefers to use the most strongest cipher. In this case it's
+: obvious that 'SSLHonorCipherOrder' is set (exceptions see below).
-:   Show internal commands.
+: ''+cipherall''  uses a  more accurate algorithm  to detect the server's
+: cipher order.
-====== --help=range======
+: '''Exceptions:'''
+: If either, the server or the client,  uses only one cipher suite in
+: the list, SSLHonorCipherOrder cannot be detected at all.
+: The same happens, if only one cipher in the client's list matches a
+: cipher in the server's list.
-:   Show list of cipherranges (see ''--cipherrange=RANG'').
+====== +extensions vs. +tlsextensions======
-====== --help=score======
+: ''+extensions''  shows the "Certificate extensions" and  ''+tlsextensions''
+: will show the TLS protocol extensions.
+: Use  ''+tlsextdebug''  to show more informations about the TLS protocol
+: extensions.
-:   Show score value for each check.
+====== +http2 +spdy +spdy3 +spdy31 +spdy4 +prots======
-:   Value is printed in format to be used for  ''--cfg_score=KEY=SCORE''.
-:   Note that the  sequence  of options  is important.  Use the options
+: These commands are just an alias for the  ''+protocols''  command.
-:   ''--trace''  and/or  ''--cfg_score=KEY=SCORE''  before  ''--help=score''.
-====== --help=toc  --help=content======
+====== +hostname vs. +wildhost vs. +altname vs. +rfc_2818======
-:   Show headlines from help textsUseful to get an overview.
-====== --help=SECTION======
+:The commands  ''+cn''  and  ''+altname''  print the  information stored  in
+:the certificate.
+:The command  ''+hostname''  checks if the given hostname matches the CN
+:value in the certificate.  Note that wildcard names in the CN, only
+:allow to contain one '*'.
+:The command  ''+wildcard''  checks if the given hostname does not match
+:any name specified in the certificate's "subjectAltname". This check
+:is useful  if the certificate and the configuration  must comply to
+:RFC 6125 or EV certificates.
-:   Show  <SECTION>  from documentation, see  ''--help=toc''  for a list.
+==== OPTIONS====
-:   Example:
-      o-saft.pl --help=EXAMPLES
-====== --help=regex======
+: All options are written in lowercase. Words written in all capital in
+: the description here is text provided by the user.
-:   Show regular expressions used internally.
+===== Options for help and documentation=====
-====== --help=gen-html======
+====== --h======
-:  Show help text in HTML format.
+====== --help======
-====== --help=gen-wiki======
+:   WYSIWYG
-:  Show help text in mediawiki format.
+====== --help=help ======
+:Show available options to show descriptions (this Options section).
-====== --help=gen-cgi======
+====== --help=cmds======
-:  Generate HTML page with o-saft.cgi as form action..
+:   Show available commands.
-====== --help=error --help=warning --help=problem ======
+====== --help=commands======
-:Show  [[#KNOWN PROBLEMS|KNOWN PROBLEMS]]  section with  description of known  error and
+:   Show available commands with short description.
-:warning messages.
-====== --help=FAQ ======
+====== --help=opt======
-:Show  [[#KNOWN PROBLEMS|KNOWN PROBLEMS]]  and  [[#LIMITATIONS|LIMITATIONS]]  section.
+:   Show available options; short form.
-====== --help=glossar======
+====== --help=options======
-:  Show common abbreviation used in the world of security.
+:   Show available options with their description.
-====== --help=todo======
+====== --help=checks======
-:  Show known problems and bugs.
+:   Show available checks.
-===== Options for all commands (general)=====
+====== --help=tools======
-====== --no-rc======
-:   Do not read  [[#RC-FILE|RC-FILE]] .
+:Description of tools around O-Saft, when, where and how to use.
-====== --dns======
+====== --help=cmd======
-:   Do DNS lookups to map given hostname to IP, do a reverse lookup.
+:Show additional and user specified commands.
-====== --no-dns======
+====== --help=cfg-cmd======
-:   Do not make DNS lookups.
+:Show additional and user specified commands.  Output can be used in
-:   Note  that the corresponding IP and reverse hostname may be missing
+:[[#RC-FILE|RC-FILE]]  or as option.
-:   in some messages then.
-====== --host=HOST======
+====== --help=check-cfg --help=cfg-check======
-:   Specify <code>HOST</code> as target to be checked. Legacy option.
+:   Show texts used as labels in output for checks (see  ''+check'')  ready
+:   for use in  [[#RC-FILE|RC-FILE]]  or as option.
-====== --port=PORT======
+====== --help=data======
-:   Specify target's <code>PORT</code> to be used. Legacy option.
+:   Show available informations.
-====== --host=HOST --port=PORT HOST:PORT HOST======
+====== --help=data-cfg --help=cfg-data --help=cfg-info======
-:   When giving more than one HOST argument,  the sequence of the given
+:   Show texts used  as labels in output for  data  (see  ''+info'')  ready
-:   HOST argument and the given  ''--port=PORT''  and the given ''--host=HOST''
+:   for use in  [[#RC-FILE|RC-FILE]]  or as option.
-:   options are important.
-:   The rule how ports and hosts are mapped is as follows:
-:   *    HOST:PORT arguments are used as is (connection to HOST on PORT)
-:   *    only HOST is given, then previous specified ''--port=PORT'' is used
-:   Note that URLs are treated as HOST:PORT, if they contain a port.
-:   Example:
-    o-saft.pl +cmd host-1 --port 23 host-2 host-3:42 host-4
-:   will connect to:
-       host-1:443
-       host-2:23
-       host-3:42
-       host-4:23
-====== --proxyhost=PROXYHOST --proxy=PROXYHOST:PROXYPORT======
+====== --help=hint======
-:Make all connection to target using <code>PROXYHOST</code>.
+:   Show texts used in hint messages.
-:Also possible is: ''--proxy=PROXYUSER:PROXYPASS@PROXYHOST:PROXYPORT''
+====== --help=hint-cfg --help=cfg-hint======
-====== --proxyport=PROXYPORT======
+:   Show texts used in hint messages ready for use in  [[#RC-FILE|RC-FILE]]  or as
+:   option.
-:   Make all connection to target using PROXYHOST:PROXYPORT.
+====== --help=text======
+:   Show texts used in various messages.
-====== --proxyuser=PROXYUSER======
+====== --help=text-cfg --help=cfg-text======
-:   Specify username for proxy authentication.
+:    Show texts used in various messages ready for use in  [[#RC-FILE|RC-FILE]]  or
+:    as option.
-====== --proxypass=PROXYPASS======
+====== --help=legacy======
-:   Specify password for proxy authentication.
+:   Show possible legacy formats (used as value in  [[#--legacy=KEY|--legacy=KEY]]).
-:   ''--proxy=PROXYUSER:PROXYPASS@PROXYHOST:PROXYPORT'' is also possible.
-====== --starttls======
+====== --help=compliance======
-:  Use <code>STARTTLS</code> command to start a TLS connection via SMTP.
+:   Show available compliance checks.
-:  This option is a shortcut for  ''--starttls=SMTP''
-====== --starttls=PROT======
+====== --help=intern======
-:  Use <code>STARTTLS</code> command to start a TLS connection via protocol.
+:   Show internal commands.
-:  <code>PROT</code>  may be any of:  <code>SMTP</code>, <code>IMAP</code>, <code>IMAP2</code>, <code>POP3</code>, <code>FTPS</code>, <code>LDAP</code>, <code>RDP</code>, <code>XMPP</code>
-:  For  ''--starttls=SMTP'' see  ''--dns-mx''  also to use MX records instead
+====== --help=range======
-:  of host
+: Show list of cipherranges (see [[#--cipherrange=RANGE--cipherrange=RANGE]]).
-====== --starttls-delay=SEC======
+====== --help=alias======
+: Show alias for commands and options.
-:  Number of seconds to wait before sending a packet, to slow down the
+====== --help=pattern======
-:  <code>STARTTLS</code> requests. Default is 0.
+: Show list of cipher pattern (used for  [[#--cipher=CIPHER|--cipher=CIPHER]]).
-:  This may prevent blocking of requests by the target due to too much
-:  or too fast connections.
-:  Note:  In this case there is an automatic suspension and retry with
-:  a longer delay.
-====== --cgi, --cgi-exec======
+====== --help=score======
-:  Internal use for CGI mode only.
+:   Show score value for each check.
+:   Value is printed in format to be used for  ''--cfg_score=KEY=SCORE''.
-===== Options for SSL tool=====
+:   Note that the  sequence  of options  is important.  Use the options
+:   ''--trace''  and/or  ''--cfg_score=KEY=SCORE''  before  ''--help=score''.
-====== --s_client======
+====== --help=toc  --help=content======
+:   Show headlines from help textsUseful to get an overview.
-:   Use  <code>openssl s_slient ...</code> call to retrieve more informations from
+====== --help=SECTION======
-:   the SSL connection.  This is disabled by default on Windows because
-:   of performance problems. Without this option (default on Windows !)
-:   following informations are missing on Windows:
-       compression, expansion, renegotiation, resumption,
-       selfsigned, verify, chain, protocols, DH parameters
-:   See ''Net::SSLinfo'' for details.
-:   If used together with ''--trace'', s_client data will also be printed
+:   Show  <code>SECTION</code>  from documentation, see  [[#--help=toc|--help=toc]]  for a list.
-:   in debug output of ''Net::SSLinfo''.
+:   Example:
+      o-saft.pl --help=EXAMPLES
-====== --no-openssl======
+====== --help=regex======
+:   Show regular expressions used internally.
-:   Do not use external <code>openssl</code> tool to retrieve informations. Use of
+====== --help=gen-html======
-:   <code>openssl</code> is disabled by default on Windows.
-:   Note that this results in some missing informations, see above.
-====== --openssl=TOOL======
+:  Show help text in HTML format.
-:   <code>TOOL</code>      can be a path to openssl executable;  default: openssl
+====== --help=gen-pod======
-====== --openssl-cnf=FILE --openssl-conf=FILE======
+:  Show help text in POD format.
-: <code>FILE</code>        path of directory or full path of openssl.cnf
+====== --help=gen-wiki======
-:If set, environment variable OPENSSL_CONF will be set to given path
+:  Show help text in mediawiki format.
-:(or file) when ''openssl(1)'' is started. Please see openssl's man page
-:for details about specifying alternate  openssl.cnf  files.
-====== --force-openssl======
+====== --help=gen-cgi======
-:   Use openssl to check for supported ciphers;  default: IO::Socket
+:  Generate HTML page with o-saft.cgi as form action..
-:   This option forces to use  <code>openssl s_slient -connect CIPHER ..</code> to
+====== --help=error --help=warning --help=problem ======
-:   check if a cipher is supported by the remote target. This is useful
-:   if the ''--lib=PATH'' option doesn't work (for example due to changes
-:   of the API or other incompatibilities).
-====== --exe-path=PATH --exe=PATH======
+:Show  [[#KNOWN PROBLEMS|KNOWN PROBLEMS]]  section with  description of known  error and
+:warning messages.
-:   <code>PATH</code>      is a full path where to find openssl.
+====== --help=FAQ ======
-====== --lib-path=PATH --lib=PATH======
+:Show  [[#KNOWN PROBLEMS|KNOWN PROBLEMS]]  and  [[#LIMITATIONS|LIMITATIONS]]  section.
-:   <code>PATH</code>      is a full path where to find libssl.so and libcrypto.so
+====== --help=glossar======
-:   See [[#HACKER's INFO|HACKER's INFO]] below for a detailed description how it works.
+:  Show common abbreviation used in the world of security.
-====== --envlibvar=NAME======
+====== --help=links======
+:  Show list of URLs related to SSL/TLS.
-:   <code>NAME</code>  is the name of a environment variable containing additional
+====== --help=rfc======
-:   paths for searching dynamic shared libraries.
+:  Show list of RFC related to SSL/TLS.
-:   Default is LD_LIBRARY_PATH .
-:   Check your system for the proper name, i.e.:
+====== --help=todo======
-:       DYLD_LIBRARY_PATH, LIBPATH, RPATH, SHLIB_PATH .
+:  Show known problems and bugs.
-====== --ssl-lazy======
+====== --help=exit======
+:  Show possible  ''--exit=KEY''  options. Used for debugging only.
-:   if the ''--lib=PATH'' option doesn't work (for example due to changes
+====== --help=program.code======
-:   I.g. this tools tries to identify available functionality according
+:  For developers.
-:   SSL versions from the underlaying libraries.  Unsupported  versions
-:   are then disables and a warning is shown.
-:   Unfortunately some libraries have  not implemented all functions to
-:   check availability of a specific SSL version, which then results in
-:   a compile error.
-:   This option disables the strict check of availability.
+===== Options for all commands (general)=====
-:   If the underlaying library doesn't support the required SSL version
+====== --dns======
-:   at all, following error may occour:
-       Can't locate auto/Net/SSLeay/CTX_v2_new.al in @INC ...
-====== -v======
+:   Do DNS lookups to map given hostname to IP, do a reverse lookup.
-:  Print list of ciphers in style like: <code>openssl ciphers -v</code>.
+====== --no-dns======
-:  Option used with  ''+ciphers''  command only.
-====== -V======
+:   Do not make DNS lookups.
+:   Note  that the corresponding IP and reverse hostname may be missing
+:   in some messages then.
-:  Print list of ciphers in style like: <code>openssl ciphers -V</code>.
+====== --host=HOST======
-:  Option used with  ''+ciphers''  command only.
-===== Options for SSL connection to target=====
+:   Specify <code>HOST</code> as target to be checked. Legacy option.
-====== --cipher=CIPHER======
-* <code>CIPHER</code>    can be any string accepeted by openssl or following:
+====== --port=PORT======
-* <code>yeast</code>     use all ciphers from list defined herein, see ''+list''
-:  Beside the cipher names accepted by openssl, CIPHER can be the name
+:   Specify target's <code>PORT</code> to be used. Legacy option.
-:  of the constant or the (hex) value as defined in openssl's files.
-:  Currently supported are the names and constants of openssl 1.0.1k .
-:  Example:
-* --cipher=DHE_DSS_WITH_RC4_128_SHA
-* --cipher=0x03000066
-* --cipher=66
-:  will be mapped to   DHE-DSS-RC4-SHA
-:  Note: if more than one cipher matches, just one will be selected.
+====== --host=HOST --port=PORT HOST:PORT HOST======
-:
-:  Default is <code>ALL:NULL:eNULL:aNULL:LOW</code> as specified in Net::SSLinfo
-====== --ignore-no-connect======
+:   When giving more than one HOST argument,  the sequence of the given
+:   HOST argument and the given  ''--port=PORT''  and the given ''--host=HOST''
+:   options are important.
+:   The rule how ports and hosts are mapped is as follows:
+:   *    HOST:PORT arguments are used as is (connection to HOST on PORT)
+:   *    only HOST is given, then previous specified ''--port=PORT'' is used
+:   Note that URLs are treated as HOST:PORT, if they contain a port.
+:   Example:
+    o-saft.pl +cmd host-1 --port 23 host-2 host-3:42 host-4
+:   will connect to:
+       host-1:443
+       host-2:23
+       host-3:42
+       host-4:23
-:  A simple check if the target can be connected  will be performed by
+====== --proxyhost=PROXYHOST --proxy=PROXYHOST:PROXYPORT======
-:  default.  If this check fails, the target will be ignored, means no
-:  more reuqested checks will be done.  As this connection check some-
-:  times fails due to various reasons, the check can be disabled using
-:  this option.
-====== --no-md5-cipher======
+:Make all connection to target using <code>PROXYHOST</code>.
-:  Do not use *-MD5 ciphers for other protocols than SSLv2.
+:Also possible is: ''--proxy=PROXYUSER:PROXYPASS@PROXYHOST:PROXYPORT''
-:  This option is only effective with  ''+cipher''  command.
-:  The purpose is to avoid warnings from  IO::Socket::SSL  like:
+====== --proxyport=PROXYPORT======
-         Use of uninitialized value in subroutine entry at lib/IO/Socket/SSL.pm line 430.
-:  which occours with some versions of  IO::Socket::SSL  when a  *-MD5
-:  ciphers will be used with other protocols than SSLv2.
-:  Note that these ciphers will be checked for SSLv2 only.
+:   Make all connection to target using PROXYHOST:PROXYPORT.
-====== --SSL, -protocol SSL======
+====== --proxyuser=PROXYUSER======
-====== --no-SSL======
+:   Specify username for proxy authentication.
-* <code>SSL</code>       can be any of:
-:ssl, ssl2, ssl3, sslv2, sslv3, tls1,
-:tls1, tls11, tls1.1, tls1-1, tlsv1, tlsv11, tlsv1.1, tlsv1-1
-:(and similar variants for tlsv1.2).
-:For example  ''--tls1''  ''--tlsv1''  ''--tlsv1_1''  are all the same.
-:  (''--SSL'' variants):    Test ciphers for this SSL/TLS version.
+====== --proxypass=PROXYPASS======
-:  (''--no-SSL'' variants): Don't test ciphers for this SSL/TLS version.
-====== --no-tcp======
+:   Specify password for proxy authentication.
-:Shortcut for:
+:   ''--proxy=PROXYUSER:PROXYPASS@PROXYHOST:PROXYPORT'' is also possible.
-:''--no-sslv2 --no-sslv3 --no-tlsv1 --no-tlsv11 --no-tlsv12 --no-tlsv13''
-====== --tcp======
+====== --starttls======
-:Shortcut for:  ''--sslv2 --sslv3 --tlsv1 --tlsv11 --tlsv12 --tlsv13''
+:  Use <code>STARTTLS</code> command to start a TLS connection via SMTP.
+:  This option is a shortcut for  ''--starttls=SMTP''
-====== --no-udp======
+====== --starttls=PROT======
-:Shortcut for:
+:  Use <code>STARTTLS</code> command to start a TLS connection via protocol.
-:''--no-dtlsv09 --no-dtlsv1 --no-dtlsv11 --no-dtlsv12 --no-dtlsv13''
+:  <code>PROT</code>  may be any of:  <code>SMTP</code>, <code>IMAP</code>, <code>IMAP2</code>, <code>POP3</code>, <code>FTPS</code>, <code>LDAP</code>, <code>RDP</code>, <code>XMPP</code>
-====== --udp======
+:  For  ''--starttls=SMTP'' see  ''--dns-mx''  also to use MX records instead
+:  of host
-:Shortcut for:  ''--dtlsv09 --dtlsv1 --dtlsv11 --dtlsv12 --dtlsv13''
+====== --starttls-delay=SEC======
-====== --nullsslv2======
+:  Number of seconds to wait before sending a packet, to slow down the
-:  This option  forces  to assume that  SSLv2  is enabled  even if the
+:  <code>STARTTLS</code> requests. Default is 0.
-:  target does not accept any ciphers.
+:  This may prevent blocking of requests by the target due to too much
+:  or too fast connections.
+:  Note:  In this case there is an automatic suspension and retry with
+:  a longer delay.
-:  The target server may accept connections with  SSLv2  but not allow
+====== --cgi, --cgi-exec======
-:  any cipher. Some checks verify if  SSLv2  is enabled at all,  which
-:  then would result in a failed test.
-:  The default behaviour is to assume that  SSLv2 is not enabled if no
-:  ciphers are accepted.
-:
-====== --http======
-:  Make a HTTP request if cipher is supported.
+:  Internal use for CGI mode only.
-:  If used twice debugging will be enabled using  environment variable
+===== Options for SSL tool=====
-:  <code>HTTPS_DEBUG</code> .
+====== --no-rc======
-====== --no-http======
+: Do not read  [[#RC-FILE|RC-FILE]] .
-:
-:  Do not make HTTP request.
-:
-====== --sni======
-:
-:  Make SSL connection in SNI mode.
-:
-====== --no-sni======
-:  Do not make SSL connection in SNI mode (default: SNI mode).
+====== --rc======
-====== --sni-toggle --toggle-sni ======
+: Read  [[#RC-FILE|RC-FILE]]  if exists, from directory where program was found.
-: Test with and witout SNI mode.
+====== --rc=path/to/FILE ======
-====== --force-sni======
+: Read  [[#RC-FILE|RC-FILE]]  <code>path/to/FILE</code> if exists.
-:  Do not check if SNI seems to be supported by ''Net::SSLeay(1)''.
+====== --exitcode======
-:  Older versions of openssl and its libries do not support SNI or the
+:The exit status code will be greater 0, if any of following applies:
-:  SNI support is implemented buggy. By default it's checked if SNI is
+:* any check returns  <code>no</code>, except if  <code>no (<<...>>)</code>
-:  properly supported. With this option this check can be disabled.
+:* insecure protocols are available
+:* insecure ciphers are supported
+:* ciphers without PFS are supported
+:In particular, the status code will be the total count of all these
+:checks. The status code will also be printed at end, like:
+    # EXIT 23
-:  Be warned that this may result in improper results.
+:Parts of these checks can be diasabled,  see  ''--exitcode-*''  options
+:below.
-====== --servername=NAME======
+:Use  ''--v''  or  ''--exitcode-v'' to see details about the performed checks.
-====== --sni-name=NAME======
-:  Use  <code>NAME</code>  instead of given hostname to connect to  target in SNI
+:Functionality implemented experimental, may change in future.
-:  mode. By  default,  <code>NAME</code>  is automatically set to the given FQDN.
-:  This is insufficient, when an IP instead of a FQDN was given,  then
-:  the connection needs to specify the correct hostname (i.g. a FQDN).
-:  For historical reason, the value <code>1</code> is the same as if the the real
+======--exitcode-v======
-:  FQDN (given hostname) has been used.  If the value is empty, or the
+:Print information about performed checks.
-:  value <code>0</code> is given, no SNI name will be used.
-:  Note: i.g. there is no need to use this option,  as a correct value
+======--exitcode-quiet======
-:  for the SNI name will be choosen automatically (except for IPs).
+:Do not print status code at end like <code># EXIT 23</code>.
-:  However, it's kind of fuzzing ...
-====== --no-cert======
+====== --exitcode-no-checks======
-:
+:Do not count checks with result 'no' for  ''--exitcode'' .
-:  Do not get data from target's certificate, return empty string.
-:
-====== --no-cert --no-cert======
-:
-:  Do not get data from target's certificate, return default string
-:  of ''Net::SSLinfo'' (see  ''--no-cert-text TEXT''  option).
-:
-====== --no-cert-text=TEXT======
+====== --exitcode-no-low  --exitcode-no-weak  --exitcode-no-medium======
-:
+:Do not count <code>LOW</code>, <code>WEAK</code> or <code>MEDIUM</code> security ciphers for  ''--exitcode'' .
-:  Set  <code>TEXT</code>  to be returned from  <code>Net::SSLinfo.pm</code> if no certificate
-:  data is collected due to use of  ''--no-cert''.
-:
-====== --ca-depth=INT======
+====== --exitcode-no-ciphers======
-:
+:Do not count any ciphers for  ''--exitcode'' .
-:  Check certificate chain to depth  <code>INT</code> (like openssl's -verify).
-:
-====== --ca-file=FILE======
+====== --exitcode-no-pfs======
-:
+:Do not count ciphers without PFS for  ''--exitcode'' .
-:  Use  <code>FILE</code>  with bundle of CAs to verify target's certificate chain.
-:
-====== --ca-path=DIR======
+====== --openssl-s_client --s_client======
-:
-:  Use  <code>DIR</code>  where to find CA certificates in PEM format.
-:
-====== --no-nextprotoneg======
+:   Use  <code>openssl s_slient ...</code> call to retrieve more informations from
-:
+:   the SSL connection.  This is disabled by default on Windows because
-:  Do not use  <code>-nextprotoneg</code>  option for openssl.
+:   of performance problems. Without this option (default on Windows !)
-:
+:   following informations are missing:
-====== --no-reconnect======
+       compression, expansion, renegotiation, resumption,
-:
+       selfsigned, verify, chain, protocols, DH parameters
-:  Do not use  <code>-reconnect</code>  option for openssl.
+:   See ''Net::SSLinfo'' for details.
-:
-====== --no-tlsextdebug======
-:
-:  Do not use  <code>-tlsextdebug</code>  option for openssl.
-:
-====== --sclient-opt=VALUE======
-:
-:  Argument or option passed to openssl s_client command.
-:
-===== Options for ''+cipherall''  command =====
-====== --range=RANGE ======
+:   If used together with ''--trace'', s_client data will also be printed
-====== --cipherrange=RANGE======
+:   in debug output of ''Net::SSLinfo''.
-:  Specify range of cipher constants to be tested by  ''+cipherall'' .
+====== --no-openssl======
-:  Following <code>RANGE</code>s are supported:
-*  <code>rfc</code>             all ciphers defined in various RFCs
+:   Do not use external <code>openssl</code> tool to retrieve informations. Use of
-*  <code>shifted</code>         <code>rfc</code>, shifted by 64 bytes to the right
+:   <code>openssl</code> is disabled by default on Windows.
-*  <code>long</code>            like <code>rfc</code> but more lazy list of
+:   Note that this results in some missing informations, see above.
-*  <code>huge</code>            all constants  0x03000000 .. 0x0300FFFF
-*  <code>safe</code>            all constants  0x03000000 .. 0x032FFFFF
-*  <code>full</code>            all constants  0x03000000 .. 0x0300FFFF
-*  <code>SSLv2</code>           all ciphers according RFC for SSLv2
-:Note: <code>SSLv2</code> is the internal list used for testing SSLv2 ciphers.
+====== --openssl=TOOL======
-:It does not make sense to use it for other protocols; however ...
-====== --slow-server-delay=SEC======
+:   <code>TOOL</code>      can be a path to openssl executable;  default: openssl
-:  Additional delay in seconds  after the server is connected  using a
+====== --openssl-cnf=FILE --openssl-conf=FILE======
-:  proxy or before starting STARTTLS.
-:  This is useful when connecting via  slow proxy chains or connecting
-:  to slow servers before sending the STARTTLS sequence.
-====== --ssl-maxciphers=CNT ======
+: <code>FILE</code>        path of directory or full path of openssl.cnf
-:  Maximal number of ciphers sent in a sslhello (default: 32).
+:If set, environment variable OPENSSL_CONF will be set to given path
+:(or file) when ''openssl(1)'' is started. Please see openssl's man page
+:for details about specifying alternate  openssl.cnf  files.
-====== --ssl-double-reneg======
+====== --openssl-ciphers --force-openssl======
-:  Send SSL extension  "reneg_info"  even if list of ciphers includes
+:   Use openssl to check for supported ciphers;  default: IO::Socket
-:  TLS_EMPTY_RENEGOTIATION_INFO_SCSV (default: do not include)
-====== --ssl-nodata-nocipher======
+:   This option forces to use  <code>openssl s_slient -connect CIPHER ..</code> to
+:   check if a cipher is supported by the remote target. This is useful
+:   if the ''--lib=PATH'' option doesn't work (for example due to changes
+:   of the API or other incompatibilities).
-:  Do not abort testing for next cipher when the target  responds with
+====== --exe-path=PATH --exe=PATH======
-:  "NoData" times out. Useful for TLS intolerant servers.
-:  By default testing for ciphers is aborted  when the target responds
-:  with "noData message.
-====== --ssl-use-ecc======
+:   <code>PATH</code>      is a full path where to find openssl.
-:  Use supported elliptic curves.  Default on.
+====== --lib-path=PATH --lib=PATH======
-====== --ssl-use-ec-point======
+:   <code>PATH</code>      is a full path where to find libssl.so and libcrypto.so
-:  Use TLS "ec_point_formats" extension.  Default on.
+:   See [[#HACKER's INFO|HACKER's INFO]] below for a detailed description how it works.
-====== --ssl-use-reneg======
+====== --envlibvar=NAME======
-:  Test for ciphers with "secure renegotiation" flag set.
+:   <code>NAME</code>  is the name of a environment variable containing additional
-:  Default: don't set "secure renegotiation" flag.
+:   paths for searching dynamic shared libraries.
+:   Default is LD_LIBRARY_PATH .
-====== --ssl-retry=CNT======
+:   Check your system for the proper name, i.e.:
+:       DYLD_LIBRARY_PATH, LIBPATH, RPATH, SHLIB_PATH .
-:  Number of retries when connection timed-out (default: 2).
+====== --ssl-error======
+: The connection to  a target may fail, or even block, due to various
+: reasons, for example lost network at all, blocking at firewall, etc.
+: In particular when checking ciphers with  [[++cipher|+cipher]] , this may result
+: in long delays until results are printed.
+: Using this option stops trying to do more connections to the target
+: when  [[#--ssl-error-max=CNT|--ssl-error-max=CNT]]  consecutive errors occoured, or if the total
+: amount of errors increases  [[#--ssl-error-total=CNT|--ssl-error-total=CNT]].
-====== --ssl-timeout=SEC======
+====== --ssl-error-max=CNT======
+: Max. amount of consecutive errors (default: 5).
-:  Number of seconds to wait until connection is qualified as timeout.
+====== --ssl-error-timeout=SEC======
+: Timeout in seconds when a failed connection is treated as error and
+: then counted (default: 1).
+====== --ssl-error-total=CNT======
+: Max. total amount of errors (default: 10).
+====== --ssl-lazy======
-====== --dns-mx, --mx======
+:   I.g. this tools tries to identify available functionality according
+:   SSL versions from the underlaying libraries.  Unsupported  versions
+:   are then disables and a warning is shown.
+:   Unfortunately some libraries have  not implemented all functions to
+:   check availability of a specific SSL version, which then results in
+:   a compile error.
-:  Get DNS MX records for given target and check the returned targets.
+:   This option disables the strict check of availability.
-:  (only useful with  ''--starttls=SMTP'')
+:   If the underlaying library doesn't support the required SSL version
+:   at all, following error may occour:
+       Can't locate auto/Net/SSLeay/CTX_v2_new.al in @INC ...
-===== Options for checks and results=====
+====== --timeout=SEC======
-:
-:Options used for  ''+check''  command:
-:
-====== --enabled======
-:
-:  Only print result for ciphers accepted by target.
-:
-====== --disabled======
-:
-:  Only print result for ciphers not accepted by target.
-:
-====== --ignorecase======
-:
-:  Checks are done case insensitive.
-:
-====== --no-ignorecase======
-:  Checks are done case sensitive. Default: case insensitive.
+:  Timeout in seconds when connecting to the target (default: 2).
-:  Currently only checks according CN, alternate names in the target's
-:  certificate compared to the given hostname are effected.
-===== Options for output format=====
+====== -v======
-:
-====== --short======
-:
-:  Use short less descriptive text labels for  ''+check''   and  ''+info''
-:  command.
-:
-====== --legacy=TOOL======
-:  For compatibility with other tools,  the output format used for the
+:  Print list of ciphers in style like: <code>openssl ciphers -v</code>.
-:  result of the ''+cipher'' command can be adjusted to mimic the format
+:  Option used with  ''+ciphers''  command only.
-:  of other SSL testing tools.
-:  The argument to the ''--legacy=TOOL''  option is the name of the tool
+====== -V======
-:  to be simulated.
-:  Following <code>TOOL</code>s are supported:
+:  Print list of ciphers in style like: <code>openssl ciphers -V</code>.
+:  Option used with  ''+ciphers''  command only.
-*  <code>sslaudit</code>        format of output similar to  sslaudit
+===== Options for SSL connection to target=====
-*  <code>sslcipher</code>       format of output similar to  ssl-cipher-check
+====== --ciphermode=MODE======
-*  <code>ssldiagnos</code>      format of output similar to  ssldiagnos
-*  <code>sslscan</code>         format of output similar to  sslscan
-*  <code>ssltest</code>         format of output similar to  ssltest
-*  <code>ssltestg</code>        format of output similar to  ssltest -g
-*  <code>ssltest-g</code>       format of output similar to  ssltest -g
-*  <code>sslyze</code>          format of output similar to  sslyze
-*  <code>ssl-cipher-check</code>      same as sslcipher
-*  <code>ssl-cert-check</code>  format of output similar to  ssl-cert-check
-*  <code>testsslserver</code>   format of output similar to  TestSSLServer.jar
-* <code> thcsslcHeck</code>     format of output similar to  THCSSLCheck
-:  Note that these legacy formats only apply to  output of the checked
+Following <code>MODE</code>s are supported:
-:  ciphers. Other texts like headers and footers are adapted slightly.
+* <code>intern</code>    scan for ciphers using internal method; (default)
+* <code>openssl</code>   scan for ciphers using external openssl executable
+* <code>ssleay</code>    scan for ciphers using  IO::Socket  and  Net::SSLeay
+* <code>dump</code>      same as <code>intern</code> but print  all cipher informations,
+:                         useful when postprocessed by contrib/* tools
-:  Please do not expect identical output as the <code>TOOL</code>  when using these
+====== --cipher=CIPHER======
-:  options, it's a best guess and should be parsable in a very similar
-:  way.
-======--legacy=compact======
+<code>CIPHER</code> can be any string accepted by openssl or following:
+* <code>yeast</code>     use all ciphers from list defined herein, see ''+list''
-:Internal format: mainly avoid tabs and spaces format is as follows:
+:  Beside the cipher names accepted by openssl, CIPHER can be the name
-  Some Label:<-- anything right of colon is data
+:  of the constant or the (hex) value as defined in openssl's files.
+:  Currently supported are the names and constants of openssl 1.0.1k .
+:  Example:
+* --cipher=DHE_DSS_WITH_RC4_128_SHA
+* --cipher=0x03000066
+* --cipher=66
+:  will be mapped to   DHE-DSS-RC4-SHA
-======--legacy=full======
+:  Note: if more than one cipher matches, just one will be selected.
+:
+:  Default is <code>ALL:NULL:eNULL:aNULL:LOW</code> as specified in Net::SSLinfo
-:Internal format: pretty print each label in its own line,  followed
+====== --socket-reuse======
-:by data prepended by tab character (useful for  ''+info''  only).
+: TCP socket will be reused for  next connection attempt  even if SSL
+: connection failed.
-======--legacy=quick======
+====== --no-socket-reuse======
+: Close TCP socket and then reopen for next connection attempt if SSL
+: connection failed.
-:Internal format: use tab as separator; ciphers are printed with bit
+: This is useful for some servers which may return an "TLS alert"  if
-:length (implies ''--tab'').
+: the connection fails and then fail again on the same socket.
-======--legacy=simple======
+====== --ignore-no-connect======
-:Internal default format.
+:  A simple check if the target can be connected  will be performed by
+:  default.  If this check fails, the target will be ignored, means no
+:  more reuqested checks will be done.  As this connection check some-
+:  times fails due to various reasons, the check can be disabled using
+:  this option.
-======--legacy=key======
+====== --no-md5-cipher======
+:Do not use *-MD5 ciphers for other protocols than SSLv2.
+:This option is only effective with  ''+cipher''  command.
-:Internal format: print name of key instead of text as label. Key is
+:The purpose is to avoid warnings from  IO::Socket::SSL(3pm)  like:
-:that of the internal data structure(s).  For ciphers and protocols,
+         Use of uninitialized value in subroutine entry at lib/IO/Socket/SSL.pm line 430.
-:the corresponding hex value is used as key.  Note that these values
+:which occours with some versions of  IO::Socket::SSL(3pm)  when a
-:are unique.
+:*-MD5  ciphers will be used with other protocols than SSLv2.
-====== --format=FORM======
+:Note that these ciphers will be checked for SSLv2 only.
-*  <code>raw</code>    Print raw data as passed from ''Net::SSLinfo'' .
+====== --SSL, -protocol SSL======
-:    Note:  all data will be printed as is,  without additional label
+====== --no-SSL======
-:    or formatting. It's recommended to use the option in conjunction
+* <code>SSL</code>       can be any of:
-:    with exactly one command.  Otherwise the user needs  to know how
+:ssl, ssl2, ssl3, sslv2, sslv3, tls1,
-:    to "read"  the printed data.
+:tls1, tls11, tls1.1, tls1-1, tlsv1, tlsv11, tlsv1.1, tlsv1-1
+:(and similar variants for tlsv1.2).
+:For example  ''--tls1''  ''--tlsv1''  ''--tlsv1_1''  are all the same.
+:  (''--SSL'' variants):    Test ciphers for this SSL/TLS version.
+:  (''--no-SSL'' variants): Don't test ciphers for this SSL/TLS version.
-*  <code>hex</code>    Convert some data to hex: 2 bytes separated by <code>:</code>.
+====== --no-tcp======
-*  <code>0x</code>     Convert some data with hex values:
+:Shortcut for:
-:                           2 bytes preceded by <code>0x</code> and separated by a space.
+:''--no-sslv2 --no-sslv3 --no-tlsv1 --no-tlsv11 --no-tlsv12 --no-tlsv13''
-*  <code>/x</code>     Same as  ''--format=\x''
-*  <code>\x</code>     Convert some data with hex values:
-:                           2 bytes preceded by <code>\x</code> and no separating char.
-====== --header======
+====== --tcp======
-:
-:  Print formatting header.  Default for  ''+check'', ''+info'', ''+quick''.
-:  and  ''+cipher''  only.
-:
-====== --no-header======
-:  Do not print formatting header.
-:  Usefull if raw output should be passed to other programs.
-:   Note: must be used on command line to inhibit all header lines.
+:Shortcut for:  ''--sslv2 --sslv3 --tlsv1 --tlsv11 --tlsv12 --tlsv13''
-======--ignore-cmd=CMD======
+====== --no-udp======
-======--ignore-output=CMD======
-======--no-cmd=CMD======
-======--no-output=CMD======
-:Do not print output (data or check result) for command <code>CMD</code>.
-:<code>CMD</code> is any valid command, see  [[#COMMANDS|COMMANDS]],  without leading <code>+</code>.
-:Option can be used multiple times.
-====== --score======
+:Shortcut for:
-:
+:''--no-dtlsv09 --no-dtlsv1 --no-dtlsv11 --no-dtlsv12 --no-dtlsv13''
-:  Print scoring results. Default for  ''+check''.
+====== --udp======
+:Shortcut for:  ''--dtlsv09 --dtlsv1 --dtlsv11 --dtlsv12 --dtlsv13''
+====== --nullsslv2======
+:  This option  forces  to assume that  SSLv2  is enabled  even if the
+:  target does not accept any ciphers.
+:  The target server may accept connections with  SSLv2  but not allow
+:  any cipher. Some checks verify if  SSLv2  is enabled at all,  which
+:  then would result in a failed test.
+:  The default behaviour is to assume that  SSLv2 is not enabled if no
+:  ciphers are accepted.
 :
-====== --no-score======
+====== --http======
+:  Make a HTTP request if cipher is supported.
+:  If used twice debugging will be enabled using  environment variable
+:  <code>HTTPS_DEBUG</code> .
+====== --no-http======
 :
-:  Do not print scoring results.
+:  Do not make HTTP request.
 :
-====== --separator=CHAR======
+====== --sni======
 :
-====== --sep=CHAR======
+:  Make SSL connection in SNI mode.
-:
-:  <code>CHAR</code>      will be used as separator between  label and value of the
-:      printed results. Default is  <code>:</code>
 :
+====== --no-sni======
-====== --tab======
+:  Do not make SSL connection in SNI mode (default: SNI mode).
-:  <code>TAB</code> character (0x09, \t)  will be used  as separator between  label
+====== --sni-toggle --toggle-sni ======
-:      and value of the printed results.
-:  As label and value are already separated by a  <code>TAB</code>  character, this
+: Test with and witout SNI mode (''+cipherall''  only).
-:  options is only useful in conjunction with the   ''--legacy=compact''
-:  option.
+====== --force-sni======
+:  Do not check if SNI seems to be supported by ''Net::SSLeay(3pm)''.
+:  Older versions of openssl and its libries do not support SNI or the
+:  SNI support is implemented buggy. By default it's checked if SNI is
+:  properly supported. With this option this check can be disabled.
+:  Be warned that this may result in improper results.
+====== --servername=NAME======
+====== --sni-name=NAME======
+: If in SNI mode is active, see  ''--sni''  above, <code>NAME</code> is used instead of
+: hostname for connections to the target. If SNI mode is not active,
+: see  ''--no-sni''  above, <code>NAME</code> is not used. The default is undefined,
+: which forces to use the given FQDN.
-====== --showhost======
+: This is useful, for example when an IP instead of a FQDN was given,
+: where a correct hostname (i.g. a FQDN) needs to be specified.
-:  Prefix each printed line with the given hostname (target).
+: Note: i.g. there is no need to use this option,  as a correct value
-:  The hostname will be followed by the separator character.
+: for the SNI name will be choosen automatically (except for IPs).
+: However, it is kind of fuzzing ...even setting to an  empty string
+: is possible.
+: Limitation: the same <code>NAME</code> is used for all targets, if more than
+: one  target was specified.
-====== --win-CR======
+====== --no-cert======
+:
+:  Do not get data from target's certificate, return empty string.
+:
+====== --no-cert --no-cert======
 :
-:  Print windows-Style with CR LF as end of line. Default is NL only.
+:  Do not get data from target's certificate, return default string
+:  of ''Net::SSLinfo'' (see  ''--no-cert-text TEXT''  option).
 :
-===== Options for compatibility with other programs=====
-:Please see other programs for detailed description (if not obvious:).
+====== --no-cert-text=TEXT======
-:Note that only the long form options are accepted  as most short form
+:
-:options are ambiguous.
+:  Set  <code>TEXT</code>  to be returned from  <code>Net::SSLinfo.pm</code> if no certificate
-: Following list contains only those options not shown with:
+:  data is collected due to use of  ''--no-cert''.
-  o-saft.pl --help=alias
+:
- Tool's Option        (Tool)          o-saft.pl Option
+====== --ca-depth=INT======
- --------------------+---------------+---------------------------
+:
-  --checks CMD        (TLS-Check.pl)  same as ''+CMD''
+:  Check certificate chain to depth  <code>INT</code> (like openssl's -verify).
-  -h, -h=HOST         (various tools) same as ''--host HOST''
+:
-  -p, -p=PORT         (various tools) same as ''--port PORT''
-  -t HOST             (ssldiagnos)    same as ''--host HOST''
-  --protocol SSL      (ssldiagnos)    same as ''--SSL''
-  --UDP               (ssldiagnos)    same as ''--udp''
-  --insecure          (cnark.pl)      ignored
-  --nopct --nocolor   (ssldiagnos)    ignored
-  --timeout, --grep   (ssltest.pl)    ignored
-  -r,  -s,  -t,  -x   (ssltest.pl)    ignored
-  -connect, -H, -u, -url, -U          ignored
-  -noSSL                              same as ''--no-SSL''
-  -no_SSL                             same as ''--no-SSL''
- --------------------+---------------+---------------------------
-:  For definition of  <code>SSL</code>  see  ''--SSL''  and  ''--no-SSL''  above.
+====== --ca-file=FILE======
+:
+:  Use  <code>FILE</code>  with bundle of CAs to verify target's certificate chain.
+:
-===== Options for customization=====
+====== --ca-path=DIR======
 :
-:  For general descriptions please see  [[#CUSTOMIZATION|CUSTOMIZATION]]  section below.
+:  Use  <code>DIR</code>  where to find CA certificates in PEM format.
 :
-====== --cfg_cmd=CMD=LIST======
-:  Redefine list of commands. Sets  %cfg{cmd-CMD}  to <code> LIST</code>.  Commands
+====== --no-nextprotoneg======
-:  can be written without the leading  <code>+</code>.
+:  Do not use  <code>-nextprotoneg</code>  option for openssl.
-:  If  <code>CMD</code>  is any of the known internal commands, it will be redifned.
-:  If  <code>CMD</code>  is a unknown command, it will be created.
+====== --proto-alpn=NAME======
+:    Name of protocol to be added to list of  applcation layer protocols
+:    (ALPN), which is used for any connection to the targets.
+:    See  ''--cipher-alpn=NAME''  also.
-:  Example:   ''--cfg_cmd=sni=sni hostname''
+====== --proto-npn=NAME======
+:    Name of protocol to be added to list of  next protocol negotiations
+:    (NPN), which is used for any connection to the targets.
+:    See  ''--cipher-npn=NAME''  also.
-:  To get a list of commands and their settings, use:
+====== --ssl-compression --compression======
+:  Use SSL option "compression" for connection.
-    o-saft.pl --help=intern
+====== --no-ssl-compression --no-compression======
+:  Use SSL option "no compression" for connection (default: don't use)
-:  Main purpose is to reduce list of commands or to print them sorted.
+====== --no-reconnect======
-:  An example  ''+preload''  can be found in  <code>.o-saft.pl</code> .
+:  Do not use  <code>-reconnect</code>  option for openssl.
-====== --cfg_score=KEY=SCORE======
+====== --no-tlsextdebug======
+:
+:  Do not use  <code>-tlsextdebug</code>  option for openssl.
+:
+====== --sclient-opt=VALUE======
+:
+:  Argument or option passed to openssl s_client command.
+:
+===== Options for ''+cipher''  command =====
-:  Redefine value for scoring. Sets  %checks{KEY}{score}  to  SCORE.
+====== --cipher-alpn=NAME======
-:  Most score values are set to 10 by default. Values <code>0</code> .. <code>100</code> are
-:  allowed.
-:  To get a list of current score settings, use:
+:    Name of protocol to be added to list of  applcation layer protocols
+:    (ALPN), which is used for cipher checks.
-    o-saft.pl --help=score
+:*    ''--cipher-alpn=,''   sets empty list.
+:*    ''--cipher-alpn=,,''  sets list to empty element "".
-:  For deatils how scoring works, please see  [[#SCORING| SCORING]]  section.
+====== --cipher-npn=NAME======
-:  Use the  ''--trace-key''  option for the  ''+info''  and/or  ''+check''
+:    Name of protocol to be added to list of  next protocol negotiations
-:  command to get the values for  KEY.
+:    (NPN), which is used for cipher checks.
-====== --cfg_checks=KEY=TEXT --cfg_data=KEY=TEXT======
+:*    ''--cipher-lpn=,''   sets empty list.
+:*    ''--cipher-lpn=,,''  sets list to empty element "".
-:  Redefine texts used for labels in output. Sets  %data{KEY}{txt}  or
+:    Note:  setting empty list or element most likely does not work with
-:  %checks{KEY}{txt}  to  TEXT.
+:    openssl executable (i.e.  --force-openssl).
-:  To get a list of preconfigured labels, use:
+====== --cipher-curve=NAME======
-    o-saft.pl --help=cfg_checks
+:    Name of ecliptic curve to be added to list of ecliptic curves (EC),
-    o-saft.pl --help=cfg_data
+:    which is used for cipher checks.
-:
-====== --cfg_text=KEY=TEXT======
+:*    ''--cipher-curve=,''   sets empty list.
+:*    ''--cipher-curve=,,''  sets list to empty element "".
-:  Redefine general texts used in output. Sets  %text{KEY}  to  <code>TEXT</code>.
+:    Note:  setting empty list or element most likely does not work with
+:    openssl executable (i.e.  ''--force-openssl'').
-:  To get a list of preconfigured texts, use:
+===== Options for cipherall  and cipherraw  command =====
-    o-saft.pl --help=cfg_text
+====== --range=RANGE ======
+====== --cipherrange=RANGE======
-:  Note that \n, \r and \t are replaced by the corresponding character
+:  Specify range of cipher constants to be tested by  ''+cipherall'' .
-:  when read from [[#RC-FILE| RC-FILE]].
+:  Following <code>RANGE</code>s are supported (see also [[#--cipherrange=RANGE|--cipherrange=RANGE]]):
+*  <code>rfc</code>             all ciphers defined in various RFCs
+*  <code>shifted</code>         <code>rfc</code>, shifted by 64 bytes to the right
+*  <code>long</code>            like <code>rfc</code> but more lazy list of
+*  <code>huge</code>            all constants  0x03000000 .. 0x0300FFFF
+*  <code>safe</code>            all constants  0x03000000 .. 0x032FFFFF
+*  <code>full</code>            all constants  0x03000000 .. 0x0300FFFF
+*  <code>SSLv2</code>           all ciphers according RFC for SSLv2
-====== --cfg_hint=KEY=TEXT======
+:Note: <code>SSLv2</code> is the internal list used for testing SSLv2 ciphers.
+:It does not make sense to use it for other protocols; however ...
-:Redefine texts used for hints. Sets  %cfg{hints}{KEY}  to  TEXT.
+====== --slow-server-delay=SEC======
-:To get a list of preconfigured texts, use:
+:  Additional delay in seconds  after the server is connected  using a
+:  proxy or before starting STARTTLS.
+:  This is useful when connecting via  slow proxy chains or connecting
+:  to slow servers before sending the STARTTLS sequence.
-    o-sat.pl --help=cfg-hint
+====== --ssl-maxciphers=CNT ======
-====== --call=METHOD======
+:  Maximal number of ciphers sent in a sslhello (default: 32).
-:
-:  See  [[#Options for SSL tool|Options for SSL tool]]
-:
-====== --usr======
+====== --ssl-double-reneg======
-:
-: Execute functions defined in  o-saft-usr.pm.
-====== --usr-*======
+:  Send SSL extension  "reneg_info"  even if list of ciphers includes
-====== --user-*======
+:  TLS_EMPTY_RENEGOTIATION_INFO_SCSV (default: do not include)
-: Options ignored, but stored as is internal in  $cfg{usr-args} .
+====== --ssl-nodata-nocipher======
-: These options can be used in  o-saft-usr.pm  or  o-saft-dbx.pm.
-====== --experimental======
+:  Do not abort testing for next cipher when the target  responds with
-:
+:  "NoData" times out. Useful for TLS intolerant servers.
-:  Use experimental functionality.
+:  By default testing for ciphers is aborted  when the target responds
-:  Some functionality of this tool is  under development and only used
+:  with "noData message.
-:  when this option is given.
-===== Options for tracing and debugging=====
+====== --ssl-use-ecc======
-:
-====== --n======
-:  Do not execute, just show commands (only useful in conjunction with
+:  Use supported elliptic curves.  Default on.
-:  using openssl).
-===== Difference --trace vs. --v=====
+====== --ssl-use-ec-point======
-:While  ''--v''  is used to print more data, ''--trace'' is used to print
+:  Use TLS "ec_point_formats" extension.  Default on.
-:more information about internal data such as  procedure names and/or
-:variable names and program flow.
-====== --v======
+====== --ssl-use-reneg======
-====== --verbose======
-:  Print more information about checks.
+:  Test for ciphers with "secure renegotiation" flag set.
-:
+:  Default: don't set "secure renegotiation" flag.
-:  Note that this option should be first otherwise some debug messages
-:  are missing.
-:
-:  Note that  ''--v''  is different from  ''-v''  (see above).
-====== --v --v======
+====== --ssl-retry=CNT======
-:  Print remotely checked ciphers.
+:  Number of retries when connection timed-out (default: 2).
-====== --v --v --v======
+====== --ssl-timeout=SEC======
-:  Print remotely checked ciphers one per line.
+:  Number of seconds to wait until connection is qualified as timeout.
-====== --v --v --v --v======
+====== --dns-mx, --mx======
-:  Print processed ciphers (check, skip, etc.).
+:  Get DNS MX records for given target and check the returned targets.
+:  (only useful with  ''--starttls=SMTP'')
-====== --trace======
+===== Options for checks and results=====
+:
+:Options used for  ''+check''  command:
+:
+====== --enabled======
+:
+:  Only print result for ciphers accepted by target.
+:
+====== --disabled======
+:
+:  Only print result for ciphers not accepted by target.
+:
+====== --ignorecase======
+:
+:  Checks are done case insensitive.
+:
+====== --no-ignorecase======
-:  Print debugging messages.
+:  Checks are done case sensitive. Default: case insensitive.
+:  Currently only checks according CN, alternate names in the target's
+:  certificate compared to the given hostname are effected.
-====== --trace --trace======
+====== --ignore-no-reply======
-:  Print more debugging messages and pass <code>trace=2</code> to Net::SSLeay and
+:When checking for the TLS "heartbeat" extension,  the server may not
-:  Net::SSLinfo.
+:respond at all, which would result in a  "no reply"  message.  This
+:marks the check for  ''+heartbleed''  as <code>no</code>.
+:I.g.  a server is  not vulnerable to the  heartbleed attack  if the
+:TLS "heartbeat" extension is disabled. Hence the check result  <code>no</code>
+:may be mis-leading.  This option  treats the  "no reply"  result as
+:"not vulnerable" and returns  <code>yes</code>  then.
-====== --trace --trace --trace======
+:Note: if the server does not respond for this check,  does not mean
+:that the "heartbeat" extension is switched off.  If unsure, disable
+:this lazy check with  ''--no-ignore-no-reply'' .
-:  Print more debugging messages and pass <code>trace=3</code> to Net::SSLeay and
+===== Options for output format=====
-:  Net::SSLinfo.
+:
+====== --label=TYPE======
-====== --trace --trace --trace --trace======
+:  Defines the format of the descriptive text(label) for  ''+check''   and
+:  ''+info'' command.
-:  Print processing of all command line arguments.
+:  Following <code>TYPE</code>s are supported:
-====== --trace--======
+====== --label=long======
-:
+:Prints full text for labels:
-====== --trace-arg======
+  Certificate Common Name:  some.tld
-:  Print command line argument processing.
+====== --label=short======
+:Prints short less descriptive text for labels:
+  Common Name:              some.tld
-====== --trace-cmd======
+====== --label=key======
+:Internal format: print name of key instead of text as label. Key is
+:Prints name of key instead of text as label. The key is that of the
+:internal data structure(s).
-:  Trace execution of command processing (those given as  ''+*'').
+  [cn]                      some.tld
-====== --trace@======
+====== --legacy=TOOL======
-:
-====== --trace-key======
-:  Print some internal variable names in output texts (labels).
+:  For compatibility with other tools,  the output format used for the
-:  Variable names are prefixed to printed line and enclosed in  <code>#</code> .
+:  result of the ''+cipher'' command can be adjusted to mimic the format
-:  Example without --trace-key :
+:  of other SSL testing tools.
-       Certificate Serial Number:          deadbeef
-:  Example with    --trace-key :
+:  The argument to the ''--legacy=TOOL''  option is the name of the tool
-       #serial#          Certificate Serial Number:          deadbeef
+:  to be simulated.
-:
-====== --trace=VALUE======
+:  Following <code>TOOL</code>s are supported:
-:Trace Option        Alias Option
+*  <code>sslaudit</code>        format of output similar to  sslaudit
-*  --trace=1                          same as --trace
+*  <code>sslcipher</code>       format of output similar to  ssl-cipher-check
-*  --trace=2                          same as --trace --trace
+*  <code>ssldiagnos</code>      format of output similar to  ssldiagnos
-*  --trace=arg                        same as --trace-arg
+*  <code>sslscan</code>         format of output similar to  sslscan
-*  --trace=cmd                        same as --trace-cmd
+*  <code>ssltest</code>         format of output similar to  ssltest
-*  --trace=key                        same as --trace-key
+*  <code>ssltestg</code>        format of output similar to  ssltest -g
+*  <code>ssltest-g</code>       format of output similar to  ssltest -g
+*  <code>sslyze</code>          format of output similar to  sslyze
+*  <code>ssl-cipher-check</code>      same as sslcipher
+*  <code>ssl-cert-check</code>  format of output similar to  ssl-cert-check
+*  <code>testsslserver</code>   format of output similar to  TestSSLServer.jar
+* <code> thcsslcHeck</code>     format of output similar to  THCSSLCheck
-====== --trace-time======
+:  Note that these legacy formats only apply to  output of the checked
-:
+:  ciphers. Other texts like headers and footers are adapted slightly.
-:  Prints timestamp in trace output (implies ''--trace-cmd'').
-====== --trace=FILE======
+:  Please do not expect identical output as the <code>TOOL</code>  when using these
+:  options, it's a best guess and should be parsable in a very similar
+:  way.
-:  Use <code>FILE</code> instead of the default rc-file (.o-saft.pl, see [[#RC-FILE|RC-FILE]]).
+======--legacy=TYPE======
+======--legacy=compact======
-====== --trace-me======
+:Internal format: mainly avoid tabs and spaces format is as follows:
+ Some Label:<-- anything right of colon is data
-:Print debugging messages for <code>o-saft.pl</code> only, but not any modules.
+======--legacy=full======
-====== --trace-not-me======
+:Internal format: pretty print each label in its own line,  followed
+:by data prepended by tab character (useful for  ''+info''  only).
-:Print debugging messages for modules only, but not <code>o-saft.pl</code> istself.
+====== --legacy=owasp======
-====== --trace-sub +traceSUB======
+:Results for cipher checks use rating from OWASP Cipher Cheat Sheet.
-:  Print formatted list of internal functions with their description.
+======--legacy=quick======
-:  Not to be intended in conjunction with any target check.
-====== --hint======
+:Internal format: use tab as separator; ciphers are printed with bit
-:  Print hint messages (!!Hint:).
+:length (implies ''--tab'').
-====== --no-hint======
+======--legacy=simple======
-:  Do not print hint messages (!!Hint:).
-====== --warning======
+:Internal default format.
-:  Print warning messages (**WARNING:).
-====== --no-warning======
+====== --format=FORM======
-:  Do not print warning messages (**WARNING:).
+:This option is used to specify the format of the result lines. This
+:covers the value of the result line only.
-====== --exit=KEY======
+*  <code>raw</code>    Print raw data as passed from ''Net::SSLinfo'' .
-:For debugging only: terminate <code>o-saft.pl</code> at specified <code>KEY</code>.
+:    Note:  all data will be printed as is,  without additional label
-:For <code>KEY</code> please see:  <code>grep exit= o-saft.pl</code>
+:    or formatting. It's recommended to use the option in conjunction
+:    with exactly one command.  Otherwise the user needs  to know how
+:    to "read"  the printed data.
-===== Options vs. Commands=====
+*  <code>hex</code>    Convert some data to hex: 2 bytes separated by <code>:</code>.
+*  <code>0x</code>     Convert some data with hex values:
+:                           2 bytes preceded by <code>0x</code> and separated by a space.
+*  <code>/x</code>     Same as  ''--format=\x''
+*  <code>\x</code>     Convert some data with hex values:
+:                           2 bytes preceded by <code>\x</code> and no separating char.
-:For compatibility with other programs and lazy users, some arguments
+====== --header======
-:looking like options are silently taken as commands. This means that
+:
-:''--THIS''  becomes  ''+THIS''  then. These options are:
+:  Print formatting header.  Default for  ''+check'', ''+info'', ''+quick''.
+:  and  ''+cipher''  only.
+:
+====== --no-header======
+:  Do not print formatting header.
+:  Useful if raw output should be passed to other programs.
-:*  ''--help''
+:   Note: must be used on command line to inhibit all header lines.
-:*  ''--abbr''
-:*  ''--todo''
-:*  ''--chain''
-:*  ''--default''
-:*  ''--fingerprint''
-:*  ''--list''
-:*  ''--version''
-:Take care that this behaviour may be removed in future versions as it
+======--ignore-cmd=CMD======
-:conflicts with those options and commands which actually exist, like:
+======--ignore-output=CMD======
+======--no-cmd=CMD======
+======--no-output=CMD======
+:Do not print output (data or check result) for command <code>CMD</code>.
+:<code>CMD</code> is any valid command, see  [[#COMMANDS|COMMANDS]],  without leading <code>+</code>.
+:Option can be used multiple times.
-:*  ''--sni''  vs.  ''+sni''
+====== --score======
+:
+:  Print scoring results. Default for  ''+check''.
+:
+====== --no-score======
+:
+:  Do not print scoring results.
+:
+====== --separator=CHAR======
+:
+====== --sep=CHAR======
+:
+:  <code>CHAR</code>      will be used as separator between  label and value of the
+:      printed results. Default is  <code>:</code>
+:
-==== LAZY SYNOPSIS====
+====== --tab======
-===== Commands=====
+:  <code>TAB</code> character (0x09, \t)  will be used  as separator between  label
+:      and value of the printed results.
+:  As label and value are already separated by a  <code>TAB</code>  character, this
+:  options is only useful in conjunction with the   ''--legacy=compact''
+:  option.
-:Following strings are treated as a command instead of target names:
+====== --showhost======
-:*  ciphers
+:  Prefix each printed line with the given hostname (target).
-:*  s_client
+:  The hostname will be followed by the separator character.
-:*  version
-:A warning will be printed.
+======--std-format=utf8======
+======--std-format=crlf======
-===== Options=====
+======--std-format=raw======
+======--std-format=unix======
+======--std-format=CHARSET======
+:This option is used to specify the general output format for STDOUT
+:and STDERR. All results are written to STDOUT,  errors and warnings
+:may also be written to STDERR .  The default is <code>:unix:utf8</code>, which
+:is the perlish definition used internally.
+:Following values are supported:
+:* <code>raw</code>
+:* <code>unix</code>      Print raw data, binary in bytes without conversion.
+:Note:  binary here just means characters (as all output is text).
+:* <code>utf8</code>      Convert all characters to UTF-8.
+:* <code>crlf</code>      Use CR LF as end of line.
+:* <code>CHARSET</code>   <code>CHARSET</code> can be any of the local installed character
+:sets, like UTF-8, UTF-16LE, CP1252, iso-8859-7, etc..
+:This conversion may print its own warnings.
+:The option can be used multiple times with different values.
+:To reset the  default behaviour, either  <code>raw</code>  or  <code>unix</code>  must be
+:used. Obviously, they must be used first. All other values are used
+:additionally.
+:Note:  <code>utf8</code> just defines the format of the characters, it does no
+:further checks on the converted characters. In contrast, <code>UTF-8</code> is
+:used as real encoding and does some checks.
-:We support following options, which are all identical, for lazy users
+:For more details, please see  "perldoc -f binmode" .
-:and for compatibility with other programs.
+:Currently (Jan. 2018), these options must be used before any ''--help''
+:option.
-====== Option Variants======
+====== --win-CR======
-:    ''--port PORT''
+:Obsolete, please use  ''--std-format=crlf'' .
-:    ''--port=PORT''
-:This applies to most such options,  ''--port''  is just an example.
+===== Options for compatibility with other programs=====
-:When used in the [[#RC-FILE|RC-FILE]], the ''--OPTION=VALUE'' variant must be used.
-====== Option Names======
+:Please see other programs for detailed description (if not obvious:).
-:
+:Note that often only the long form options are accepted  as most short
-:Dash  <code>-</code>, dot <code>.</code>  and/or  underscore  <code>_</code>  in option names are optional,
+:form options are ambiguous.
-:all following are the same:
+:If other programs use the same option,but with a different behaviour,
-:    ''--no.dns''
+:then thes other options are not supported.
-:    ''--no-dns''
+:For a list of supported options, please see:
-:    ''--no_dns''
+  o-saft.pl --help=alias
-:    ''--nodns''
-:
-:This applies to all such options, ''--no-dns'' is just an example.
-:
-===== Targets=====
+: Following list contains only those options not shown with:
-:
+  o-saft.pl --help=alias
-:Following syntax is supported also:
-:
-    o-saft.pl <nowiki>http://some.tld</nowiki> other.tld:3889/some/path?a=b
-:
-:Note that only the hostname and the port are used from an URL.
-:
-===== Options vs. Commands=====
+ Tool's Option        (Tool)          o-saft.pl Option
-:
+ --------------------+---------------+---------------------------
-:See  [[#Options vs. Commands|Options vs. Commands]]  in  [[#OPTIONS|OPTIONS]]  section above
+  --checks CMD        (TLS-Check.pl)  same as ''+CMD''
-:
+  -h, -h=HOST         (various tools) same as ''--host HOST''
+  -p, -p=PORT         (various tools) same as ''--port PORT''
+  -t HOST             (ssldiagnos)    same as ''--host HOST''
+  --protocol SSL      (ssldiagnos)    same as ''--SSL''
+  --UDP               (ssldiagnos)    same as ''--udp''
+  --insecure          (cnark.pl)      ignored
+  --nopct --nocolor   (ssldiagnos)    ignored
+  --timeout, --grep   (ssltest.pl)    ignored
+  -r,  -s,  -t,  -x   (ssltest.pl)    ignored
+  -connect, -H, -u, -url, -U          ignored
+  -noSSL                              same as ''--no-SSL''
+  -no_SSL                             same as ''--no-SSL''
+ --------------------+---------------+---------------------------
-==== CHECKS====
+:  For definition of  <code>SSL</code>  see  ''--SSL''  and  ''--no-SSL''  above.
-:All SSL related check performed by the tool will be described here.
+===== Options for customization=====
+:
+:  For general descriptions please see  [[#CUSTOMIZATION|CUSTOMIZATION]]  section below.
+:
+====== --cfg_cmd=CMD=LIST======
-===== General Checks=====
+:  Redefine list of commands. Sets  %cfg{cmd-CMD}  to <code> LIST</code>.  Commands
+:  can be written without the leading  <code>+</code>.
+:  If  <code>CMD</code>  is any of the known internal commands, it will be redifned.
+:  If  <code>CMD</code>  is a unknown command, it will be created.
-:Lookup the IP of the given hostname (FQDN), and then tries to reverse
+:  Example:
-:resolve the FQDN again.
+    ''--cfg_cmd=sni=sni hostname''
-===== SSL Ciphers=====
+:  To get a list of commands and their settings, use:
-:Check which ciphers are supported by target. Please see [[#RESULTS|RESULTS]] for
+    o-saft.pl --help=intern
-:details of this check.
-===== SSL Connection=====
+:  Main purpose is to reduce list of commands or to print them sorted.
+:  An example  ''+preload''  can be found in  <code>.o-saft.pl</code> .
-====== heartbeat======
+====== --cfg_score=KEY=SCORE======
-:Check if heartbead extension is supported by target.
+:  Redefine value for scoring. Sets  %checks{KEY}{score}  to  SCORE.
+:  Most score values are set to 10 by default. Values <code>0</code> .. <code>100</code> are
+:  allowed.
-====== poodle======
+:  To get a list of current score settings, use:
-:Check if target is vulnerable to POODLE attack (SSLv3 enabled).
+    o-saft.pl --help=score
-====== sloth======
+:  For deatils how scoring works, please see  [[#SCORING| SCORING]]  section.
-:Check if target is vulnerable to SLOTH attack (server offeres RSA-MD5
+:  Use the  ''--trace-key''  option for the  ''+info''  and/or  ''+check''
-:or ECDSA-MD5 ciphers).
+:  command to get the values for  KEY.
-====== sweet32======
+====== --cfg_checks=KEY=TEXT --cfg_data=KEY=TEXT======
-:Check if target is vulnerable to Sweet32 attack  (server offers 3DES
+:  Redefine texts used for labels in output. Sets  %data{KEY}{txt}  or
-:ciphers).
+:  %checks{KEY}{txt}  to  <code>TEXT</code>.
-====== ALPN======
+:  To get a list of preconfigured labels, use:
-:Check if target supports ALPN. Following messages are evaluated:
+    o-saft.pl --help=cfg_checks
+    o-saft.pl --help=cfg_data
 :
-    ALPN protocol: h2-14
-    No ALPN negotiated
-===== SSL Vulnerabilities=====
+====== --cfg_text=CIPHER=value======
-====== ADH======
+:  Redefine the security value (i.e. HIGH) in the cipher description.
+:  Example:
+    o-saft.pl --cfg-cipher=NULL-MD5=no-security-at-all ...
-:Check if ciphers for anonymous key exchange are supported: ADH|DHA .
+====== --cfg_text=KEY=TEXT======
-:Such key exchanges can be sniffed.
-====== EDH======
+:  Redefine general texts used in output. Sets  %text{KEY}  to  <code>TEXT</code>.
-:Check if ephemeral ciphers are supported: DHE|EDH .
+:  To get a list of preconfigured texts, use:
-:They are necessary to support Perfect Forward Secrecy (PFS).
-====== BEAST======
+    o-saft.pl --help=cfg_text
-:Currently (2015) only a simple check is used: RC4 or CBC ciphers used.
+:  Note that \n, \r and \t are replaced by the corresponding character
-:Which is any cipher with RC4, ARC4 or ARCFOUR or with CBC.
+:  when read from [[#RC-FILE| RC-FILE]].
-:TLSv1.2 checks are not yet implemented.
-====== CRIME======
+====== --cfg_text=FILE======
+:Read definitions for  %text{KEY}="my text" from file  <code>FILE</code>.
-:Connection is vulnerable if target supports SSL-level compression.
+====== --cfg_hint=KEY=TEXT======
-====== DROWN======
+:Redefine texts used for hints. Sets  %cfg{hints}{KEY}  to <code>TEXT</code>.
-:Connection is vulnerable if target supports SSLv2 (with at least one cipher).
+:To get a list of preconfigured texts, use:
-======FREAK======
+    o-sat.pl --help=cfg-hint
-:Attack Against SSL/TLS to downgrade to EXPORT ciphers.
+====== --call=METHOD======
-:Currently (2015) a simple check is used:   SSLv3 enabled and EXPORT
+:
-:ciphers supported by server.
+:  See  [[#Options for SSL tool|Options for SSL tool]]
-:	See CVE-2015-0204 and https://freakattack.com/ .
+:
-====== HEARTBLEED======
+====== --usr======
+:
+: Execute functions defined in  o-saft-usr.pm.
-:Check if target is vulnerable to heartbleed attack, see CVE-2014-0160
+====== --usr-*======
-:and http://heartbleed.com/ .
+====== --user-*======
-====== Logjam======
+: Options ignored, but stored as is internal in  $cfg{usr-args} .
+: These options can be used in  o-saft-usr.pm  or  o-saft-dbx.pm.
-:Check if target is vulenerable to Logjam attack.
+====== --experimental======
-:Check if target suports  EXPORT ciphers  and/or  DH Parameter is less
+:
-:than 2048 bits.
+:  Use experimental functionality.
+:  Some functionality of this tool is  under development and only used
+:  when this option is given.
-====== Lucky 13======
+===== Options for tracing and debugging=====
+:
+====== --n  --dry-run======
-:Check if CBC ciphers are offered.
+:  Do not execute, just show commands (only useful in conjunction with
-:NOTE the recommendation to be safe againts  Lucky 13  was to use RC4
+:  using openssl).
-:ciphers. But they are also subjetc to attacks (see below). Hence the
-:check is only for CBC ciphers.
-====== RC4======
+===== Difference --trace vs. --v=====
-:Check if RC4 ciphers are supported.
+:While  ''--v''  is used to print more data, ''--trace'' is used to print
-:They are assumed to be broken.
+:more information about internal data such as  procedure names and/or
-:Note that  ''+rc4''  reports the vulnerabilitiy to the RC4 Attack, while
+:variable names and program flow.
-:''+rc4_cipher''  simply reports if RC4 ciphers are offered.  However the
-:the check, and hence the result, is the same.
-====== PFS======
+====== --v======
+====== --verbose======
-:Check if DHE ciphers are used. Also check if the  TLS session ticket
+:  Print more information about checks.
-:is random or not used at all.
+:
-:Currently (2015) only a simple check is used: only DHE ciphers used.
+:  Note that this option should be first otherwise some debug messages
-:Which is any cipher with DHE or ECDHE. SSLv2 does not support PFS.
+:  are missing.
-:TLSv1.2 checks are not yet implemented.
+:
+:  Note that  ''--v''  is different from  ''-v''  (see above).
-====== POODLE======
+====== --v --v======
-:Check if target is vulnerable to POODLE attack (just check if  SSLv3
+:  Print remotely checked ciphers.
-:is enabled).
-====== Practical Invalid Curve Attack======
+====== --v-cipher --cipher-v======
+:Print remotely checked ciphers.
+:In contrast to  ''--v --v''  above,  this just prints the ciphers while
+:being checked, but no other verbose messages.
+<!-- no longer implemented (8/2015)
+====== --v --v --v======
-:This attack allows an attacker to read the servers private key if the
+:  Print remotely checked ciphers one per line.
-:server does not check properly the passed points for a ecliptic curve
-:when EDH ciphers are used.
-:This check will not send multiple invalid points,  but only checks if
+====== --v --v --v --v======
-:the server closes the connection or responds with no matching cipher.
-====== SLOTH======
+:  Print processed ciphers (check, skip, etc.).
+-->
-:Currently (2016) we check for ciphers with  ECDSA, RSA-MD5.
+====== --trace======
-:Checking the TLS extension 'tls-unique' is not yet implemented.
-===== Target (server) Configuration and Support=====
+:  Print debugging messages.
-====== BEAST, BREACH, CRIME, DROWN, FREAK, Logjam, Lucky 13, POODLE, RC4, SLOTH======
+====== --trace --trace======
-:See above.
+:  Print more debugging messages and pass <code>trace=2</code> to Net::SSLeay and
+:  Net::SSLinfo.
-====== Renegotiation======
+====== --trace --trace --trace======
-:Check if the server allows client-side initiated renegotiation.
+:  Print more debugging messages and pass <code>trace=3</code> to Net::SSLeay and
+:  Net::SSLinfo.
-====== Version rollback attacks======
+====== --trace --trace --trace --trace======
-:NOT YET IMPLEMENTED
+:  Print processing of all command line arguments.
-:Check if the server allows changing the protocol.
-====== DH Parameter======
+====== --trace-cli======
+:Print complete command line first. Used for internal testing.
-:Check if target's DH Parameter is less 512  or  2048 bits.
+====== --trace--======
+:
-===== Target (server) Certificate=====
+====== --trace-arg======
-====== Certificate Hashes======
+:  Print command line argument processing.
-:Check that fingerprint is not MD5.
+====== --trace-cmd======
-:Check that certificate private key signature is SHA2 or better.
-====== Root CA======
+:  Trace execution of command processing (those given as  ''+*'').
-:Provided certificate by target should not be a Root CA.
+====== --trace@======
+:
+====== --trace-key======
-====== Self-signed Certificate======
+:  Print some internal variable names in output texts (labels).
+:  Variable names are prefixed to printed line and enclosed in  <code>#</code> .
+:  Example without --trace-key :
+       Certificate Serial Number:          deadbeef
-:Certificate should not be self-signed.
+:  Example with    --trace-key :
+       #serial#          Certificate Serial Number:          deadbeef
+:
-====== IP in CommonName or subjectAltname (RFC6125)======
+====== --trace=VALUE======
+:Alias for  [[#--trace=VALUE|--trace-VALUE]]  options (see above).
-:NOT YET IMPLEMENTED
+:Trace Option        Alias Option
+*  --trace=1                          same as --trace
+*  --trace=2                          same as --trace --trace
+*  --trace=arg                        same as --trace-arg
+*  --trace=cmd                        same as --trace-cmd
+*  --trace=key                        same as --trace-key
-====== Basic Constraints======
+====== --trace-time======
+:
+:  Prints timestamp in trace output. More timestamps are printed if
+:  used together with  ''--trace-cmd''.
-:Certificate extension Basic Constraints should be <code>CA:FALSE</code>.
+====== --trace=FILE======
-====== OCSP, CRL, CPS======
+:  Use <code>FILE</code> instead of the default [[#RC-FILE|RC-FILE]], i.e. <code>.o-saft.pl</code>.
-:Certificate should contain URL for OCSP and CRL.
+====== --trace-me======
-====== Private Key encyption======
+:Print debugging messages for <code>o-saft.pl</code> only, but not any modules.
-:Certificates signature key supports encryption.
+====== --trace-not-me======
-====== Private Key encyption well known======
+:Print debugging messages for modules only, but not <code>o-saft.pl</code> istself.
-:Certificates signature key encryption algorithm is well known.
+====== --hint======
+:  Print hint messages (!!Hint:).
-====== Public Key encyption======
+====== --no-hint======
+:  Do not print hint messages (!!Hint:).
-:Certificates public key supports encryption.
+====== --warning======
+:  Print warning messages (**WARNING:).
-====== Public Key encyption well known======
+====== --no-warning======
+:  Do not print warning messages (**WARNING:).
-:Certificates public key encryption algorithm is well known.
+====== --exit=KEY======
+:Terminate <code>o-saft.pl</code> at specified <code>KEY</code>. Please see  [[#TESTING|TESTING]]  below.
-====== Public Key Modulus size======
+===== Options vs. Commands=====
-:Some (historic) SSL implementations are subject to buffer overflow if
+:For compatibility with other programs and lazy users, some arguments
-:the key exceeds 16384 or 32768 bits. The check is against 16384 bits.
+:looking like options are silently taken as commands. This means that
+:''--THIS''  becomes  ''+THIS''  then. These options are:
-====== Public Key Modulus Exponent size======
+:*  ''--help''
+:*  ''--abbr''
+:*  ''--todo''
+:*  ''--chain''
+:*  ''--default''
+:*  ''--fingerprint''
+:*  ''--list''
+:*  ''--version''
-:The modulus exponent should be <= 65536 as some (mainly historic) SSL
+:Take care that this behaviour may be removed in future versions as it
-:implementations may have problems to connect.
+:conflicts with those options and commands which actually exist, like:
-====== Sizes and Lengths of Certificate Settings======
+:*  ''--sni''  vs.  ''+sni''
-:  Serial Number <= 20 octets (RFC5280, 4.1.2.2.  Serial Number)
+==== LAZY SYNOPSIS====
-:...
+===== Commands=====
-====== DV-SSL - Domain Validation Certificate======
+:Following strings are treated as a command instead of target names:
-:The Certificate must provide:
+:*  ciphers
-* Common Name <code>/CN=</code> field
+:*  s_client
-* Common Name <code>/CN=</code> in <code>subject</code>  or <code>subjectAltname</code> field
+:*  version
-* Domain name in <code>commonName</code> or <code>altname</code> field
-====== EV-SSL - Extended Validation Certificate======
+:A warning will be printed.
-:This check is performed according the requirements defined by the CA/
+===== Options=====
-:Browser Forum  https://www.cabforum.org/contents.html .
-:The Certificate must provide:
-:*  DV - Domain Validation Certificate (see above)
-:*  Organization name <code>/O=</code> Cn ''subject'' field
-:*  Organization name must be less to 64 characters
-:*  Business Category <code>/businessCategory=</code> in <code>subject</code> field
-:*  Registration Number <code>/serialNumber=</code> in <code>subject</code> field
-:*  Address of Place of Business in <code>subject</code> field
-:Required are: <code>/C=</code>, <code>/ST=</code>, <code>/L=</code>
+:We support following options, which are all identical, for lazy users
+:and for compatibility with other programs.
-:Optional are: <code>/street=</code>, <code>/postalCode=</code>
+====== Option Variants======
-:*  Validation period does not exceed 27 month
-:See  [[#LIMITATIONS|LIMITATIONS]]  also.
+:    ''--port PORT''
+:    ''--port=PORT''
-===== Target (server) HTTP(S) Support=====
+:This applies to most such options,  ''--port''  is just an example.
-====== STS header (see RFC 6797)======
+:When used in the [[#RC-FILE|RC-FILE]], the ''--OPTION=VALUE'' variant must be used.
-:Using STS is no perfect security.  While the very first request using
+====== Option Names======
-:http: is always prone to a MiTM attack, MiTM is possible to following
+:
-:requests again, if STS is not well implemented on the server.
+:Dash  <code>-</code>, dot <code>.</code>  and/or  underscore  <code>_</code>  in option names are optional,
-:* Request with http: should be redirected to https:
+:all following are the same:
-:* Redirects should use status code 301 (even others will work)
+:    ''--no.dns''
-:* Redirect's Location header must contain schema https:
+:    ''--no-dns''
-:* Redirect's Location header must redirect to same FQDN
+:    ''--no_dns''
-:* Redirect may use Refresh instead of Location header (not RFC6797)
+:    ''--nodns''
-:* Redirects from HTTP must not contain STS header
+:
-:* Answer from redirected page (HTTPS) must contain STS header
+:This applies to all such options, ''--no-dns'' is just an example.
-:* Answer from redirected page for IP must not contain STS header
+:
-:* STS header must contain includeSubDirectoy directive
-:* STS header max-age should be less than 1 month
+===== Targets=====
-:* STS must not be set in http-equiv attribute of a meta TAG
+:
+:Following syntax is supported also:
+:
+    o-saft.pl <nowiki>http://some.tld</nowiki> other.tld:3889/some/path?a=b
+:
+:Note that only the hostname and the port are used from an URL.
+:
-====== STS header preload attribute (''+preload'')======
+===== Options vs. Commands=====
+:
-:To satisfy the requirements on  <code>https://hstspreload.appspot.com/</code>  the
+:See  [[#Options vs. Commands|Options vs. Commands]]  in  [[#OPTIONS|OPTIONS]]  section above
-:HSTS header must:
+:
-:* have the max-age with at least 18 weeks (10886400 seconds)
-:* have the includeSubDomains attribute
+==== CHECKS====
-:* have the preload attribute
-:* redirect to https first, then to sub-domains (if redirected)
-:* have an HSTS header in each redirect to https.
-:Additionally, the site must have:
-:* a valid certificate
-:* serve all subdomains over https.
-:Except the last requirement,  ''+preload''  will do the checks.
-:Note that  ''+preload''  is defined in  <code>.o-saft.pl</code>  only.
-====== Publix Key Pins header======
+:All SSL related check performed by the tool will be described here.
-:TBD - to be described ...
+===== General Checks=====
-===== Compliances=====
+:Lookup the IP of the given hostname (FQDN), and then tries to reverse
+:resolve the FQDN again.
-:Note that it is not possible to satisfy all following compliances. Best
+===== SSL Ciphers=====
-:match is: ''PSF'' and ''ISM'' and ''PCI'' and ''lazy BSI TR-02102-2''.
-:In general it is difficult to  satisfy all conditions of a compliances,
+:Check which ciphers are supported by target. Please see [[#RESULTS|RESULTS]] for
-:and it is also difficult to check all these conditions. That's why some
+:details of this check.
-:of the compliances checks are  not completely implemented,  for details
-:please see blow.
-:Note that output of results of some checks is disabled in the  [[#RC-FILE|RC-FILE]]
+===== SSL Connection=====
-:by default. A  "**Hint:"  message will be printed, if any of these checks
-:are used.
-:* FIPS-140
+====== heartbeat======
-:* ISM
-:* PCI
-:* BSI TR-02102
-:* BSI TR-03116-4
-:* RFC 6125
-:* RFC 6797
-:* RFC 7525
-======BSI TR-02102-2 (''+bsi-tr-02102+'' ''+bsi-tr-02102-'' ''+bsi'')======
+:Check if "heartbead" extension is supported by target.
-:Checks if connection and ciphers are compliant according TR-02102-2,
+====== poodle======
-:see https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen
-:/TechnischeRichtlinien/TR02102/BSI-TR-02102-2_pdf.pdf?__blob=publicationFile
-:(following headlines are taken from there)
+:Check if target is vulnerable to POODLE attack (SSLv3 enabled).
-:*  3.2.1 Empfohlene Cipher Suites
+====== robot======
-:*  3.2.2 Übergangsregelungen
+:Check if target is vulnerable to ROBOT attack (server offers ciphers
+:with RSA encryption).
-:    RC4 allowed temporary for TLS 1.0. Only if  TLS 1.1  and  TLS 1.2
+====== sloth======
-:    cannot be supported.
-:*  3.2.3 Mindestanforderungen für Interoperabilität
+:Check if target is vulnerable to SLOTH attack (server offeres RSA-MD5
+:or ECDSA-MD5 ciphers).
-:    Must at least support: ECDHE-ECDSA-* and ECDHE-RSA-*
+====== sweet32======
-:*  3.3 Session Renegotation
+:Check if target is vulnerable to Sweet32 attack  (server offers CBC or
+: CBC3 or DES or 3DES ciphers).
-:    Only server-side (secure) renegotiation allowed (see RFC5280).
+:Note that FIPS-140 compliance requires 3DES ciphers, hence compliant
+:systems are then vulnerable to Sweet32 attacks.
-:*  3.4 Zertifikate und Zertifikatsverifikation
+====== ALPN======
-:    Must have <code>CRLDistributionPoint</code> or <code>AuthorityInfoAccess</code>.
+:Check if target supports ALPN. Following messages are evaluated:
+:
+    ALPN protocol: h2-14
+    No ALPN negotiated
-:    MUST have <code>OCSP URL</code>.
+: Please see also  CHECKS [[#ALPN and NPN|ALPN and NPN]]  below.
-:    <code>PrivateKeyUsage</code> must not exceed three years for certificate and
+===== SSL Vulnerabilities=====
-:    must not exceed five years for CA certificates.
-:    <code>Subject</code>,  <code>CommonName</code>  and  <code>SubjectAltName</code>  must not contain
+====== ADH======
-:    a wildcard.
-:    Certificate itself must be valid according dates if validity.
+:Check if ciphers for anonymous key exchange are supported: ADH|DHA .
-:    Note that  the validity check relies on the years provided by the
+:Such key exchanges can be sniffed.
-:    certificate's  <code>before</code>  and  <code>after</code>  values only. For example a
-:    certificate valid  from Jan 2013 to Mar 2016  is considered valid
-:    even the validity is more than three years.
-:    All certificates in the chain must be valid.
+====== EDH======
-:    **NOT YET IMPLEMENTED**
-:    Above conditions are not required for lazy checks.
+:Check if ephemeral ciphers are supported: DHE|EDH .
+:They are necessary to support Perfect Forward Secrecy (PFS).
-:*  3.5 Domainparameter und Schlüssellängen
+====== BEAST======
-:    **NOT YET IMPLEMENTED**
+:Check if ciphers with CBC for protocol SSLv1, SSLv3 or TLSv1 are used.
+:TLSv1.2 checks are not yet implemented.
-:*  3.6 Schlüsselspeicherung
+====== CRIME======
-:    This requirement is not testable from remote.
+:Connection is vulnerable if target supports SSL-level compression.
-:*  3.7 Umgang mit Ephemeralschlüsseln
+====== DROWN======
-:    This requirement is not testable from remote.
+:Connection is vulnerable if target supports SSLv2 (with at least one cipher).
-:*  3.8 Zufallszahlen
+======FREAK======
-:    This requirement is not testable from remote.
+:Attack Against SSL/TLS to downgrade to EXPORT ciphers.
+:Currently (2018) a simple check is used:   SSLv3 enabled and EXPORT
+:ciphers supported by server.
+:	See CVE-2015-0204 and https://freakattack.com/ .
-======BSI TR-03116-4 (''+bsi-tr-03116+'' ''+bsi-tr-03116-'' ''+bsi'')======
+====== HEARTBLEED======
-:Checks if connection and ciphers are compliant according TR-03116-4,
-:see https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen
-:/TechnischeRichtlinien/TR03116/BSI-TR-03116-4.pdf?__blob=publicationFile
-:(following headlines are taken from there)
+:Check if target is vulnerable to heartbleed attack, see CVE-2014-0160
+:and http://heartbleed.com/ .
-:* 2.1.1 TLS-Versionen und Sessions
+====== HEIST======
-:Allows only TLS 1.2.
+:Not implemented.
-:* 2.1.2 Cipher Suites
+:There are no checks for the HEIST attack implemented, because this is
+:an attack on TCP/IP rather than SSL/TLS on top of TCP/IP.
-:Cipher suites must be ECDHE-ECDSA or -RSA with AES128 and SHA265.
+====== KCI======
-:For curiosity, stronger cipher suites with AES256 and/or SHA384 are
-:not not allowed. To follow this curiosity the ''+bsi-tr-03116-'' (lazy)
-:check allows the stronger cipher suites ;-)
-:* 2.1.1 TLS-Versionen und Sessions
+:Not implemented.
-:The TLS session lifetime must not exceed 2 days.
+:To perform a MiTM attack with Key Compromise Impersonation, the atta-
+:cker needs to engage the victim to install and use a client certificate.
+:This is considered a low risk and hence not tested here.
-:* 2.1.4.2 Encrypt-then-MAC-Extension
+====== Logjam======
-:* 2.1.4.3 OCSP-Stapling
+:Check if target is vulenerable to Logjam attack.
+:Check if target suports  EXPORT ciphers  and/or  DH Parameter is less
+:than 2048 bits.
-:MUST have <code>OCSP Stapling URL</code>.
+====== Lucky 13======
-:* 4.1.1 Zertifizierungsstellen/Vertrauensanker
+:Check if CBC ciphers are offered.
+:NOTE the recommendation to be safe againts  Lucky 13  was to use RC4
+:ciphers. But they are also subjetc to attacks (see below). Hence the
+:check is only for CBC ciphers.
-:Certificate must provide all root CAs. (NOT YET IMPLEMENTED).
+====== RC4======
-:Should use a small certificate trust chain.
+:Check if RC4 ciphers are supported.
+:They are assumed to be broken.
+:Note that  ''+rc4''  reports the vulnerabilitiy to the RC4 Attack, while
+:''+rc4_cipher''  simply reports if RC4 ciphers are offered.  However the
+:the check, and hence the result, is the same.
-:* 4.1.2 Zertifikate
+====== PFS======
-:Must have <code>CRLDistributionPoint</code> or <code>AuthorityInfoAccess</code>.
+:Check if DHE ciphers are used. Also check if the  TLS session ticket
+:is random or not used at all.
+:Currently (2018) only a simple check is used: only DHE ciphers used.
+:TLSv1.2 checks are not yet implemented.
+====== POODLE======
-:End-user certificate must not be valid longer than 3 years.
+:Check if target is vulnerable to POODLE attack (just check if  SSLv3
-:Root-CA certificate must not be valid longer than 5 years.
+:is enabled).
-:Certificate extension <code>pathLenConstraint</code> must exist, and should be
+====== Practical Invalid Curve Attack======
-:a small value ("small" is not defined).
-:All certificates must contain the extension <code>KeyUsage</code>.
+:This attack allows an attacker to read the servers private key if the
+:server does not check properly the passed points for a ecliptic curve
+:when EDH ciphers are used.
-:Wildcards for <code>CN</code> or <code>Subject</code> or <code>SubjectAltName</code> are not allowed
+:This check will not send multiple invalid points,  but only checks if
-:in any certificate.
+:the server closes the connection or responds with no matching cipher.
-:EV certificates are recommended (NOT YET checked properly).
+====== ROBOT======
+:Bleichebacher's Oracle attack against SSL/TLS ciphers.
-:* 4.1.3 Zertifikatsverifikation
+:Not implemented.
+: https://robotattack.org/
-:Must verify all certificates in the chain down to their root-CA.
+====== SLOTH======
-:(NOT YET IMPLEMENTED).
-:Certificate must be valid according issue and expire date.
+:Currently (2016) we check for ciphers with  ECDSA, RSA-MD5.
+:Checking the TLS extension 'tls-unique' is not yet implemented.
-:All Checks must be doen for all certificates in the chain.
+====== Sweet32======
+:Currently (2016) we check for ciphers with CBC or CBC3 or DES or 3DES.
-:* 4.1.4 Domainparameter und Schlüssellängen
+===== Target (server) Configuration and Support=====
-:This requirement is not testable from remote.
+====== BEAST, BREACH, CRIME, DROWN, FREAK, Logjam, Lucky 13, POODLE, RC4, ROBOT, SLOTH, Sweet32======
-:* 4 5.2 Zufallszahlen
+:See above.
-:This requirement is not testable from remote.
+====== Renegotiation======
-======RFC 6125 (''+rfc6125'')======
+:Check if the server allows client-side initiated renegotiation.
-:Checks values <code>CommonName</code>, <code>Subject</code> and <code>SubjectAltname</code>  of the
-:certificate for:
-:* must all be valid characters for DNS
-:* must not contain more than one wildcards
-:* must not contain invalid wildcards
-:* must not contain invalid IDN characters
-======RFC 6797 (''+rfc6797'')======
+====== Version rollback attacks======
-: Same as STS header  ''+hsts'' .
-======RFC 7525 (''+rfc7525'') ======
+:NOT YET IMPLEMENTED
-:Checks if connection and ciphers are compliant according RFC 7525.
+:Check if the server allows changing the protocol.
-:See http://tools.ietf.org/rfc/rfc7525.txt
-:(following headlines are taken from there)
-:* 3.1.1.  SSL/TLS Protocol Versions
+====== DH Parameter======
+:Check if target's DH Parameter is less 512  or  2048 bits.
-:SSLv2 and SSLv3 must not be supportetd.
+====== SSTP======
-:TLSv1 should only be supported if there is no TLSv1.1 or TLSv1.2.
+:Check if target supports SSTP by accepting method SSTP_DUPLEX_POST.
-:Either TLSv1.1 or TLSv1.2 must be supported, prefered is TLSv1.2.
-:* 3.1.2.  DTLS Protocol Versions
+:The check does not send other methods (like CONNECT) to verify if the
+:protocol is fully supported.
-:DTLSv1 and DTLSv1.1 must not be supported.
+:Supporting SSTP is considered insecure, because SSTP allows to tunnel
+:other, probably insecure, protocols.
-:* 3.1.3.  Fallback to Lower Versions
+===== Target (server) Certificate=====
-:(check implecitely done by 3.1.1, see above)
+====== Certificate Hashes======
-:* 3.2.  Strict TLS
+:Check that fingerprint is not MD5.
+:Check that certificate private key signature is SHA2 or better.
-:Check if server provides Strict Transport Security.
+====== Root CA======
-:(STARTTLS check NOT YET IMPLEMENTED).
-:* 3.3.  Compression
+:Provided certificate by target should not be a Root CA.
-:Compression on TLS must not be supported.
+====== Self-signed Certificate======
-:* 3.4.  TLS Session Resumption
+:Certificate should not be self-signed.
+====== FQDN is listed in subjectAltname (RFC2818) ======
-:Server must support resumtion and random session tickets.
+:The FQDN must be listed in the certificates subjectAltname.
-:(Randomnes of session tickets implemented YET experimental.)
+:The check command  ''+rfc_2818_names''  is based on the info command
+:''+verify_hostname'' . The check was added in 05/2017 because browsers
+:started to complain if the FQDN is not part of the subjectAltname.
-:Check if ticket is authenticated and encrypted NOT YET IMPLEMENTED.
+====== IP in CommonName or subjectAltname (RFC6125)======
-:* 3.5.  TLS Renegotiation
+:NOT YET IMPLEMENTED
-:Server must support renegotiation.
+====== Basic Constraints======
-:* 3.6.  Server Name Indication
+:Certificate extension Basic Constraints should be <code>CA:FALSE</code>.
-:(Check for SNI support implemented experimental.)
+====== OCSP, CRL, CPS======
-:* 4.  Recommendations: Cipher Suites
+:Certificate should contain URL for OCSP and CRL.
-:* 4.1.  General Guidelines
+====== Private Key encyption======
-:* 4.2.  Recommended Cipher Suites
-:Check for recommended ciphers.
+:Certificates signature key supports encryption.
-:* 4.3.  Public Key Length
+====== Private Key encyption well known======
-:DH parameter must be at least 256 bits or 2048 its with EC.
+:Certificates signature key encryption algorithm is well known.
-:(Check currently, 4/2016, based on openssl which may not provide DH
-: parameters for all ciphers.)
-:* 4.5.  Truncated HMAC
+====== Public Key encyption======
-:TLS extension "truncated hmac" must not be used.
+:Certificates public key supports encryption.
-:* 6.  Security Considerations
+====== Public Key encyption well known======
-:* 6.1.  Host Name Validation
-:Given hostname must matches hostname in certificate's subject.
+:Certificates public key encryption algorithm is well known.
-:* 6.2.  AES-GCM
+====== Public Key Modulus size======
-:* 6.3.  Forward Secrecy
-:* 6.4.  Diffie-Hellman Exponent Reuse
-:(NOT YET IMPLEMENTED).
-:* 6.5.  Certificate Revocation
+:Some (historic) SSL implementations are subject to buffer overflow if
+:the key exceeds 16384 or 32768 bits. The check is against 16384 bits.
-:OCSP and CRL Distrbution Point in cetificate must be defined.
+====== Public Key Modulus Exponent size======
-==== OUTPUT====
+:The modulus exponent should be = 65537 as it is a prime number and an
+:easy to calculate exponent.
+:If the exponent is less than 65537, "Boradcast" attacks are possible.
-:All output is designed to make it  easily parsable by postprocessors.
+:However, some (mainly historic) SSL implementations may have problems
-:Following rules are used:
+:to connect because they are not able to do the crypt mathematics with
+:exponenents larger than 65536.
+:If ecliptic curves are used, the result for these checks is always
+:<code>no (<<N/A ...)</code>.
-:*  Lines for formatting or header lines start with <code>=</code>.
+====== Sizes and Lengths of Certificate Settings======
-:*  Lines for verbosity or tracing start with <code>#</code>.
-:*  Errors and warnings start with <code>**</code>.
-:*  Empty lines are comments ;-)
-:*  Label texts end with a separation character; default is  <code>:</code>.
-:*  Label and value for all checks are separated by  at least one  TAB :character.
-:*  Texts for additional information are enclosed in  <code><<</code>  and  <code>>></code>.
-:*  <code>N/A</code> is used when no proper informations was found or provided.
-:    Replace  <code>N/A</code> by whatever you think is adequate:  "No answer",
+:  Serial Number <= 20 octets (RFC5280, 4.1.2.2.  Serial Number)
-:    "Not available",  "Not applicable",  ...
-:When used in  ''--legacy=full''  or  ''--legacy=simple''  mode, the output
+:...
-:may contain formatting lines for better (human) readability.
-===== Postprocessing Output=====
+====== DV-SSL - Domain Validation Certificate======
-:It is recommended to use the  ''--legacy=quick''  option, if the output
+:The Certificate must provide:
-:should be postprocessed, as it omits the default separation character
+* Common Name <code>/CN=</code> field
-:(<code>:</code> , see above) and just uses on single tab character (0x09, \t  or
+* Common Name <code>/CN=</code> in <code>subject</code>  or <code>subjectAltname</code> field
-:TAB) to separate the label text from the text of the result. Example:
+* Domain name in <code>commonName</code> or <code>altname</code> field
-         Label of the performed checkTABresult
-:More examples for postprocessing the output can be found here:
+====== EV-SSL - Extended Validation Certificate======
-:    https://github.com/OWASP/O-Saft/blob/master/contrib
-==== CUSTOMIZATION====
+:This check is performed according the requirements defined by the CA/
-:This tools can be customized as follows:
+:Browser Forum  https://www.cabforum.org/contents.html .
+:The Certificate must provide:
+:*  DV - Domain Validation Certificate (see above)
+:*  Organization name <code>/O=</code> Cn ''subject'' field
+:*  Organization name must be less to 64 characters
+:*  Business Category <code>/businessCategory=</code> in <code>subject</code> field
+:*  Registration Number <code>/serialNumber=</code> in <code>subject</code> field
+:*  Address of Place of Business in <code>subject</code> field
-*  Using command line options
+:Required are: <code>/C=</code>, <code>/ST=</code>, <code>/L=</code>
-:    This is a simple way to redefine  specific settings.  Please  see
+:Optional are: <code>/street=</code>, <code>/postalCode=</code>
-:    [[#CONFIGURATION OPTIONS|CONFIGURATION OPTIONS]]  below.
+:*  Validation period does not exceed 27 month
-*  Using Configuration file
+:See  [[#LIMITATIONS|LIMITATIONS]]  also.
-:    A configuration file can contain multiple configuration settings.
+===== Target (server) HTTP(S) Support=====
-:    Syntax is simply  KEY=VALUE. Please see [[#CONFIGURATION FILE|CONFIGURATION FILE]] below.
+====== STS header (see RFC 6797)======
-*  Using resource files
+:Using STS is no perfect security.  While the very first request using
+:http: is always prone to a MiTM attack, MiTM is possible to following
-:    A resource file can contain multiple command line options. Syntax
+:requests again, if STS is not well implemented on the server.
-:    is the same as for command line options iteself.  Each  directory
+:* Request with http: should be redirected to https:
-:    may contain its own resource file. Please see  [[#RC-FILE|RC-FILE]]  below.
+:* Redirects should use status code 301 (even others will work)
+:* Redirect's Location header must contain schema https:
-*  Using debugging files
+:* Redirect's Location header must redirect to same FQDN
+:* Redirect may use Refresh instead of Location header (not RFC6797)
+:* Redirects from HTTP must not contain STS header
+:* Answer from redirected page (HTTPS) must contain STS header
+:* Answer from redirected page for IP must not contain STS header
+:* STS header must contain includeSubDirectoy directive
+:* STS header max-age should be less than 1 month
+:* STS must not be set in http-equiv attribute of a meta TAG
+====== STS header preload attribute (''+preload'')======
+:To satisfy the requirements on  <code>https://hstspreload.appspot.com/</code>  the
+:HSTS header must:
+:* have the max-age with at least 18 weeks (10886400 seconds)
+:* have the includeSubDomains attribute
+:* have the preload attribute
+:* redirect to https first, then to sub-domains (if redirected)
+:* have an HSTS header in each redirect to https.
+:Additionally, the site must have:
+:* a valid certificate
+:* serve all subdomains over https.
+:Except the last requirement,  ''+preload''  will do the checks.
+:Note that  ''+preload''  is defined in  <code>.o-saft.pl</code>  only.
-:    These files are --nomen est omen-- used for debugging purposes.
+====== Public Key Pins header======
-:    However, they can be (mis-)used to redefine all settings too.
-:    Please see  [[#DEBUG-FILE|DEBUG-FILE]]  below.
-*  Using user specified code
+:TBD - to be described ...
-:    This file contains  user specified  program code.  It can also be
+===== Sizes =====
-:    (mis-)used to redefine all settings. Please see [[#USER-FILE|USER-FILE]]  below.
-:Customization is done by redefining values in internal data structure
+:Mainly in the certificate various counts, lengths and sizes of values
-:which are:  %cfg,  %data,  %checks,  %text,  %scores .
+:are checked and reported. All commands for these checks start with
+:<code>+cnt_</code>  or  <code>+len_</code>.  Up to now, there is no  <code>yes</code>  or  <code>no</code>  value
+:for these checks.
-:Unless used in  [[#DEBUG-FILE|DEBUG-FILE]]  or  [[#USER-FILE|USER-FILE]],  there is  no need to know
+:Following commands will check the value to be in  a specific range to
-:these internal data structures or the names of variables; the options
+:become  <code>yes</code>  or  <code>no</code>:
-:will set the  proper values.  The key names being part of the option,
+:* +sts_maxage1d       - yes if HSTS maxage < 1 day
-:are printed in output with the  ''--trace-key''  option.
+:* +sts_maxage1m       - yes if HSTS maxage < 1 month
+:* +sts_maxage1y       - yes if HSTS maxage < 1 year
+:* +sts_maxage18       - yes if HSTS maxage < 18 weeks (5 months)
+:* +sts_maxagexy       - yes if HSTS maxage > 1 year
+:* +modulus_exp_1      - Public Key Modulus Exponent <>1
+:* +modulus_exp_65537  - Public Key Modulus Exponent =65537
+:* +modulus_exp_oldssl - Public Key Modulus Exponent <65537
+:* +modulus_size_oldssl - Public Key Modulus <16385 bits
-:I.g. texts (values) of keys in  %data are those used in output of the
+:For some details of these checks, please see the description above at
-:<code>Informations</code> section. Texts of keys in  %checks are used for output
+:    "Public Key Modulus Exponent size"
-:in <code>Performed Checks</code> section.  And texts of keys in  %text  are used
-:for additional information lines or texts (mainly beginning with <code>=</code>).
-====== Configuration File vs. RC-FILE vs. DEBUG-FILE======
+:The recommendations for  DH parameters (RSA and ecliptice curve)  are
+:are checked as follows:
+:* +dh_512             - DH Parameter >= 512 bits
+:* +dh_2048            - DH Parameter >= 2048 bits
+:* +ecdh_256           - DH Parameter >= 256 bits (ECDH)
+:* +ecdh_512           - DH Parameter >= 512 bits (ECDH)
+:Note that only one of the checks  <code>+dh_*</code>  and  <code>+ecdh_*</code>  can return
+:<code>yes</code>.
-*  CONFIGURATION FILE
+===== ALPN and NPN=====
-:    Configuration Files must be specified with one of the   ''--cfg_*''
+:The commands for the checks to report  <code>yes</code>  or  <code>no</code>, are  ''+hasalpn''
-:    options. The specified file can be a valid path. Please note that
+:and  ''+hasnpn''.
-:    only the characters:  a-zA-Z_0-9,.\/()-  are allowed as pathname.
+:
-:    Syntax in configuration file is:  <code>KEY=VALUE</code>  where <code>KEY</code> is any
+:Both, the Application Layer Protocol Negotiation (ALPN) and the  Next
-:    key as used in internal data structure.
+:Protocol Negotiation (NPN) will be tested. The commands for that are:
-:    the keys in output).
+:* +alpns
+:* +npns
+:
+:Each, ALPN and NPN, is tested separately with all known protocols.
+:The test sets only one protocol,  tries to make a connection and then
+:checks if the protocol was accepted by the server. The collected list
+:of protocols will be printed with the aforementioned commands, or the
+:''+info''  command. Note the difference for the commands  ''+next_protocols''
+:and  ''+alpns'', where  ''+next_protocols''  simply reports  what  the server
+:itself advertises, while  ''+alpns''  reports what the server supports if
+:asked for.
-*  RC-FILE
+===== Compliances=====
-:    Resource files are searched for and used automatically.
+:Note that it is not possible to satisfy all following compliances. Best
-:    For details see [[#RC-FILE|RC-FILE]] below.
+:match is: ''PSF'' and ''ISM'' and ''PCI'' and ''lazy BSI TR-02102-2''.
-*  DEBUG-FILE
+:In general it is difficult to  satisfy all conditions of a compliances,
+:and it is also difficult to check all these conditions. That's why some
+:of the compliances checks are  not completely implemented,  for details
+:please see blow.
-:    Debug files are searched for and used automatically.
+:Note that output of results of some checks is disabled in the  [[#RC-FILE|RC-FILE]]
-:    For details see [[#DEBUG-FILE|DEBUG-FILE]] below.
+:by default. A  "!!Hint:"  message will be printed, if any of these checks
+:are used.
-*  USER-FILE
+:* FIPS-140
+:* ISM
+:* PCI
+:* BSI TR-02102 (2016-01)
+:* BSI TR-03116-4
+:* RFC 2818
+:* RFC 6125
+:* RFC 6797
+:* RFC 7525
-:    The user program file is included only if the  ''--usr'' option was
+======BSI TR-02102-2 (''+tr-02102+'' ''tr-02102-'' ''+bsi'')======
-:    used. For details see  [[#USER-FILE|USER-FILE]]  below.
-===== CONFIGURATION OPTIONS=====
+:Checks if connection and ciphers are compliant according TR-02102-2,
-:Configuration options are used to redefine  texts and labels or score
+:see https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen
-:settings used in output. The options are:
+:/TechnischeRichtlinien/TR02102/BSI-TR-02102-2_pdf.pdf?__blob=publicationFile
-:*  ''--cfg-cmd=KEY=LIST''
+:(following headlines are taken from TR-02102-2 Version 2016-01)
-:*  ''--cfg-checks=KEY=TEXT''
-:*  ''--cfg-data=KEY=TEXT''
-:*  ''--cfg-hint=KEY=TEXT''
-:*  ''--cfg-text=KEY=TEXT''
-:Here  <code>KEY</code> is the key used in the internal data structure and <code>TEXT</code>
+:*  3.1.3 Schlüssellängen bei EC-Verfahren
-:is the value to be set for this key.  Note that  unknown keys will be
-:ignored silently.
+:*  3.2   SSL/TLS_Versionen
+:    Only TLSv1.2 allowed (except for ''+tr-02102-''  which also allows
+:    TLSv1.1)
+:*  3.3.1 Empfohlene Cipher Suites
+:    Allows only *DHE-*-SHA256, *DHE-*-SHA384, *DH-*-SHA256 and
+:    *DH-*-SHA384 ciphers and PSK ciphers with ephermeral keys.
+:    For  ''+tr-02102+''  they must be AES-GCM,  ''+tr02102-'' also allows
+:    AES-CBC.
+:*  3.3.2 Übergangsregelungen
+:    SHA1 temporary allowed. SHA256 and SHA384 recommended.
+:    RC4 not reocmmended.
+:    Use of SHA1 will only be checked for  ''+tr-02102+''
-:If  <code>KEY=TEXT</code>  is an exiting filename,  all lines from that file are
+:*  3.4.1 Session Renegotation
-:read and set. For details see  [[#CONFIGURATION FILE|CONFIGURATION FILE]]  below.
-:NOTE that such configuration options should be used before any ''--help''
+:    Only server-side (secure) renegotiation allowed (see RFC5280).
-:or  ''--help=*''  option, otherwise the changed setting is not visible.
-===== CONFIGURATION FILE=====
+:*  3.4.2 Verkürzung der HMAC-Ausgabe
+:    Truncated HMAC according RFC 6066 not recommended.
+:*  3.4.3 TLS-Kompression und der CRIME-Angriff
+:    No TLS compression.
+:*  3.4.4 Der Lucky 13-Angriff
+:*  3.4.5 Die "Encrypt-thn-MAC"-Erweiterung
+:    Use of AES-GCM ciphers only.
+:    Use of Encrypt-then-MAC according RFC 7366 cannot be checked.
+:*  3.4.6 Die Heartbeat-Erweiterung
+:    Target must not support the heartbeat extension.
+:*  3.4.7 Die Extended Master Secret Extension
+:    Use of Extended Master Secret Extension according RFC 7627 cannot
+:    be checked.
+:*  3.5 Authentisierung der Kommunikationspartner
+:    Not checked as only applicable for VPN connections.
-:Note that the file can contain  <code>KEY=TEXT</code>  pairs for any kind of the
+:*  3.6 Domainparameter und Schlüssellängen
-:configuration as given by the  ''--cfg_CFG''  option.
-:For example when used  with  ''--cfg_text=file'' only values for  %text
+:    Check if signature key is > 2000 bits.
-:will be set, when used  with  ''--cfg_data=file'' only values for %data
-:will be set, and so on.  <code>KEY</code>  is not used when  <code>KEY=TEXT</code>  is an existing
-:filename. Though, it's recommended to use a non-existing key, i.e.:
-:''--cfg-text=my_file=some/path/to/private/file'' .
-===== RC-FILE=====
+:*  3.6.1 Verwendung von elliptischen Kurven
+:    **NOT YET IMPLEMENTED**
+:    Use only following curves according RFC 5639 and RFC 7027:
+:    brainpoolP256r1, brainpoolP384r1, brainpoolP512r1
+:    Use of secp256r1 and secp384r1  temporary allowed.
-:The rc-file will be searched for in the working directory only.
+:*  4.1 Schlüsselspeicherung
-:The name of the rc-file is the name of the program file prefixed by a
+:    This requirement is not testable from remote.
-:<code>.</code>  (dot),  for example:  <code>.o-saft.pl</code>.
-:A  rc-file  can contain any of the commands and options valid for the
+:*  4.1 Umgang mit Ephemeralschlüsseln
-:tool itself. The syntax for them is the same as on command line. Each
-:command or option must be in a single line. Any empty or comment line
-:will be ignored. Comment lines start with  <code>#</code>  or  <code>=</code>.
-:Note that options with arguments must be used as  <code>KEY=VALUE</code>  instead
+:    This requirement is not testable from remote.
-:of  <code>KEY VALUE</code>.
-:Configurations options must be written like <code>--cfg-CFG=KEY=VALUE</code>
+:*  4.3 Zufallszahlen
-:where "CFG" is any of:  cmd, check, data, text or score  and "KEY is
-:any key from internal data structure (see above).
-:All commands and options given on command line will  overwrite  those
+:    This requirement is not testable from remote.
-:found in the rc-file.
-===== DEBUG-FILE=====
+======BSI TR-03116-4 (''+tr-03116+'' ''+tr-03116-'' ''+bsi'')======
+:Checks if connection and ciphers are compliant according TR-03116-4,
+:see https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen
+:/TechnischeRichtlinien/TR03116/BSI-TR-03116-4.pdf?__blob=publicationFile
-:All debugging functionality is defined in ''o-saft-dbx.pm'', which will
+:(following headlines are taken from there)
-:be searched for using paths available in perl's  <code>@INC</code>  variable.
-: Syntax in this file is perl code.  For details see  [[#DEBUG|DEBUG]]  below.
+:* 2.1.1 TLS-Versionen und Sessions
-===== USER-FILE=====
+:Allows only TLS 1.2.
-:All user functionality is defined in  ''o-saft-usr.pm'',  which will be
+:* 2.1.2 Cipher Suites
-:searched for using paths available in perl's  <code>@INC</code>  variable.
-: Syntax in this file is perl code.
+:Cipher suites must be ECDHE-ECDSA or -RSA with AES128 and SHA265.
+:For curiosity, stronger cipher suites with AES256 and/or SHA384 are
+:not not allowed. To follow this curiosity the ''+bsi-tr-03116-'' (lazy)
+:check allows the stronger cipher suites ;-)
-:All functions defined in  ''o-saft-usr.pm''  are called when the option
+:* 2.1.1 TLS-Versionen und Sessions
-:''--usr''  was given. The functions are defined as empty stub, any code
-:can be inserted as need.  Please see  ''perldoc o-saft-usr.pm''  to see
-:when and how these functions are called.
-===== SHELL TWEAKS=====
+:The TLS session lifetime must not exceed 2 days.
-:Configuring the shell environment where the tool is startet,  must be
+:* 2.1.4.2 Encrypt-then-MAC-Extension
-:done before the tools starts.  It is  not really  a task for the tool
-:itself, but it can simplify your life, somehow.
+:* 2.1.4.3 OCSP-Stapling
-:There exist customizations for some commonly used shells,  please see
+:MUST have <code>OCSP Stapling URL</code>.
-:the files in the <code>./contrib/</code> directory.
-===== COMMANDS=====
+:* 4.1.1 Zertifizierungsstellen/Vertrauensanker
-:The option  ''--cfg-cmd=CMD=LIST''  can be used to define own commands.
+:Certificate must provide all root CAs. (NOT YET IMPLEMENTED).
-:When configuring own commands,  <code>CMD</code>  must not be  one of the commands
-:listed with  ''--help=intern''  and <code>CMD</code>  must constist only of digits and
-:letters.
-==== CIPHER NAMES====
+:Should use a small certificate trust chain.
-:While the SSL/TLS protocol uses integer numbers to identify  ciphers,
+:* 4.1.2 Zertifikate
-:almost all tools use some kind of  `human readable'  texts for cipher
-:names.
-:These numbers (which are most likely written  as hex values in source
+:Must have <code>CRLDistributionPoint</code> or <code>AuthorityInfoAccess</code>.
-:code and documentations) are the only true identifier, and we have to
-:rely on the tools that they use the proper integers.
-:As such integer or hex numbers are difficult to handle by humans,  we
+:End-user certificate must not be valid longer than 3 years.
-:decided to use human readable texts. Unfortunately no common standard
+:Root-CA certificate must not be valid longer than 5 years.
-:exists how to construct the names and map them to the correct number.
-:Some, but by far not all, oddities are described in [[#Name Rodeo|Name Rodeo]].
-:The rules for specifying cipher names are:
+:Certificate extension <code>pathLenConstraint</code> must exist, and should be
+:a small value ("small" is not defined).
-:
+:All certificates must contain the extension <code>KeyUsage</code>.
-:*  1. textual names as defined by IANA (see [IANA])
-:*  2. mapping of names and numbers as defined by IANA (see [IANA])
+:Wildcards for <code>CN</code> or <code>Subject</code> or <code>SubjectAltName</code> are not allowed
-:*  3. <code>-</code>  and  <code>_</code>  are treated the same
+:in any certificate.
-:*  4. abbreviations are allowed, as long as they are unique
-:*  5. beside IANA, openssl's cipher names are preferred
-:*  6. name variants are supported, as long as they are unique
-:*  7. hex numbers can be used
-:[IANA]    http://www.iana.org/assignments/tls-parameters/tls-parameters.txt September 2013
+:EV certificates are recommended (NOT YET checked properly).
-:[openssl] ... openssl 1.0.1
+:* 4.1.3 Zertifikatsverifikation
-:If in any doubt, use  ''+list''  to get an idea about the mapping.
+:Must verify all certificates in the chain down to their root-CA.
-:Use  ''--help=regex''  to see which regex  are used to handle all these
+:(NOT YET IMPLEMENTED).
-:variants herein.
-:Mind the traps and dragons with cipher names and what number they are
+:Certificate must be valid according issue and expire date.
-:actually mapped to. In particular when  ''--lib'', ''--exe'' or ''--openssl''
-:options are in use. Always use these options with ''+list'' command too.
-===== Name Rodeo=====
+:All Checks must be doen for all certificates in the chain.
-:As said above, the  SSL/TLS protocol uses integer numbers to identify
+:* 4.1.4 Domainparameter und Schlüssellängen
-:ciphers, but almost all tools use some kind of  human readable  texts
-:for cipher names.
-:For example the cipher commonly known as <code>DES-CBC3-SHA</code> is identified
+:This requirement is not testable from remote.
-:by <code>0x020701c0</code> (in openssl) and has <code>SSL2_DES_192_EDE3_CBC_WITH_SHA</code>
-:as constant name. A definition is missing in IANA, but there is
-:<code>TLS_RSA_WITH_3DES_EDE_CBC_SHA</code> .
-:It's the responsibility of each tool to map the human readable cipher
-:name to the correct (hex, integer) identifier.
-:For example Firefox uses  <code>dhe_dss_des_ede3_sha</code>,  which is what?
+:* 4 5.2 Zufallszahlen
-:Furthermore, there are different acronyms for the same thing in use.
+:This requirement is not testable from remote.
-:For example  <code>DHE</code>  and  <code>EDH</code>  both mean "Ephemeral Diffie-Hellman".
-:Comments in the ''openssl(1)'' sources mention this. And for curiosity
-:these sources use both in cypher names but allow  <code>EDH</code> as shortcut
-:only in openssl's "ciphers"  command. Wonder about (up to 1.0.1h):
-    openssl ciphers -V EDH
-    openssl ciphers -V DHE
-    openssl ciphers -V EECDH
-    openssl ciphers -V ECDHE
-:Next example is  <code>ADH</code>  which is also known as  <code>DH_anon</code> or <code>DHAnon</code>
+======RFC 2818 (''+rfc2818'')======
-:or  <code>DHA</code>  or  <code>ANON_DH</code>.
+:Check if the FQDN is listed in the certificates <code>subjectAltname</code>.
-:You think this is enough? Then have a look how many acronyms are used
+======RFC 6125 (''+rfc6125'')======
-:for  "Tripple DES".
+:Checks values <code>CommonName</code>, <code>Subject</code> and <code>SubjectAltname</code>  of the
+:certificate for:
+:* must all be valid characters for DNS
+:* must not contain more than one wildcards
+:* must not contain invalid wildcards
+:* must not contain invalid IDN characters
-:Compared to above, the interchangeable use of  <code>-</code>  vs.  <code>_</code> in human
+======RFC 6797 (''+rfc6797'')======
-:readable cipher names is just a very simple one. However, see openssl
+: Same as STS header  ''+hsts'' .
-:again what following means (returns):
-    openssl ciphers -v RC4-MD5
-    openssl ciphers -v RC4+MD5
-    openssl ciphers -v RC4:-MD5
-    openssl ciphers -v RC4:!MD5
-    openssl ciphers -v RC4!MD5
-:Looking at all these oddities, it would be nice to have a common unique
+======RFC 7525 (''+rfc7525'') ======
-:naming scheme for cipher names. We have not.  As the SSL/TLS protocol
+:Checks if connection and ciphers are compliant according RFC 7525.
-:just uses a number, it would be natural to use the number as uniq key
+:See http://tools.ietf.org/rfc/rfc7525.txt
-:for all cipher names, at least as key in our internal sources.
+:(following headlines are taken from there)
-:Unfortunately, the assignment of ciphers to numbers  changed over the
+:* 3.1.1.  SSL/TLS Protocol Versions
-:years, which means that the same number refers to a  different cipher
-:depending on the standard, and/or tool, or version of a tool you use.
-:As a result, we cannot use human readable cipher names as  identifier
+:SSLv2 and SSLv3 must not be supportetd.
-:(aka unique key), as there are  to many aliases  for the same cipher.
+:TLSv1 should only be supported if there is no TLSv1.1 or TLSv1.2.
-:And also the number  cannot be used  as unique key, as a key may have
+:Either TLSv1.1 or TLSv1.2 must be supported, prefered is TLSv1.2.
-:multiple ciphers assigned.
-==== KNOWN PROBLEMS====
+:* 3.1.2.  DTLS Protocol Versions
-:This section describes knwon problems, and known error messages which
+:DTLSv1 and DTLSv1.1 must not be supported.
-:may occour when using ''o-saft.pl''. This sections can be used as FAQ too
-:as it gives hints and workarounds.
-===== Segmentation fault=====
+:* 3.1.3.  Fallback to Lower Versions
-:Sometimes  the program terminates with a  <code>Segmentation fault</code>.  This
+:(check implecitely done by 3.1.1, see above)
-:mainly happens if the target does not return certificate information.
-:If so, the  ''--no-cert''  option may help.
-===== **WARNING: empty result from openssl; ignored at ...=====
+:* 3.2.  Strict TLS
-:This most likely occurs when the  provided cipher is  not accepted by
+:Check if server provides Strict Transport Security.
-:the server, or the server expects client certificates.
+:(STARTTLS check NOT YET IMPLEMENTED).
-===== **WARNING: unknown result from openssl; ignored at ...=====
+:* 3.3.  Compression
-:This most likely occurs when the  openssl  executable is used with a
+:Compression on TLS must not be supported.
-:very slow connection. Typically the reason is a connection timeout.
-:Try to use  ''--timeout=SEC''  option.
-:To get more information, use  ''--v'' ''--v''  and/or  ''--trace''  also.
-===== **WARNING: undefined cipher description=====
+:* 3.4.  TLS Session Resumption
-:May occour if ciphers are checked, but no description is available for
+:Server must support resumtion and random session tickets.
-:them herein. This results in printed cipher checks like:
+:(Randomnes of session tickets implemented YET experimental.)
-         EXP-KRB5-RC4-MD5                no       <undef>>
+:Check if ticket is authenticated and encrypted NOT YET IMPLEMENTED.
-:instead of:
+:* 3.5.  TLS Renegotiation
-         EXP-KRB5-RC4-MD5                no       weak
+:Server must support renegotiation.
-===== **WARNING: Can't make a connection to your.tld:443; no initial data=====
+:* 3.6.  Server Name Indication
-===== **WARNING: Can't make a connection to your.tld:443; target ignored=====
-:This message occours if the underlaying  SSL library (i.e. libssl.a)
+:(Check for SNI support implemented experimental.)
-:was not able to connect to the target. Known observed reasons are:
-:* target does not support SSL protocol on specified port
-:* target expects a client certificate in ClientHello message
-:More details why the connection failed can be seen using  ''--trace=2'' .
+:* 4.  Recommendations: Cipher Suites
-:If the targets supports SSL, it should be at least possible to check
+:* 4.1.  General Guidelines
-:for supported ciphers using  ''+cipherall''  instead of  ''+cipher'' .
+:* 4.2.  Recommended Cipher Suites
-===== Use of uninitialized value $headers in split ... do_httpx2.al)=====
+:Check for recommended ciphers.
-:The warning message (like follows or similar):
+:* 4.3.  Public Key Length
-:Use of uninitialized value $headers in split at blib/lib/Net/SSLeay.pm
+:DH parameter must be at least 256 bits or 2048 its with EC.
-:(autosplit into blib/lib/auto/Net/SSLeay/do_httpx2.al) line 1290.
+:(Check currently, 4/2016, based on openssl which may not provide DH
+: parameters for all ciphers.)
-:occurs if the target refused a connection on port 80.
+:* 4.5.  Truncated HMAC
-:This is considered a bug in ''Net::SSLeay''.
-:Workaround to get rid of this message: use  ''--no-http''  option.
-===== invalid SSL_version specified at ... IO/Socket/SSL.pm=====
+:TLS extension "truncated hmac" must not be used.
-:This error may occur on systems where a specific  SSL version is not
+:* 6.  Security Considerations
-:supported. Subject are mainly  SSLv2, SSLv3 TLSv1.3 and DTLSv1.
+:* 6.1.  Host Name Validation
-:For DTLSv1 the full message looks like:
-       invalid SSL_version specified at C:/programs/perl/perl/vendor/lib/IO/Socket/SSL.
-:See also  [[#Note on SSL versions|Note on SSL versions]] .
-:Workaround: use options like: ''--no-sslv2'' ''--no-sslv3'' ''--no-tlsv13'' ''--no-dtlsv1''
+:Given hostname must matches hostname in certificate's subject.
-===== Use of uninitialized value $_[0] in length at (eval 4) line 1.=====
+:* 6.2.  AES-GCM
+:* 6.3.  Forward Secrecy
+:* 6.4.  Diffie-Hellman Exponent Reuse
+:(NOT YET IMPLEMENTED).
-:This warning occours with IO::Socket::SSL 1.967, reason is unknown.
+:* 6.5.  Certificate Revocation
-:It seems not to harm functionality, hence no workaround, just ignore.
-===== Use of uninitialized value in subroutine entry at lib/IO/Socket/SSL.pm line 430.=====
+:OCSP and CRL Distrbution Point in cetificate must be defined.
-:Some versions of  IO::Socket::SSL return this error message if  *-MD5
+==== OUTPUT====
-:ciphers are used with other protocols than SSLv2.
-:Workaround: use  ''--no-md5-cipher''  option.
+:All output is designed to make it  easily parsable by postprocessors.
+:Following rules are used:
-===== Can't locate auto/Net/SSLeay/CTX_v2_new.al in @INC ... =====
+:*  Lines for formatting or header lines start with <code>=</code>.
+:*  Lines for verbosity or tracing start with <code>#</code>.
+:*  Errors and warnings start with <code>**</code>, hints start with <code>!!</code>.
+:*  Empty lines are comments ;-)
+:*  Label texts end with a separation character; default is  <code>:</code>.
+:*  Label and value for all checks are separated by  at least one  TAB  character.
+:*  Texts for additional information are enclosed in  <code><<</code>  and  <code>>></code>.
+:*  <code>N/A</code> is used when no proper informations was found or provided.
-:Underlaying library doesn't support the required SSL version.
+:    Replace  <code>N/A</code> by whatever you think is adequate:  "No answer",
-:See also  [[#Note on SSL versions|Note on SSL versions]] .
+:    "Not available",  "Not applicable",  ...
-:Workaround: use  ''--ssl-lazy''  option, or corresponding ''--no-SSL'' option.
+:  Lines not described above, will have the form (be default):
+         Label for information or check:  TABresult
-===== Read error: Connection reset by peer (,199725) at blib/lib/Net/SSLeay.pm (autosplit into blib/lib/auto/Net/SSLeay/tcp_read_all.al) line 535. =====
+:  For more details on these lines, please refer to  [[#RESULTS|RESULTS]]  above.
-:Error reported by some Net::SSLeay versions. Reason may be a timeout.
+:When used in  ''--legacy=full''  or  ''--legacy=simple''  mode, the output
-:This error cannot be omitted or handled properly.
+:may contain formatting lines for better (human) readability.
+===== Errors, Warnings, Hints=====
+:Errors, warnings and hints may be part of the output as needed. While
+:errors and warnings are printed immediately as they occour during the
+:program flow, hints are printed right after the corresponding result.
-:Workaround: try to use same call again (no guarantee, unfortunatelly)
+:Errors and warnings start with a unique 3-digit number.
-=====openssl: ...some/path.../libssl.so.1.0.0: no version information available (required by openssl)=====
+:Hints print an additional explanation of a specific result.  They are
+:are defined statically in the program code, or can be added on demand
+:by using the option  ''--cfg-hint=KEY=TEXT'' .
-:Mismatch of  openssl executable  and loaded underlaying library. This
+===== Postprocessing Output=====
-:most likely happens when options  ''--lib=PATH''  and/or  ''--exe=PATH''  are
-:used. See also  [[#Note on SSL versions|Note on SSL versions]] .
-:Hint: use following commands to get information about used libraries:
+:It is recommended to use the  ''--legacy=quick''  option, if the output
-   o-saft.pl +version
+:should be postprocessed, as it omits the default separation character
-   o-saft.pl --v --v +version
+:(<code>:</code> , see above) and just uses on single tab character (0x09, \t  or
+:TAB) to separate the label text from the text of the result. Example:
+         Label of the performed checkTABresult
-===== Integer overflow in hexadecimal number at ...=====
+:More examples for postprocessing the output can be found here:
+:    https://github.com/OWASP/O-Saft/blob/master/contrib
-:This error message may occour on  32-bit systems if perl was not com-
+==== CUSTOMIZATION====
-:piled with proper options. I.g. perl automatically converts the value
+:This tools can be customized as follows:
-:to a floating pont number.
-:Please report a bug with output of following command:
-   o-saft.pl +s_client +dump your.tld
-===== <<openssl did not return DH Paramter>>=====
+*  Using command line options
-:Text may be part of a value. This means that all checks according  DH
+:    This is a simple way to redefine  specific settings.  Please  see
-:parameters and logkam attack cannot be done.
+:    [[#CONFIGURATION OPTIONS|CONFIGURATION OPTIONS]]  below.
-:Workaround: try to use  --openssl=TOOL  option.
+*  Using Configuration file
-:This text may appears in any of the compliance checks (like +rfc7525)
+:    A configuration file can contain multiple configuration settings.
-:which may be a false positive.  For these checks openssl is also used
+:    Syntax is simply  KEY=VALUE. Please see [[#CONFIGURATION FILE|CONFIGURATION FILE]] below.
-:to get the DH Parameter.
+*  Using resource files
+:    A resource file can contain multiple command line options. Syntax
+:    is the same as for command line options iteself.  Each  directory
+:    may contain its own resource file. Please see  [[#RC-FILE|RC-FILE]]  below.
-:Workaround: not available yet
+*  Using debugging files
-=====No output with  +help  and/or  --help=todo =====
+:    These files are --nomen est omen-- used for debugging purposes.
+:    However, they can be (mis-)used to redefine all settings too.
+:    Please see  [[#DEBUG-FILE|DEBUG-FILE]]  below.
-:On some (mainly Windows-based) systems using
+*  Using user specified code
-   o-saft.pl +help
-   o-saft.pl --help
-:does not print anything.
-:Workaround: use  ''--v''  option.
+:    This file contains  user specified  program code.  It can also be
-    o-saft.pl +help --v
+:    (mis-)used to redefine all settings. Please see [[#USER-FILE|USER-FILE]]  below.
-:or
-   o-saft.pl +help | more
-===== **WARNING: on MSWin32 additional option  --v  required, sometimes ...=====
+:Customization is done by redefining values in internal data structure
+:which are:  %cfg,  %data,  %checks,  %text,  %scores .
-:On some (mainly Windows-based) systems  this may happen  when calling
+:Unless used in  [[#DEBUG-FILE|DEBUG-FILE]]  or  [[#USER-FILE|USER-FILE]],  there is  no need to know
-:for example:
+:these internal data structures or the names of variables; the options
-   o-saft.pl --help=FAQ
+:will set the  proper values.  The key names being part of the option,
-:which then may produce:
+:are printed in output with the  ''--trace-key''  option.
-   **WARNING: on MSWin32 additional option  --v  required, sometimes ...
-   === reading: ./.o-saft.pl (RC-FILE done) ===
-   === reading: Net/SSLinfo.pm (O-Saft module done) ===
-   **USAGE: no command given
-   # most common usage:
-     o-saft.pl +info   your.tld
-     o-saft.pl +check  your.tld
-     o-saft.pl +cipher your.tld
-   # for more help use:
-     o-saft.pl --help
-:Workaround: use full path to perl.exe, for example
+:I.g. texts (values) of keys in  %data are those used in output of the
-   C:\Programs\perl\bin\perl.exe o-saft.pl --help=FAQ
+:<code>Informations</code> section. Texts of keys in  %checks are used for output
+:in <code>Performed Checks</code> section.  And texts of keys in  %text  are used
+:for additional information lines or texts (mainly beginning with <code>=</code>).
-===== Performance Problems=====
+====== Configuration File vs. RC-FILE vs. DEBUG-FILE======
-:There are various reasons when the program responds slow, or seems to
+*  CONFIGURATION FILE
-:hang. Beside the problems described below performance issues are most
-:likely a target-side problem. Most common reasons are:
-*  a) DNS resolver problems
+:    Configuration Files must be specified with one of the   ''--cfg_*''
-:Try with  ''--no-dns''
+:    options. The specified file can be a valid path. Please note that
+:    only the characters:  <code>-zA-Z_0-9,.\/()-</code>  are allowed as pathname.
+:    Syntax in configuration file is:  <code>KEY=VALUE</code>  where <code>KEY</code> is any
+:    key as used in internal data structure.
+:    the keys in output).
-*  b) target does not accept connections for https
+*  RC-FILE
-:Try with  ''--no-http''
-*  c) target's certificate is not valid
+:    Resource files are searched for and used automatically.
-:Try with  ''--no-cert''
+:    For details see [[#RC-FILE|RC-FILE]] below.
-*  d) target expects that the client provides a client certificate
+*  DEBUG-FILE
-:No option provided yet ...
-*  e) target does not handle Server Name Indication (SNI)
+:    Debug files are searched for and used automatically.
-:Try with  ''--no-sni''
+:    For details see [[#DEBUG-FILE|DEBUG-FILE]] below.
-*  f) use of external openssl(1) executable
+*  USER-FILE
-:Use  ''--no-openssl''
-:Other options which may help to get closer to the problem's cause:
+:    The user program file is included only if the  ''--usr'' option was
-:''--timeout=SEC'',  ''--trace'',  ''--trace=cmd''
+:    used. For details see  [[#USER-FILE|USER-FILE]]  below.
-==== LIMITATIONS====
+===== CONFIGURATION OPTIONS=====
+:Configuration options are used to redefine  texts and labels or score
+:settings used in output. The options are:
-===== Commands=====
+:*  ''--cfg-cmd=CMD=LIST''
+:*  ''--cfg-checks=KEY=TEXT''
+:*  ''--cfg-data=KEY=TEXT''
+:*  ''--cfg-hint=KEY=TEXT''
+:*  ''--cfg-text=KEY=TEXT''
+:*  ''--cfg-cipher=CIPHER=TEXT''
-:Some commands cannot be used together with others, for example:
+:<code>KEY</code>  is the key used in the internal data structure, and  <code>TEXT</code> is the
-:''+cipher'',  ''+ciphers'',  ''+list'',  ''+libversion'',  ''+version'',  ''+check'',  ''+help'',
+:value to be set for this key.  Note that unknown keys will be ignored
-:''+protocols'' .
+:silently.
-:''+quick''  should not be used together with other commands, it returns
+:If  <code>KEY=TEXT</code>  is an exiting filename,  all lines from that file are
-:strange output then.
+:read and set. For details see  [[#CONFIGURATION FILE|CONFIGURATION FILE]]  below.
-:''+protocols''  requires  ''openssl(1)'' with support for <code>-nextprotoneg</code>
+:<code>CIPHER</code> must be a valid cipher suite name as shown with:
-:option. Otherwise the value will be empty.
-===== Options=====
+    o-saft.pl ciphers
-:The option  ''--port=PORT''  must preceed  ''--host=HOST''  for a target like
+:NOTE that such configuration options should be used before any ''--help''
-:''HOST:PORT'' .
+:or  ''--help=*''  option, otherwise the changed setting is not visible.
-:The characters <code>+</code> and <code>=</code> cannot be used for ''--separator'' option.
+===== CONFIGURATION FILE=====
-:Following strings should not be used in any value for options:
+:Note that the file can contain  <code>KEY=TEXT</code>  pairs for any kind of the
-:  <code>+check</code>, <code>+info</code>, <code>+quick</code>, <code>--header</code>
+:configuration as given by the  [[#--cfg_CFG|--cfg_CFG]]  option.
-:as they my trigger the  -''--header''  option unintentional.
-:The used ''timeout(1)'' command cannot be defined with a full path like
+:For example when used  with  [[#--cfg_text=FILE|--cfg_text=FILE]] only values for  %text
-:''openssl(1)''  can with the  ''--openssl=path/to/openssl''.
+:will be set, when used  with  [[#--cfg_data=FILE--cfg_data=FILE]] only values for %data
+:will be set, and so on.  <code>KEY</code>  is not used when  <code>KEY=TEXT</code>  is an existing
+:filename. Though, it's recommended to use a non-existing key, i.e.:
+:''--cfg-text=my_file=some/path/to/private/file'' .
-:''--cfg_text=file''  cannot be used to redefine the texts <code>yes</code> and <code>no</code>
+===== RC-FILE=====
-:as used in the output for  ''+cipher''  command.
-===== Checks (general)=====
+:The rc-file will be searched for in the working directory only.
-====== +constraints======
+:The name of the rc-file is the name of the program file prefixed by a
+:<code>.</code>  (dot),  for example:  <code>.o-saft.pl</code>.
-:This check is only done for the certificate provided by the target.
+:A  rc-file  can contain any of the commands and options valid for the
-:All other certificate in the chain are not checked.
+:tool itself. The syntax for them is the same as on command line. Each
+:command or option must be in a single line. Any empty or comment line
+:will be ignored. Comment lines start with  <code>#</code>  or  <code>=</code>.
-:This is currently (2015) a limitation in ''o-saft.pl''.
+:Note that options with arguments must be used as  <code>KEY=VALUE</code>  instead
+:of  <code>KEY VALUE</code>.
-===== Broken pipe=====
+:Configurations options must be written like <code>--cfg-CFG=KEY=VALUE</code>
+:where <code>CFG</code> is any of:  <code>cmd</code>, <code>check</code>, <code>data</code>, <code>text</code>  and <code>KEY</code> is
+:any key from internal data structure (see above).
-:This error message most likely means that the connection to specified
+:All commands and options given on command line will  overwrite  those
-:target was not possible (firewall or whatever reason).
+:found in the rc-file.
-===== Target Certificate Chain Verification=====
+===== DEBUG-FILE=====
-:The systems default capabilities i.e. libssl.so, openssl, are used to
+:All debugging functionality is defined in ''o-saft-dbx.pm'', which will
-:verify the target's certificate chain.  Unfortunately various systems
+:be searched for using paths available in  <code>@INC</code>  variable.
-:have implemented different  approaches and rules how identify and how
-:to report a successful verification.  As a consequence  this tool can
-:only return the  same information about the chain verification as the
-:used underlying tools.  If that information is trustworthy depends on
-:how trustworthy the tools are.
-:These limitations apply to following commands:
+: Syntax in this file is Perl code.  For details see  [[#DEBUG|DEBUG]]  below.
-:*  ''+verify''
+===== USER-FILE=====
-:*  ''+selfsigned''
-:Following commands and options are useful to get more information:
+:All user functionality is defined in  ''o-saft-usr.pm'',  which will be
+:searched for using paths available in  <code>@INC</code>  variable.
-:*  ''+chain_verify'', ''+verify'', ''+error_verify'', ''+chain'', ''+s_client''
+: Syntax in this file is Perl code.
-:*  ''--ca-file'', ''--ca-path'', ''--ca-depth''
-===== User Provided Files=====
+:All functions defined in  ''o-saft-usr.pm''  are called when the option
+:''--usr''  was given. The functions are defined as empty stub, any code
+:can be inserted as need.  Please see  ''perldoc o-saft-usr.pm''  to see
+:when and how these functions are called.
-:Please note that there cannot be any guarantee that the code provided
+===== SHELL TWEAKS=====
-:in the   [[#DEBUG-FILE|DEBUG-FILE]] ''o-saft-usr.pm''  or   [[#USER-FILE|USER-FILE]]  ''o-saft-usr.pm''
-:will work flawless. Obviously this is the user's responsibility.
-===== Problems and Errors=====
+:Configuring the shell environment where the tool is startet,  must be
+:done before the tools starts.  It is  not really  a task for the tool
+:itself, but it can simplify your life, somehow.
-:Checking the target for supported ciphers may return that a cipher is
+:There exist customizations for some commonly used shells,  please see
-:not supported by the server  misleadingly.  Reason is most likely  an
+:the files in the <code>./contrib/</code> directory.
-:improper timeout for the connection. See  ''--timeout=SEC''  option.
-:If the specified targets accepts connections but does not speak  SSL,
+===== COMMANDS=====
-:the connection will be closed after the system's TCP/IP-timeout. This
-:script will hang (about 2-3 minutes).
-:If reverse DNS lookup fails, an error message is returned as hostname,
+:The option  ''--cfg-cmd=CMD=LIST''  can be used to define own commands.
-:like:  <code><<gethostbyaddr() failed</code>>>.
+:When configuring own commands,  <code>CMD</code>  must not be  one of the commands
-:Workaround to get rid of this message: use  ''--no-dns''  option.
+:listed with  ''--help=intern''  and <code>CMD</code>  must constist only of digits and
+:letters.
-:All checks for EV are solely based on the information provided by the
+:Examples in  ''.o-saft.pl''  are  ''+preload''  and  ''+ciphercheck'' .
-:certificate.
-:Some versions of openssl (< 1.x) may not support all required options
+==== CIPHER NAMES====
-:which results in various error messages or --more worse--  may not be
-:visibale at all.
-:Following table shows the openssl option and how to disbale it within
-:o-saft:
-:-nextprotoneg       ''--no-nextprotoneg''
+:While the SSL/TLS protocol uses integer numbers to identify  ciphers,
+:almost all tools use some kind of  `human readable'  texts for cipher
+:names.
-:-reconnect          ''--no-reconnect''
+:These numbers (which are most likely written  as hex values in source
+:code and documentations) are the only true identifier, and we have to
+:rely on the tools that they use the proper integers.
-:-tlsextdebug        ''--no-tlsextdebug''
+:As such integer or hex numbers are difficult to handle by humans,  we
+:decided to use human readable texts. Unfortunately no common standard
-===== Poor Systems=====
+:exists how to construct the names and map them to the correct number.
+:Some, but by far not all, oddities are described in [[#Name Rodeo|Name Rodeo]].
-:Use of  ''openssl(1)'' is disabled by default on Windows due to various
+:The rules for specifying cipher names are:
-:performance problems. It needs to be enabled with ''--openssl'' option.
-:On Windows the usage of  <code>openssl s_client</code> needs to be enabled using
+:
-:''--s_client'' option.
+:*  1. textual names as defined by IANA (see [IANA])
+:*  2. mapping of names and numbers as defined by IANA (see [IANA])
+:*  3. <code>-</code>  and  <code>_</code>  are treated the same
+:*  4. abbreviations are allowed, as long as they are unique
+:*  5. beside IANA, openssl's cipher names are preferred
+:*  6. name variants are supported, as long as they are unique
+:*  7. hex numbers can be used
-:On Windows it's a pain to specify the path for ''--openssl=..'' option.
+:[IANA]    http://www.iana.org/assignments/tls-parameters/tls-parameters.txt September 2013
-:Variants are:
-:*  --openssl=/path/to/openssl.exe
+:[openssl] ... openssl 1.0.1
-:*  --openssl=X:/path/to/openssl.exe
-:*  --openssl=\path\to\openssl.exe
-:*  --openssl=X:\path\to\openssl.exe
-:*  --openssl=\\path\\to\\openssl.exe
-:*  --openssl=X:\\path\\to\\openssl.exe
-:You have to fiddle around to find the proper one.
+:If in any doubt, use  ''+list''  to get an idea about the mapping.
+:Use  ''--help=regex''  to see which regex  are used to handle all these
+:variants herein.
-===== Debug and Trace Output=====
+:Mind the traps and dragons with cipher names and what number they are
+:actually mapped to. In particular when  ''--lib'', ''--exe'' or ''--openssl''
+:options are in use. Always use these options with ''+list'' command too.
-: When both  ''--trace=key''  and  ''--trace=cmd''  options are used, output is
+===== Name Rodeo=====
-: mixed, obviously. Hint: output for ''--trace=cmd'' always contains "CMD".
-==== DEPENDENCIES====
+:As said above, the  SSL/TLS protocol uses integer numbers to identify
+:ciphers, but almost all tools use some kind of  human readable  texts
+:for cipher names.
-:All perl modules and all  private moduels and files  will be searched
+:For example the cipher commonly known as <code>DES-CBC3-SHA</code> is identified
-:for using paths available in perl's  <code>@INC</code>  variable.  <code>@INC</code>  will
+:by <code>0x020701c0</code> (in openssl) and has <code>SSL2_DES_192_EDE3_CBC_WITH_SHA</code>
-:be prepended by following paths:
+:as constant name. A definition is missing in IANA, but there is
+:<code>TLS_RSA_WITH_3DES_EDE_CBC_SHA</code> .  Thers is also <code>0x000A</code> for the same
+:cipher <code>DES-CBC3-SHA</code>. Both are valid, first one when used with SSLv2,
+:and second one when used with SSLv3.
+:It's the responsibility of each tool to map the human readable cipher
+:name to the correct (hex, integer) identifier.
-:*   .
+:For example Firefox uses  <code>dhe_dss_des_ede3_sha</code>,  which is what?
-:*   ./lib
-:*   INSTALL_PATH
-:*   INSTALL_PATH/lib
-:Where  <code>INSTALL_PATH</code>  is the path where the tool is installed.
+:Furthermore, there are different acronyms for the same thing in use.
-:To see which files have been included use:
+:For example  <code>DHE</code>  and  <code>EDH</code>  both mean "Ephemeral Diffie-Hellman".
+:Comments in the ''openssl(1)'' sources mention this. And for curiosity
+:these sources use both in cypher names but allow  <code>EDH</code> as shortcut
+:only in openssl's "ciphers"  command. Wonder about (up to 1.0.1h):
+    openssl ciphers -V EDH
+    openssl ciphers -V DHE
+    openssl ciphers -V EECDH
+    openssl ciphers -V ECDHE
-    o-saft.pl +version --v --user
+:Next example is  <code>ADH</code>  which is also known as  <code>DH_anon</code> or <code>DHAnon</code>
+:or  <code>DHA</code>  or  <code>ANON_DH</code>.
-===== Perl Modules=====
+:You think this is enough? Then have a look how many acronyms are used
+:for  "Tripple DES".
-*  ''IO::Socket::SSL(1)''
+:Compared to above, the interchangeable use of  <code>-</code>  vs.  <code>_</code> in human
-*  ''IO::Socket::INET(1)''
+:readable cipher names is just a very simple one. However, see openssl
-*  ''Net::SSLeay(1)''
+:again what following means (returns):
-*  ''Net::SSLinfo(1)''
+    openssl ciphers -v RC4-MD5
-*  ''Net::SSLhello(1)''
+    openssl ciphers -v RC4+MD5
+    openssl ciphers -v RC4:-MD5
+    openssl ciphers -v RC4:!MD5
+    openssl ciphers -v RC4!MD5
-===== Additional Files used if requested=====
+:Looking at all these oddities, it would be nice to have a common unique
+:naming scheme for cipher names. We have not.  As the SSL/TLS protocol
+:just uses a number, it would be natural to use the number as uniq key
+:for all cipher names, at least as key in our internal sources.
-*  ''.o-saft.pl''
+:Unfortunately, the assignment of ciphers to numbers  changed over the
-*  ''o-saft-dbx.pm''
+:years, which means that the same number refers to a  different cipher
-*  ''o-saft-man.pm''
+:depending on the standard, and/or tool, or version of a tool you use.
-*  ''o-saft-usr.pm''
-*  ''o-saft-README''
-==== INSTALLATION====
+:As a result, we cannot use human readable cipher names as  identifier
+:(aka unique key), as there are  to many aliases  for the same cipher.
+:And also the number  cannot be used  as unique key, as a key may have
+:multiple ciphers assigned.
-:The tool can be installed in any path. It just requres the modules as
+==== KNOWN PROBLEMS====
-:described in  [[#DEPENDENCIES|DEPENDENCIES]]  above. However, it's recommended that the
-:modules ''Net::SSLhello'' and ''Net::SSLinfo'' are found in the directory
-:<code>./Net/</code>  where  <code>o-saft.pl</code>  is installed.
-:For security reasons, most modern libraries disabled or even removed
+:This section describes knwon problems, and known error messages which
-:insecure or "dirty" functionality. As this tool's purpose is to find
+:may occour when using ''o-saft.pl''. This sections can be used as FAQ too
-:such insecure settings, functions, etc., it needs these dirty things
+:as it gives hints and workarounds.
-:enabled. What we need is (incomplete list):
-:* insecure protocols like SSLv2, SSLv3
+===== Segmentation fault=====
-:* more more ciphers enabled, like NULL-MD5, AECDH-NULL-SHA, etc.
-:* some SSL extensions and options
-:Therefore we recommend to compile and install at least following:
+:Sometimes  the program terminates with a  <code>Segmentation fault</code>.  This
+:mainly happens if the target does not return certificate information.
+:If so, the  ''--no-cert''  option may help.
-:* openssl  with SSLv2, SSLv3 and more ciphers enabled
+===== **WARNING: empty result from openssl; ignored at ...=====
-:* Net::SSLeay  compiled with openssl version as described before.
-:Please read the  [[#SECURITY|SECURITY]]  section first before following the install
+:This most likely occurs when the  provided cipher is  not accepted by
-:instructions below.
+:the server, or the server expects client certificates.
-=====OpenSSL=====
+===== **WARNING: unknown result from openssl; ignored at ...=====
-:Currently it is recommend to use either the openssl version from
+:This most likely occurs when the  openssl  executable is used with a
-:[https://github.com/PeterMosmans/openssl/ https://github.com/PeterMosmans/openssl/] which requires compilation,
+:very slow connection. Typically the reason is a connection timeout.
-:see  [[#Example: Compile OpenSSL|Example: Compile OpenSSL]], or use any of the precomiled versions
+:Try to use  ''--timeout=SEC''  option.
-:which are available for several platforms at [https://testssl.sh/ https://testssl.sh/] .
+:To get more information, use  ''--v'' ''--v''  and/or  ''--trace''  also.
-:The sources are available at
+===== **WARNING: undefined cipher description=====
-:* [https://github.com/PeterMosmans/openssl/archive/1.0.2-chacha.zip https://github.com/PeterMosmans/openssl/archive/1.0.2-chacha.zip]
-:The precomiled static versions are available at
-:* [https://github.com/drwetter/testssl.sh/tree/master/bin https://github.com/drwetter/testssl.sh/tree/master/bin]
-:For all following installation examples we assume:
+:May occour if ciphers are checked, but no description is available for
-:* openssl-1.0.2-chacha.zip or openssl-1.0.2d.tar.gz
+:them herein. This results in printed cipher checks like:
-:* /usr/local as bae installation directory
-:* a bourne shell (sh) compatible shell
-=====Example: Precompiled OpenSSL=====
+         EXP-KRB5-RC4-MD5                no       <undef>>
-:Simply download the tarball or zip file for your platform, unpack it,
+:instead of:
-:and install (copy) the binaries into a directory of your choice.
-=====Example: Compile OpenSSL=====
+         EXP-KRB5-RC4-MD5                no       weak
-:OpenSSL can be used from [http://openssl.org/ http://openssl.org/] or, as recommended, from
+===== **WARNING: Can't make a connection to your.tld:443; no initial data=====
-:[https://github.com/PeterMosmans/openssl/ https://github.com/PeterMosmans/openssl/] .
+===== **WARNING: Can't make a connection to your.tld:443; target ignored=====
-:'''OpenSSL-chacha'''
+:This message occours if the underlaying  SSL library (i.e. libssl.a)
-:Compiling and installing the later is as simple as:
+:was not able to connect to the target. Known observed reasons are:
-    unzip openssl-1.0.2-chacha.zip
+:* target does not support SSL protocol on specified port
-    cd openssl-1.0.2-chacha
+:* target expects a client certificate in ClientHello message
-    ./config --shared -Wl,-rpath=/usr/local/lib
-    make
+:More details why the connection failed can be seen using  ''--trace=2'' .
-    make test
-    make install
-:which will install openssl, libssl.so, libcrypto.so  and some include
+:If the targets supports SSL, it should be at least possible to check
-:files as well as the include files in  /usr/local/ .
+:for supported ciphers using  ''+cipherall''  instead of  ''+cipher'' .
-:The shared version of the libraries are necessary for  Net::SSLeay.
-:'''OpenSSL.org'''
+===== Use of uninitialized value $headers in split ... do_httpx2.al)=====
-:Building openssl from the offical  openssl.org  sources requires some
-:patching before compiling and installing the libraries and binaries.
-:Example with openssl-1.0.2d:
+:The warning message (like follows or similar):
-   echo == unpack tarball
+:Use of uninitialized value $headers in split at blib/lib/Net/SSLeay.pm
-   tar xf openssl-1.0.2d.tar.gz
+:(autosplit into blib/lib/auto/Net/SSLeay/do_httpx2.al) line 1290.
-   cd openssl-1.0.2d
-   echo == backup files to be modified
-   cp ssl/s2_lib.c{,.bak}
-   cp ssl/s3_lib.c{,.bak}
-   cp ssl/ssl3.h{,.bak}
-   cp ssl/tls1.h{,.bak}
-   echo == patch files
+:occurs if the target refused a connection on port 80.
-   vi ssl/tls1.h         +/TLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES/
+:This is considered a bug in ''Net::SSLeay''.
-            # define TLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES  1
+:Workaround to get rid of this message: use  ''--no-http''  option.
-   vi ssl/ssl3.h ssl/s{2,3}_lib.c   +"/# *if 0/"
-            #==> remove all   # if 0  and corresponding  #endif
+===== invalid SSL_version specified at ... IO/Socket/SSL.pm=====
-            #    except if lines contain:
-            #        _FZA
+:This error may occur on systems where a specific  SSL version is not
-            #        /* Fortezza ciphersuite from SSL 3.0
+:supported. Subject are mainly  SSLv2, SSLv3 TLSv1.3 and DTLSv1.
-            #        /* Do not set the compare functions,
+:For DTLSv1 the full message looks like:
-            #        if (s->shutdown & SSL_SEND_SHUTDOWN)
+        invalid SSL_version specified at C:/programs/perl/perl/vendor/lib/IO/Socket/SSL.
+:See also  [[#Note on SSL versions|Note on SSL versions]] .
-   echo == configure with static libraries
+:Workaround: use options like: ''--no-sslv2'' ''--no-sslv3'' ''--no-tlsv13'' ''--no-dtlsv1''
-   echo omitt the zlib options if zlib-1g-dev is not installed
-   echo omitt the krb5 options if no kerberos libraries available
-   ./config --prefix=/usr/local --openssldir=/usr/local/ssl \
-       enable-zlib zlib zlib-dynamic enable-ssl2 \
-       enable-krb5 --with-krb5-flavor=MIT \
-       enable-mdc2 enable-md2  enable-rc5  enable-rc2 \
-       enable-cms  enable-ec   enable-ec2m enable-ecdh enable-ecdsa \
-       enable-gost enable-seed enable-idea enable-camellia \
-       enable-rfc3779 enable-ec_nistp_64_gcc_128 \
-       experimental-jpake -fPIC \
-       -DTEMP_GOST_TLS -DTLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES \
-       shared
-   echo == make binaries and libraries
+===== Use of uninitialized value $_[0] in length at (eval 4) line 1.=====
-   make depend
-   make
-   make test
-   make install
-   echo == if you want static binaries and libraries
+:This warning occours with IO::Socket::SSL 1.967, reason is unknown.
-   make clean
+:It seems not to harm functionality, hence no workaround, just ignore.
-   echo same ./config as before but without shared option
-   ./config --prefix=/usr/local --openssldir=/usr/local/ssl \
-       enable-zlib zlib zlib-dynamic enable-ssl2 \
-       enable-krb5 --with-krb5-flavor=MIT \
-       enable-mdc2 enable-md2 enable-rc5 enable-rc2 \
-       enable-cms  enable-ec   enable-ec2m enable-ecdh enable-ecdsa \
-       enable-gost enable-seed enable-idea enable-camellia \
-       enable-rfc3779 enable-ec_nistp_64_gcc_128 \
-       experimental-jpake -fPIC \
-       -DTEMP_GOST_TLS -DTLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES
-   make depend
-   make
-   make test
-   echo next make will overwrite the previously installed dynamic
-   echo shared openssl binary with the static openssl binary
-   make install
-=====Example: Compile Net::SSLeay=====
+===== Use of uninitialized value in subroutine entry at lib/IO/Socket/SSL.pm line 430.=====
-:To enable support for ancient protocol versions,  ''Net::SSLeay'' must be
+:Some versions of  IO::Socket::SSL return this error message if  *-MD5
-:compiled manually after patching 'SSLeay.xs' (see below).
+:ciphers are used with other protocols than SSLv2.
-:Reason is, that  ''Net::SSLeay''  enables some functionality for  SSL/TLS
-:according the identified openssl version. There is, currently (2015),
-:no possibility to enable this functionality  by passing options on to
-:the configuration script <code>perl Makefile.PL</code>.
-    echo == unpack tarball
+:Workaround: use  ''--no-md5-cipher''  option.
-    tar xf Net-SSLeay-1.72.tar.gz
-    cd Net-SSLeay-1.72
-    echo == patch files
+===== Can't locate auto/Net/SSLeay/CTX_v2_new.al in @INC ... =====
-    echo "edit SSLeay.xs and change some #if as described below"
-    env OPENSSL_PREFIX=/usr/local perl Makefile.PL PREFIX=/usr/local \
-          INC=/usr/local/include  DEFINE=-DOPENSSL_BUILD_UNSAFE=1
-    make
-    make install
-    cd /tmp && o-saft.pl +version
-:SSLeay.xs needs to be changed as follows:
+:Underlaying library doesn't support the required SSL version.
-* search for
+:See also  [[#Note on SSL versions|Note on SSL versions]] .
-    #ifndef OPENSSL_NO_SSL2
-    #if OPENSSL_VERSION_NUMBER < 0x10000000L
+:Workaround: use  ''--ssl-lazy''  option, or corresponding ''--no-SSL'' option.
-    const SSL_METHOD *
-    SSLv2_method()
-    #endif
-    #endif
-    #ifndef OPENSSL_NO_SSL3
-    #if OPENSSL_VERSION_NUMBER < 0x10002000L
-    const SSL_METHOD *
-    SSLv3_method()
-    #endif
-    #endif
-* and replace by
-    const SSL_METHOD *
-    SSLv2_method()
-    const SSL_METHOD *
-    SSLv3_method()
-:Note that  ''Net::SSLeay''  will be installed in <code>/usr/local/</code> then. This
+===== Read error: Connection reset by peer (,199725) at blib/lib/Net/SSLeay.pm (autosplit into blib/lib/auto/Net/SSLeay/tcp_read_all.al) line 535. =====
-:can be adapted to your needs by passing another path to the  <code> PREFIX</code>
-:and  <code> DESTDIR</code>   parameter.
-=====Testing OpenSSL=====
+:Error reported by some Net::SSLeay versions. Reason may be a timeout.
+:This error cannot be omitted or handled properly.
-:After installation as descibed above finished, openssl may be tested:
+:Workaround: try to use same call again (no guarantee, unfortunatelly)
-    echo already installed openssl (found with PATH environment)
+===== Odd number of elements in anonymous hash at Net/SSLinfo.pm line 1613. =====
-    openssl ciphers -v
-    openssl ciphers -V -ssl2
-    openssl ciphers -V -ssl3
-    openssl ciphers -V ALL
-    openssl ciphers -V ALL:COMPLEMENTOFALL
-    openssl ciphers -V ALL:eNULL:EXP
-    echo own compiled and installed openssl
+:This warning from perl have been observed  when the connection to the
-    /usr/local/openssl ciphers -v
+:target to check for supported ciphers cannot be established.
-    /usr/local/openssl ciphers -V -ssl2
-    /usr/local/openssl ciphers -V -ssl3
-    /usr/local/openssl ciphers -V ALL
-    /usr/local/openssl ciphers -V ALL:COMPLEMENTOFALL
-    /usr/local/openssl ciphers -V ALL:eNULL:EXP
-The difference should be obvious.
+:This message can be ignored.
-Note, the commands using  "ALL:COMPLEMENTOFALL"  and  "ALL:eNULL:EXP"
-should return the same result.
-=====Testing Net::SSLeay=====
+=====openssl: ...some/path.../libssl.so.1.0.0: no version information available (required by openssl)=====
-:As we want to test the separately installed  ''Net::SSLeay'',  it is best
+:Mismatch of  openssl executable  and loaded underlaying library. This
-:to do it with  <code>o-saft.pl</code>  itself:
+:most likely happens when options  ''--lib=PATH''  and/or  ''--exe=PATH''  are
+:used. See also  [[#Note on SSL versions|Note on SSL versions]] .
-    o-saft.pl +version
+:Hint: use following commands to get information about used libraries:
+   o-saft.pl +version
+   o-saft.pl --v --v +version
-:we should see a line similar to follwong at the end of the output:
+===== Integer overflow in hexadecimal number at ...=====
-    Net::SSLeay   1.72  /usr/local/lib/x86_64-linux-gnu/perl/5.20.2/Net/SSLeay.pm
+:This error message may occour on  32-bit systems if perl was not com-
+:piled with proper options. I.g. perl automatically converts the value
+:to a floating pont number.
+:Please report a bug with output of following command:
+   o-saft.pl +s_client +dump your.tld
-:Now check for supported (known) ciphers:
+===== <<openssl did not return DH Paramter>>=====
-    o-saft.pl ciphers -V
+:Text may be part of a value. This means that all checks according  DH
+:parameters and logkam attack cannot be done.
-:we should see lines similar to those of the last  <code>/usr/local/openssl</code>
+:Workaround: try to use  --openssl=TOOL  option.
-:call. However, it should contain more cipher lines.
-=====Stand-alone Executable=====
+:This text may appears in any of the compliance checks (like +rfc7525)
+:which may be a false positive.  For these checks openssl is also used
+:to get the DH Parameter.
-:Some people asked for a stand-alone executable (mainly for Windows).
+:Workaround: not available yet
-:Even perl is a scripting language there are situations where a stand-
-:alone executable would be nice, for example if the installed perl and
-:its libraries are outdated, or if perl is missing at all.
-:Currently (2016) there a at least following possibilities to generate
+=====No output with  +help  and/or  --help=todo =====
-:a stand-alone executable:
-* perl with PAR::Packer module
+:On some (mainly Windows-based) systems using
-      pp -C -c o-saft.pl
+   o-saft.pl +help
-      pp -C -c o-saft.pl -M Net::DNS -M Net::SSLeay -M IO::Socket \
+   o-saft.pl --help
-                         -M Net::SSLinfo -M Net::SSLhello
+:does not print anything.
-      pp -C -c checkAllCiphers.pl
-      pp -C -c checkAllCiphers.pl -M Net::DNS
-* ActiveState perl with its perlapp
+:Workaround: use  ''--v''  option.
-      perlapp --clean o-saft.pl
+   o-saft.pl +help --v
-      perlapp --clean o-saft.pl -M Net::DNS -M Net::SSLeay -M IO::Socket \
+:or
-                  -M Net::SSLinfo -M Net::SSLhello
+   o-saft.pl +help | more
-      perlapp --clean checkAllCiphers.pl
-      perlapp --clean checkAllCiphers.pl -M Net::DNS
-* perl2exe from IndigoSTar
+=====Character set (like UTF-8) not recognized in some tools=====
-      perl2exe o-saft.pl
-      perl2exe checkAllCiphers.pl
-:For details  on building the executable,  for example how to include
+:Some tools do not diplay all characters properly,  i.e. some versions
-:all required modules, please refer to the documentation of the tool.
+:of podviewer. It is not the obligation of this tool to fix well known
-:* http://search.cpan.org/~rschupp/PAR-Packer-1.030/lib/PAR/Packer.pm
+:bugs in other tools. However, we can offer workarounds.
-:* http://docs.activestate.com/pdk/6.0/PerlApp.html
-:* http://www.indigostar.com
-:Note that  pre-build executables (build by perlapp, perl2exe) cannot
+:Workaround: generate the affected output using ''--std-format=*''  options
-:be provided due to licence problems.
+:For example:
-:Also note that using stand-alone executable have not been tested the
+    o-saft.pl --no-rc --std-format=raw --help=gen-pod
-:same way as the <code>o-saft.pl</code> itself. Use them at your own risk.
+===== **WARNING: on MSWin32 additional option  --v  required, sometimes ...=====
-==== SEE ALSO====
+:On some (mainly Windows-based) systems  this may happen  when calling
+:for example:
+   o-saft.pl --help=FAQ
+:which then may produce:
+   **WARNING: on MSWin32 additional option  --v  required, sometimes ...
+   === reading: ./.o-saft.pl (RC-FILE done) ===
+   === reading: Net/SSLinfo.pm (O-Saft module done) ===
+   **USAGE: no command given
+   # most common usage:
+     o-saft.pl +info   your.tld
+     o-saft.pl +check  your.tld
+     o-saft.pl +cipher your.tld
+   # for more help use:
+     o-saft.pl --help
-* ''openssl(1)'', ''Net::SSLeay(1)'', ''Net::SSLhello'', ''Net::SSLinfo'', ''timeout(1)''
+:Workaround: use full path to perl.exe, for example
-* http://www.openssl.org/docs/apps/ciphers.html
+   C:\Programs\perl\bin\perl.exe o-saft.pl --help=FAQ
-* ''IO::Socket::SSL(1)'', ''IO::Socket::INET(1)''
-==== HACKER's INFO====
+===== Performance Problems=====
-=====Note on SSL versions=====
+:There are various reasons when the program responds slow, or seems to
+:hang. Performance issues are most likely a target-side problem.  Most
+:common reasons are (no specific order):
-:Automatically detecting the supported SSL versions of the underlaying
+:*  a) DNS resolver problems
-:system is a hard job and not always possible. Reasons could be:
+::Try with  ''--no-dns''
-* used perl modules (''Socket::SSL'', ''Net::SSLeay'') does not handle errors
+:*  b) target does not accept connections for https
-:properly. Erros may be:
+::Try with  ''--no-http''
-   invalid SSL_version specified at ... IO/Socket/SSL.pm
-   Use of uninitialized value in subroutine entry at lib/IO/Socket/SSL.pm
+:*  c) target's certificate is not valid
+::Try with  ''--no-cert''
-* the underlaying libssl does not support the version, which then may
+:*  d) target expects that the client provides a client certificate
-:result in segmentation fault
+::No option provided yet ...
-* the underlaying libssl is newer than the perl module and the module
+:*  e) target does not handle Server Name Indication (SNI)
-:has not been reinstalled. This most often happens with  ''Net::SSLeay''
+::Try with  ''--no-sni''
-:This can be detected with (see version numbers for  ''Net::SSLeay''):
-    o-saft.pl +version
-* perl (in particular a used module, see above)  may bail out with a
+:*  f) use of external openssl(1) executable
-:compile error, like
+::Use  ''--no-openssl''
-    Can't locate auto/Net/SSLeay/CTX_v2_new.al in @INC ...
-:We try to detect unsupported versions and disable them automatically,
+:*  g) target does not respond at all and/or blocks
-:a warning like follwoing is shown then:
+::Use  ''--ssl-error''
-    **WARNING: SSL version <code>SSLv2</code> not supported by openssl
+::For a detailed description, please see [[#Connection Problems|Connection Problems]].
-:If problems occour with  SSL versions, following commands and options
+:Other options which may help to get closer to the problem's cause:
-:may help to to get closer to the reason or can be used as workaround:
+:''--trace-time'',  ''--timeout=SEC'',  ''--trace'',  ''--trace-cmd''
-    o-saft.pl +version
-    o-saft.pl +version | grep versions
-    o-saft.pl +version | grep 0x
-    o-saft.pl +protocols your.tld
-    o-saft.pl +protocols your.tld --no-rc
-:If problems occour with  SSL versions, following commands and options
+:Using  ''--trace=time''   should show following times:
-:Checking for SSL version is done at one place in the code, search for
+:* DNS:             1 - 10 sec
-      supported SSL versions
+:* no SNI:          1 - 10 sec
+:* connection test: 1 -  5 sec
+:* need_default:    <5 sec
+:* need_cipher:     1 - 60 sec (+cipher with socket)
+:* need_cipher:     1 - 20 sec (+cipherraw)
+:* prepare checks:  2 - 20 sec
+:* info:            <1 sec
+:* check:           <1 sec
-===== Using private libssl.so and libcrypt.so=====
+==== LIMITATIONS====
-:For all  cryptographic functionality  the libraries  installed on the
+===== Commands=====
-:system will be used. This is in particular perl's  ''Net:SSLeay'' module,
-:the system's  ''libssl.so'' and ''libcrypt.so''  and the ''openssl'' executable.
-:It is possible to provide your own libraries, if the  perl module and
+:Some commands cannot be used together with others, for example:
-:the executable are  linked using  dynamic shared objects  (aka shared
+:''+cipher'',  ''+ciphers'',  ''+list'',  ''+libversion'',  ''+version'',  ''+check'',  ''+help'',
-:library, position independent code).
+:''+protocols'' .
-:The appropriate option is  ''--lib=PATH''  .
-:On most systems these libraries are loaded at startup of the program.
+:''+quick''  should not be used together with other commands, it returns
-:The runtime loader uses a preconfigured list of directories  where to
+:strange output then.
-:find these libraries. Also most systems provide a special environment
-:variable to specify  additional paths  to directories where to search
-:for libraries, for example the  <code>LD_LIBRARY_</code> variable.
-:This is the default environment variable used herein.  If your system
-:uses  another name it must be specified with the  ''--envlibvar=NAME''
-:option, where  <code>NAME</code>  is the name of the environment variable.
-===== Understanding  ''--exe=PATH'', ''--lib=PATH'', ''--openssl=FILE''=====
+:''+protocols''  requires  ''openssl(1)'' with support for <code>-nextprotoneg</code>
+:option. Otherwise the value will be empty.
+===== Options=====
+:The option  ''--port=PORT''  must preceed  ''--host=HOST''  for a target like
+:''HOST:PORT'' .
-:If any of ''--exe=PATH'' or ''--lib=PATH'' is provided, the pragram calls
+:The characters <code>+</code> and <code>=</code> cannot be used for [[#--separator=CHAR|--separator==CHAR]] option.
-:(<code>exec</code>) itself recursively with all given options, except the option
-:itself. The environment variables  <code>LD_LIBRARY_PATH</code>  and <code>PATH</code>  are
-:set before executing as follows:
-:*  prepend  <code>PATH</code>  with all values given with  ''--exe=PATH''
+:Following strings should not be used in any value for options:
-:*  prepend  <code>LD_LIBRARY_PATH</code>  with all values given with  ''--lib=PATH''
+:  <code>+check</code>, <code>+info</code>, <code>+quick</code>, <code>--header</code>
+:as they my trigger the  -''--header''  option unintentional.
-:This is exactly, what ''Cumbersome Approach'' below describes. So these
+:The used ''timeout(1)'' command cannot be defined with a full path like
-:option simply provide a shortcut for that.
+:''openssl(1)''  can with the  ''--openssl=path/to/openssl''.
-:Note that ''--openssl=FILE'' is a full path to the ''openssl'' executable
+:[[#--cfg_text=FILE|--cfg_text=FILE]]  cannot be used to redefine the texts <code>yes</code> and <code>no</code>
-:and will not be changed.  However, if it is a relative path, it might
+:as used in the output for  ''+cipher''  command.
-:be searched for using the previously set  <code>PATH</code>  (see above).
-:Note that  <code>LD_LIBRARY_PATH</code>  is the default.  It can be changed with
+===== Checks (general)=====
-:the  ''--envlibvar=NAME''  option.
-:While  ''--exe''  mainly impacts the openssl executable,  ''--lib''  also
+====== +constraints======
-:impacts o-saft.pl itself, as it loads other shared libraries if found.
-:Bear in mind that  all these options  can affect the behaviour of the
+:This check is only done for the certificate provided by the target.
-:openssl subsystem,  influencing both which  executable is called  and
+:All other certificate in the chain are not checked.
-:which shared libraries will be used.
-:NOTE that no checks are done if the options are set proper. To verify
+:This is currently (2018) a limitation in ''o-saft.pl''.
-:the settings, following commands may be used:
-    o-saft.pl --lib=YOU-PATH --exe=YOUE-EXE +version
-    o-saft.pl --lib=YOU-PATH --exe=YOUE-EXE --v +version
-    o-saft.pl --lib=YOU-PATH --exe=YOUE-EXE --v --v +version
+===== Broken pipe=====
-:Why so many options?  Exactly as described above, these options allow
+:This error message most likely means that the connection to specified
-:the users to tune the behaviour of the tool to their needs.  A common
+:target was not possible (firewall or whatever reason).
-:use case is to enable the use of a separate openssl build independent
-:of the openssl package used by the operating system.  This allows the
-:user fine grained control over openssl's encryption suites  which are
-:compiled/available, without affecting the core system.
-===== Caveats=====
+===== Target Certificate Chain Verification=====
-:Depending on your system and the used modules and executables, it can
+:The systems default capabilities i.e. libssl.so, openssl, are used to
-:be tricky to replace the configured shared libraries with own ones.
+:verify the target's certificate chain.  Unfortunately various systems
-:Reasons are:
+:have implemented different  approaches and rules how identify and how
-:  a) the linked library name contains a version number,
+:to report a successful verification.  As a consequence  this tool can
-:  b) the linked library uses a fixed path,
+:only return the  same information about the chain verification as the
-:  c) the linked library is searched at a predefined path,
+:used underlying tools.  If that information is trustworthy depends on
-:  d) the executable checks the library version when loaded.
+:how trustworthy the tools are.
-:Only the first one a) can be circumvented.  The last one d) can often
+:These limitations apply to following commands:
-:be ignored as it only prints a warning or error message.
-:To circumvent the "name with version number" problem try following:
+:*  ''+verify''
+:*  ''+selfsigned''
-*  1. use ''ldd'' (or a similar tool) to get the names used by ''openssl'':
+:Following commands and options are useful to get more information:
-:  ldd /usr/bin/openssl
+:*  ''+chain_verify'', ''+verify'', ''+error_verify'', ''+chain'', ''+s_client''
+:*  ''--ca-file'', ''--ca-path'', ''--ca-depth''
-:which returns something like:
+===== User Provided Files=====
-:  libssl.so.0.9.8 => /lib/libssl.so.0.9.8 (0x00007f940cb6d000)
+:Please note that there cannot be any guarantee that the code provided
-:  libcrypto.so.0.9.8 => /lib/libcrypto.so.0.9.8 (0x00007f940c7de000)
+:in the   [[#DEBUG-FILE|DEBUG-FILE]] ''o-saft-usr.pm''  or   [[#USER-FILE|USER-FILE]]  ''o-saft-usr.pm''
-:  libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007f940c5d9000)
+:will work flawless. Obviously this is the user's responsibility.
-:  libz.so.1 => /lib/x86_64-linux-gnu/libz.so.1 (0x00007f940c3c1000)
-:  libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f940c02c000)
-:  /lib64/ld-linux-x86-64.so.2 (0x00007f940cdea000)
-:Here only the first two libraries are important.  Both,  libcrypto.so
+===== Problems and Errors=====
-:and libssl.so  need to be version "0.9.8" (in this example).
-*  2. create a directory for your libraries, i.e.:
+:Checking the target for supported ciphers may return that a cipher is
+:not supported by the server  misleadingly.  Reason is most likely  an
+:improper timeout for the connection. See  ''--timeout=SEC''  option.
-:  mkdir /tmp/dada
+:If the specified targets accepts connections but does not speak  SSL,
+:the connection will be closed after the system's TCP/IP-timeout. This
+:script will hang (about 2-3 minutes).
-*  3. place your libraries there, assuming they are:
+:If reverse DNS lookup fails, an error message is returned as hostname,
+:like:  <code><<gethostbyaddr() failed</code>>>.
+:Workaround to get rid of this message: use  ''--no-dns''  option.
-:  /tmp/dada/libssl.so.1.42
+:All checks for EV are solely based on the information provided by the
-:  /tmp/dada/libcrypto.so.1.42
+:certificate.
-*  4. create symbolic links in that directory:
+:Some versions of openssl (< 1.x) may not support all required options
+:which results in various error messages or --more worse--  may not be
+:visibale at all. Available functionalitity of openssl will be checked
+:for right at the beginning Proper Warnings and hints are printed.
+:Following table shows the openssl option and how to disbale it within
+:o-saft:
-:  ln -s libssl.so.1.42    libssl.so.0.9.8
+:* -nextprotoneg       ''--no-nextprotoneg''
-:  ln -s libcrypto.so.1.42 libcrypto.so.0.9.8
+:* -reconnect          ''--no-reconnect''
+:* -tlsextdebug        ''--no-tlsextdebug''
+:* -alpn               ''--no-alpn''
-*  5. test program with following option:
+===== Connection Problems=====
-    o-saft.pl +libversion --lib=/tmp/dada
+:Sometimes the connection cannot be established. This may have various
-    o-saft.pl +list --v   --lib=/tmp/dada
+:reasons.  Unfortunaly this script seems to hang then.  In  particular
+:when checking for ciphers with  ''+cipher''  or  ''+cipherall'' . The reason
+:is most likely that the server does not respond to the TCP/IP request
+:and hence the script closes the connection after the configured time-
+:out (see  ''--timeout=SEC''  option).
-:  or:
+:Continous connection attempts  can be inhibited with the  ''--ssl-error''
+:option, which is set by default. Avoiding further connections results
+:in a loss of information and consequentely leading to wrong checks.
-    o-saft.pl +libversion --lib=/tmp/dada -exe=/path/to-openssl
+:It is a trade-off to wait for all information done accurately,  or to
-     o-saft.pl +list --v   --lib=/tmp/dada -exe=/path/to-openssl
+:get the results quickly. The logic to stop connecting for ''--ssl-error''
+:can be controlled with following additional options:
+:* --ssl-error-max=CNT     - max. continous errors
+:* --ssl-error-timeout=SEC - timeout when to treat a failure as error
+:* --ssl-error-total=CNT   - max. amount of errors
-*  6. start program with your options, i.e.:
+:This means that no more connections are made when more than
+:* --ssl-error-max errors occour sequentialy
+:or
+:* --ssl-error-total errors occoured
-    o-saft.pl --lib=/tmp/dada +ciphers
+:Examples:
+:* <code>--ssl-error-max=3</code>
+:* <code>--ssl-error-timeout=6</code>
+:* <code>--ssl-error-total=6</code>
+:no more connections are made if for example  any sequence of timeouts
+:occour:
+5 2 2                   - --ssl-error-max matches
+1 3 0 0 0 4 1 2 2 2     - --ssl-error-max matches
+5 0 2 0 2 2 0 2 0 2     - --ssl-error-total matches
-:This works if ''openssl(1)'' uses the same shared libraries as
+:This allows to fine-tune the condition when to stop connecting to the
-:''Net:SSLeay(1)'', which most likely is the case.
+:target. For example, continous but not consecutive timeouts may indi-
+:cate a bad or instable network connection, but not that the target to
+:be connected blocks. In such a case sequence of timeouts like follows
+:may be observed (assuming <code>--ssl-error-max=3</code>):
+5 1 2 2 2 4 2 3 2 3 3 3 2
+        ^                 ^____ stop for --ssl-error-timeout=3
+        |______________________ stop for --ssl-error-timeout=2
-:It's tested with Unix/Linux only. It may work on other platforms also
+:On normal (even slow) network connections  dozens of  connections per
-:if they support such an environment variable and the installed
+:second are usual, hence the timeout is always  0 or 1.  Based on that
-:''Net::SSLeay(1)''  and ''openssl(1)''  are linked using dynamic shared
+:experience  ''--ssl-error''  is enabled and set with defaults as follows:
-:objects.
+:* <code>--ssl-error-max=5</code>
+:* <code>--ssl-error-timeout=1</code>
+:* <code>--ssl-error-total=10</code>
-:Depending on  compile time settings  and/or  the location of the used
+===== Poor Systems=====
-:tool or lib, a warning like following may occur:
-   WARNING: can't open config file: /path/to/openssl/ssl/openssl.cnf
+:Use of  ''openssl(1)'' is disabled by default on Windows due to various
+:performance problems. It needs to be enabled with ''--openssl'' option.
-:This warning can be ignored, usually as  ''req''  or  ''ca''  sub commands of
+:On Windows the usage of  <code>openssl s_client</code> needs to be enabled using
-:openssl is not used here.
+:[[#--s_client|--s_client]] option.
-:To fix the problem, either use  ''--openssl-cnf=FILE''  option or set the
-:the environment variable OPENSSL_CONF properly.
-====== Cumbersome Approach======
+:On Windows it's a pain to specify the path for [[#--openssl=TOO|--openssl=TOOL]] option.
+:Variants are:
-:A more cumbersome approach to call  this program is to set  following
+:*  --openssl=/path/to/openssl.exe
-:environment variables in your shell:
+:*  --openssl=X:/path/to/openssl.exe
+:*  --openssl=\path\to\openssl.exe
+:*  --openssl=X:\path\to\openssl.exe
+:*  --openssl=\\path\\to\\openssl.exe
+:*  --openssl=X:\\path\\to\\openssl.exe
-   PATH=/tmp/dada-1.42/apps:$PATH
+:You have to fiddle around to find the proper one.
-   LD_LIBRARY_PATH=/tmp/dada-1.42
-====== Windows Caveats======
+===== Debug and Trace Output=====
-:I.g. the used libraries on Windows are ''libeay32.dll'' and ''ssleay32.dll''.
+: When both  [[#--trace-key|--trace-key]]  and  [[#--trace-cmd|--trace-cmd]]  options are used, output is
+: mixed, obviously. Hint: output for [[#--trace-cmd|--trace-cmd]] always contains "CMD".
-:Windows also supports the <code>LD_LIBRARY_PATH</code> environment variable. If it
+: Any  ''--trace*''  option implies  [[#--trace-time|--trace-time]] .
-:does not work as expected with that variable, it might be possible to
-:place the libs in the same directory as the  corresponding executable
-:(which is found by the <code>PATH</code> environment variable).
-===== Using CGI mode=====
+==== DEPENDENCIES====
-:This script can be used as  CGI application. Output is the same as in
+:All Perl modules and all  private moduels and files  will be searched
-:common CLI mode, using  'Content-Type:text/plain'.  Keep in mind that
+:for using paths available in the  <code>@INC</code>  variable.  <code>@INC</code>  will
-:the used modules like  ''Net::SSLeay''  will write some debug messages
+:be prepended by following paths:
-:on STDERR instead STDOUT. Therefore multiple  ''--v'' and/or  ''--trace''
-:options behave slightly different.
-:No additional external files like [[#RC-FILE|RC-FILE]] or  [[#DEBUG-FILE|DEBUG-FILE]] are read
+:*   .
-:in CGI mode; they are silently ignored.
+:*   ./lib
-:Some options are disabled in CGI mode  because they are dangerous  or
+:*   INSTALL_PATH
-:don't make any sense.
+:*   INSTALL_PATH/lib
-====== WARNING======
+:Where  <code>INSTALL_PATH</code>  is the path where the tool is installed.
+:To see which files have been included use:
-:  There are  no  input data validation checks implemented herein. All
+    o-saft.pl +version --v --user
-:  input data is url-decoded once and then used verbatim.
-:  More advanced checks must be done outside before calling this tool.
-:It's not recommended to run this tool in CGI mode.
+===== Perl Modules=====
-:You have been warned!
-===== Using user specified code=====
+*  ''IO::Socket::SSL(3pm)''
+*  ''IO::Socket::INET(3pm)''
+*  ''Net::SSLeay(3pm)''
+*  ''Net::SSLinfo''
+*  ''Net::SSLhello''
-:There are some functions called within the program flow, which can be
+:Perl modules loaded and used for some options only:
-:filled with any perl code.  Empty stubs of the functions are prepared
-:in  ''o-saft-usr.pm''.  See also  [[#USER-FILE|USER-FILE]].
-==== DEBUG====
+* ''Net::DNS(3pm)''
+* ''Time::Local(3pm)''
-===== Debugging, Tracing=====
+===== Additional Files used if requested=====
-:Following  options and commands  are useful for hunting problems with
+*  ''.o-saft.pl''
-:SSL connections and/or this tool. Note that some options can be given
+*  ''o-saft-dbx.pm''
-:multiple times to increase amount of listed information. Also keep in
+*  ''o-saft-man.pm''
-:mind that it's best to specify  ''--v''  as very first argument.
+*  ''o-saft-usr.pm''
+*  ''o-saft-README''
+*  ''o-saft-docker''
-:Note that the file  ''o-saft-dbx.pm''  is required, if any  ''--trace*''
+==== INSTALLATION====
-:or  ''--v''  option is used.
-====== Commands======
+:The tool can be installed in any path. It just requres the modules as
+:described in  [[#DEPENDENCIES|DEPENDENCIES]]  above. However, it's recommended that the
+:modules ''Net::SSLhello'' and ''Net::SSLinfo'' are found in the directory
+:<code>./Net/</code>  where  <code>o-saft.pl</code>  is installed.
-*  ''+dump''
+:For security reasons, most modern libraries disabled or even removed
-*  ''+libversion''
+:insecure or "dirty" functionality. As this tool's purpose is to find
-*  ''+s_client''
+:such insecure settings, functions, etc., it needs these dirty things
-*  ''+todo''
+:enabled. What we need is (incomplete list):
-*  ''+version''
-====== Options======
+:* insecure protocols like SSLv2, SSLv3
+:* more more ciphers enabled, like NULL-MD5, AECDH-NULL-SHA, etc.
+:* some SSL extensions and options
-*  ''--v''
+:Therefore we recommend to compile and install at least following:
-*  ''--v--''
-*  ''--trace''
-*  ''--trace-arg''
-*  ''--trace-cmd''
-*  ''--trace-key''
-:Empty or undefined strings are written as  <code><<undefined>></code>  in texts.
+:* openssl  with SSLv2, SSLv3 and more ciphers enabled
-:Some parameters, in particular those of  HTTP responses,  are written
+:* Net::SSLeay  compiled with openssl version as described before.
-:as  <code><<response>></code>.  Long parameter lists are abbreviated with <code>...</code>.
-====== Output======
+:Please read the  [[#SECURITY|SECURITY]]  section first before following the install
+:instructions below.
-:When using  ''--v''  and/or  ''--trace''  options, additional output will
+=====OpenSSL=====
-:be prefixed with a  <code>#</code>  (mainly as first, left-most character.
-:Following formats are used:
-:*  #<space>
+:Currently (since 18.06.18) it is recommend to build openssl using
+    contrib/install_openssl.sh
-:    Addition text for verbosity (''--v'' options).
+:Other possibilities are:
+:* compiling openssl using following sources
+::  [https://github.com/PeterMosmans/openssl/ https://github.com/PeterMosmans/openssl/]
+::  see  [[#Example: Compile OpenSSL|Example: Compile OpenSSL]],
+:* use any of the precomiled versions provided by https://testssl.sh/
-:*  #[variable name]<TAB>
+:The sources are available at
+:* [https://github.com/PeterMosmans/openssl/archive/1.0.2-chacha.zip https://github.com/PeterMosmans/openssl/archive/1.0.2-chacha.zip]
+:A precomiled static versions are available at
+:* [https://github.com/drwetter/testssl.sh/tree/master/bin https://github.com/drwetter/testssl.sh/tree/master/bin]
-:    Internal variable name (''--trace-key'' options).
+:For all following installation examples we assume:
+:* openssl-1.0.2-chacha.zip or openssl-1.0.2d.tar.gz
+:* /usr/local as bae installation directory
+:* a bourne shell (sh) compatible shell
-:*  #o-saft.pl::
+=====Example: Precompiled OpenSSL=====
-:*  #Net::SSLinfo::
-:    Trace information for ''--trace''  options.
+:Simply download the tarball or zip file for your platform, unpack it,
+:and install (copy) the binaries into a directory of your choice.
-:*  #{
+=====Example: Compile OpenSSL=====
-:    Trace information from  <code>NET::SSLinfo</code>  for  ''--trace''  options.
+:OpenSSL can be used from [http://openssl.org/ http://openssl.org/] or, as recommended, from
-:    These are data lines in the format:   #{ variable name : value #}
+:[https://github.com/PeterMosmans/openssl/ https://github.com/PeterMosmans/openssl/] .
-:    Note that  <code>value</code>  here can span multiple lines and ends with #}
-==== EXAMPLES====
+:'''OpenSSL-chacha'''
+:Compiling and installing the later is as simple as:
+    unzip openssl-1.0.2-chacha.zip
+    cd openssl-1.0.2-chacha
+    ./config --shared -Wl,-rpath=/usr/local/lib
+    make
+    make test
+    make install
-:($0 in all following examples is the name of the tool)
+:which will install openssl, libssl.so, libcrypto.so  and some include
+:files as well as the include files in  /usr/local/ .
+:The shared version of the libraries are necessary for  Net::SSLeay.
-===== General=====
+:'''OpenSSL.org'''
+:Building openssl from the offical  openssl.org  sources requires some
+:patching before compiling and installing the libraries and binaries.
-    o-saft.pl +cipher some.tld
+:Example with openssl-1.0.2d:
-    o-saft.pl +info   some.tld
-    o-saft.pl +check  some.tld
-    o-saft.pl +quick  some.tld
-    o-saft.pl +help=commands
-    o-saft.pl +list
-    o-saft.pl +list --v
-    o-saft.pl +certificate  some.tld
-    o-saft.pl +fingerprint  some.tld 444
-    o-saft.pl +after +dates some.tld
-===== Some Specials=====
+   echo == unpack tarball
+   tar xf openssl-1.0.2d.tar.gz
+   cd openssl-1.0.2d
+   echo == backup files to be modified
+   cp ssl/s2_lib.c{,.bak}
+   cp ssl/s3_lib.c{,.bak}
+   cp ssl/ssl3.h{,.bak}
+   cp ssl/tls1.h{,.bak}
-*  Get an idea how messages look like
+   echo == patch files
+   vi ssl/tls1.h         +/TLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES/
+            # define TLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES  1
+   vi ssl/ssl3.h ssl/s{2,3}_lib.c   +"/# *if 0/"
+            #==> remove all   # if 0  and corresponding  #endif
+            #    except if lines contain:
+            #        _FZA
+            #        /* Fortezza ciphersuite from SSL 3.0
+            #        /* Do not set the compare functions,
+            #        if (s->shutdown & SSL_SEND_SHUTDOWN)
-    o-saft.pl +check --cipher=RC4 some.tld
+   echo == configure with static libraries
+   echo omitt the zlib options if zlib-1g-dev is not installed
+   echo omitt the krb5 options if no kerberos libraries available
+   ./config --prefix=/usr/local --openssldir=/usr/local/ssl \
+       enable-zlib zlib zlib-dynamic enable-ssl2 \
+       enable-krb5 --with-krb5-flavor=MIT \
+       enable-mdc2 enable-md2  enable-rc5  enable-rc2 \
+       enable-cms  enable-ec   enable-ec2m enable-ecdh enable-ecdsa \
+       enable-gost enable-seed enable-idea enable-camellia \
+       enable-rfc3779 enable-ec_nistp_64_gcc_128 \
+       experimental-jpake -fPIC \
+       -DTEMP_GOST_TLS -DTLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES \
+       shared
-*  Check for Server Name Indication (SNI) usage only
+   echo == make binaries and libraries
+   make depend
+   make
+   make test
+   make install
-    o-saft.pl +sni some.tld
+   echo == if you want static binaries and libraries
+   make clean
-*  Check for SNI and print certificate's subject and altname
+   echo same ./config as before but without shared option
+   ./config --prefix=/usr/local --openssldir=/usr/local/ssl \
-    o-saft.pl +sni +cn +altname some.tld
+       enable-zlib zlib zlib-dynamic enable-ssl2 \
+       enable-krb5 --with-krb5-flavor=MIT \
-*  Check for all SNI, certificate's subject and altname issues
+       enable-mdc2 enable-md2 enable-rc5 enable-rc2 \
+       enable-cms  enable-ec   enable-ec2m enable-ecdh enable-ecdsa \
-    o-saft.pl +sni_check some.tld
+       enable-gost enable-seed enable-idea enable-camellia \
+       enable-rfc3779 enable-ec_nistp_64_gcc_128 \
+       experimental-jpake -fPIC \
+       -DTEMP_GOST_TLS -DTLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES
+   make depend
+   make
+   make test
+   echo next make will overwrite the previously installed dynamic
+   echo shared openssl binary with the static openssl binary
+   make install
-*  Only print supported ciphers
+=====Example: Compile Net::SSLeay=====
-    o-saft.pl +cipher --enabled some.tld
+:To enable support for ancient protocol versions,  ''Net::SSLeay'' must be
+:compiled manually after patching 'SSLeay.xs' (see below).
+:Reason is, that  ''Net::SSLeay''  enables some functionality for  SSL/TLS
+:according the identified openssl version. There is, currently (2015),
+:no possibility to enable this functionality  by passing options on to
+:the configuration script <code>perl Makefile.PL</code>.
-*  Only print unsupported ciphers
+    echo == unpack tarball
+    tar xf Net-SSLeay-1.72.tar.gz
+    cd Net-SSLeay-1.72
-     o-saft.pl +cipher --disabled some.tld
+     echo == patch files
+    echo "edit SSLeay.xs and change some #if as described below"
+    env OPENSSL_PREFIX=/usr/local perl Makefile.PL PREFIX=/usr/local \
+          INC=/usr/local/include  DEFINE=-DOPENSSL_BUILD_UNSAFE=1
+    make
+    make install
+    cd /tmp && o-saft.pl +version
-*  Test for a specific ciphers
+:SSLeay.xs needs to be changed as follows:
+* search for
-     o-saft.pl +cipher --cipher=ADH-AES256-SHA some.tld
+    #ifndef OPENSSL_NO_SSL2
+     #if OPENSSL_VERSION_NUMBER < 0x10000000L
-* Test all ciphers, even if not supported by local SSL implementation
-     o-saft.pl +cipherall some.tld
+    const SSL_METHOD *
-     o-saft.pl +cipherall some.tld --range=full
+    SSLv2_method()
-     checkAllCiphers.pl example.tld --range=full --v
+    #endif
+    #endif
+    #ifndef OPENSSL_NO_SSL3
+    #if OPENSSL_VERSION_NUMBER < 0x10002000L
+    const SSL_METHOD *
+    SSLv3_method()
+    #endif
+    #endif
+* and replace by
+     const SSL_METHOD *
+    SSLv2_method()
+     const SSL_METHOD *
+     SSLv3_method()
-* Show supported (enabled) ciphers with their DH parameters:
+:Note that  ''Net::SSLeay''  will be installed in <code>/usr/local/</code> then. This
-    o-saft.pl +cipher-dh some.tld
+:can be adapted to your needs by passing another path to the  <code> PREFIX</code>
+:and  <code> DESTDIR</code>   parameter.
-*  Test using a private libssl.so, libcrypto.so and openssl
+:Following command can be used to check  which methods are avilable in
+:Net::SSLeay, hence above patches can be verified:
+     perl -MLNet::SSLinfo -le print Net::SSLinfo::ssleay_test();
-    o-saft.pl +cipher --lib=/foo/bar-1.42 --exe=/foo/bar-1.42/apps some.tld
+=====Testing OpenSSL=====
-*  Test using a private openssl
+:After installation as descibed above finished, openssl may be tested:
-     o-saft.pl +cipher --openssl=/foo/bar-1.42/openssl some.tld
+     echo already installed openssl (found with PATH environment)
+    openssl ciphers -v
+    openssl ciphers -V -ssl2
+    openssl ciphers -V -ssl3
+    openssl ciphers -V ALL
+    openssl ciphers -V ALL:COMPLEMENTOFALL
+    openssl ciphers -V ALL:eNULL:EXP
-*  Test using a private openssl also for testing supported ciphers
+    echo own compiled and installed openssl
+    /usr/local/openssl ciphers -v
+    /usr/local/openssl ciphers -V -ssl2
+    /usr/local/openssl ciphers -V -ssl3
+    /usr/local/openssl ciphers -V ALL
+    /usr/local/openssl ciphers -V ALL:COMPLEMENTOFALL
+    /usr/local/openssl ciphers -V ALL:eNULL:EXP
-    o-saft.pl +cipher --openssl=/foo/bar-1.42/openssl --force-openssl some.tld
+The difference should be obvious.
+Note, the commands using  <code>ALL:COMPLEMENTOFALL</code>  and  <code>ALL:eNULL:EXP</code>
+should return the same result.
-*  Show current score settings
+=====Testing Net::SSLeay=====
-    o-saft.pl --help=score
+:As we want to test the separately installed  ''Net::SSLeay'',  it is best
+:to do it with  <code>o-saft.pl</code>  itself:
-*  Change a single score setting
+    o-saft.pl +version
-    o-saft.pl --cfg_score=http_https=42   +check some.tld
+:we should see a line similar to follwong at the end of the output:
-*  Use your private score settings from a file
+    Net::SSLeay   1.72  /usr/local/lib/x86_64-linux-gnu/perl/5.20.2/Net/SSLeay.pm
-    o-saft.pl --help=score > magic.score
+:Now check for supported (known) ciphers:
-:    # edit as needed: magic.score
-    o-saft.pl --cfg_score    magic.score  +check some.tld
-*  Use your private texts in output
+    o-saft.pl ciphers -V
-    o-saft.pl +check some.tld --cfg_text=desc=<code>my special description</code>
+:we should see lines similar to those of the last  <code>/usr/local/openssl</code>
+:call. However, it should contain more cipher lines.
-*  Use your private texts from RC-FILE
+=====Stand-alone Executable=====
+:Some people asked for a stand-alone executable (mainly for Windows).
+:Even Perl is a scripting language there are situations where a stand-
+:alone executable would be nice, for example if the installed perl and
+:its libraries are outdated, or if perl is missing at all.
+:Currently (2016) there are following possibilities to generate such a
+:stand-alone executable:
+* perl with PAR::Packer module
+      pp -C -c o-saft.pl
+      pp -C -c o-saft.pl -M Net::DNS -M Net::SSLeay -M IO::Socket \
+                         -M Net::SSLinfo -M Net::SSLhello -M osaft
+      pp -C -c checkAllCiphers.pl
+      pp -C -c checkAllCiphers.pl -M Net::DNS
-    o-saft.pl --help=cfg_text >> .o-saft.pl
+* ActiveState perl with its perlapp
+      perlapp --clean o-saft.pl
+      perlapp --clean o-saft.pl -M Net::DNS -M Net::SSLeay -M IO::Socket \
+                  -M Net::SSLinfo -M Net::SSLhello -M osaft
+      perlapp --clean checkAllCiphers.pl
+      perlapp --clean checkAllCiphers.pl -M Net::DNS -M osaft
-:    # edit as needed:     .o-saft.pl
+* perl2exe from IndigoSTar
+      perl2exe o-saft.pl
+      perl2exe checkAllCiphers.pl
-    o-saft.pl +check some.tld
+:For details  on building the executable,  for example how to include
+:all required modules, please refer to the documentation of the tool.
+:* http://search.cpan.org/~rschupp/PAR-Packer-1.030/lib/PAR/Packer.pm
+:* http://docs.activestate.com/pdk/6.0/PerlApp.html
+:* http://www.indigostar.com
-* Use your private hint texts in output
+:Note that  pre-build executables (build by perlapp, perl2exe) cannot
-    o-saft.pl +check some.tld --cfg-hint=renegotiation="my special hint text"
+:be provided due to licence problems.
+:Also note that using stand-alone executable have not been tested the
+:same way as the <code>o-saft.pl</code> itself. Use them at your own risk.
-* Get the certificate's Common Name for a bunch of servers:
+==== DOCKER====
-    o-saft.pl +cn example.tld some.tld other.tld
+:The tool can be used inside a Docker image. To start  ''o-saft.pl''  inside
-    o-saft.pl +cn example.tld some.tld other.tld --showhost --no-header
+:the Docker image, use following:
-*  Generate simple parsable output
+   o-saft-docker +info some.tld
+:or
+   docker run --rm -it owasp/o-saft +info some.tld
+:For more details, please refer to:
+   o-saft-docker -help
+   o-saft-docker usage
+====BUILD DOCKER IMAGE====
+:The Docker image can be installed as follows:
+   docker pull owasp/o-saft
+:The image can also easily be build from the Dockerfile (which is part
+:of the distribution) as follows:
+   o-saft-docker build
+:To build the image from the Dockerfile with docker commands, see:
+   o-saft-docker -n build
+:For more details, please refer to:
+   o-saft-docker -help
+==== SEE ALSO====
+* ''openssl(1)'', ''Net::SSLeay(3pm)'', ''Net::SSLhello'', ''Net::SSLinfo'', ''timeout(1)''
+* http://www.openssl.org/docs/apps/ciphers.html
+* ''IO::Socket::SSL(3pm)'', ''IO::Socket::INET(3pm)''
+* ''o-saft-docker'', ''o-saft-docker-dev'', ''Dockerfile'', ''docker''
+==== HACKER's INFO====
+=====Note on SSL versions=====
+:Automatically detecting the supported SSL versions of the underlaying
+:system is a hard job and not always possible. Reasons could be:
+* used Perl modules (''Socket::SSL'', ''Net::SSLeay'') does not handle errors
+:properly. Erros may be:
+   invalid SSL_version specified at ... IO/Socket/SSL.pm
+   Use of uninitialized value in subroutine entry at lib/IO/Socket/SSL.pm
+* the underlaying libssl does not support the version, which then may
+:result in segmentation fault
+* the underlaying libssl is newer than the Perl module and the module
+:has not been reinstalled. This most often happens with  ''Net::SSLeay''
+:This can be detected with (see version numbers for  ''Net::SSLeay''):
+    o-saft.pl +version
+* perl (in particular a used module, see above)  may bail out with a
+:compile error, like
+    Can't locate auto/Net/SSLeay/CTX_v2_new.al in @INC ...
+:We try to detect unsupported versions and disable them automatically,
+:a warning like follwoing is shown then:
+    **WARNING: SSL version <code>SSLv2</code> not supported by openssl
+:If problems occour with  SSL versions, following commands and options
+:may help to to get closer to the reason or can be used as workaround:
+    o-saft.pl +version
+    o-saft.pl +version | grep versions
+    o-saft.pl +version | grep 0x
+    o-saft.pl +protocols your.tld
+    o-saft.pl +protocols your.tld --no-rc
+:If problems occour with  SSL versions, following commands and options
+:Checking for SSL version is done at one place in the code, search for
+     supported SSL versions
+===== Using private libssl.so and libcrypt.so=====
+:For all  cryptographic functionality  the libraries  installed on the
+:system will be used. This is in particular Perl's  ''Net:SSLeay'' module,
+:the system's  ''libssl.so'' and ''libcrypt.so''  and the ''openssl'' executable.
+:It is possible to provide your own libraries, if the  P module and
+:the executable are  linked using  dynamic shared objects  (aka shared
+:library, position independent code).
+:The appropriate option is  ''--lib=PATH''  .
+:On most systems these libraries are loaded at startup of the program.
+:The runtime loader uses a preconfigured list of directories  where to
+:find these libraries. Also most systems provide a special environment
+:variable to specify  additional paths  to directories where to search
+:for libraries, for example the  <code>LD_LIBRARY_</code> variable.
+:This is the default environment variable used herein.  If your system
+:uses  another name it must be specified with the  ''--envlibvar=NAME''
+:option, where  <code>NAME</code>  is the name of the environment variable.
+===== Understanding  ''--exe=PATH'', ''--lib=PATH'', ''--openssl=FILE''=====
+:If any of [[#--exe=PATH|--exe=PATH]] or [[#--lib=PATH|--lib=PATH]] is provided, the pragram calls
+:(<code>exec</code>) itself recursively with all given options, except the option
+:itself. The environment variables  <code>LD_LIBRARY_PATH</code>  and <code>PATH</code>  are
+:set before executing as follows:
+:*  prepend  <code>PATH</code>  with all values given with  [[#--exe=PATH|--exe=PATH]]
+:*  prepend  <code>LD_LIBRARY_PATH</code>  with all values given with  [[#--lib=PATH|--lib=PATH]]
+:This is exactly, what [[#Cumbersome Approach|Cumbersome Approach]] below describes. So these
+:option simply provide a shortcut for that.
+:Note that [[#--openssl=TOOL|--openssl=TOOL]] is a full path to the ''openssl'' executable
+:and will not be changed.  However, if it is a relative path, it might
+:be searched for using the previously set  <code>PATH</code>  (see above).
+:Note that  <code>LD_LIBRARY_PATH</code>  is the default.  It can be changed with
+:the  [[#--envlibvar=NAME|--envlibvar=NAME]]  option.
+:While  ''--exe''  mainly impacts the openssl executable,  ''--lib''  also
+:impacts o-saft.pl itself, as it loads other shared libraries if found.
+:Bear in mind that  all these options  can affect the behaviour of the
+:openssl subsystem,  influencing both which  executable is called  and
+:which shared libraries will be used.
+:NOTE that no checks are done if the options are set proper. To verify
+:the settings, following commands may be used:
+    o-saft.pl --lib=YOU-PATH --exe=YOUE-EXE +version
+    o-saft.pl --lib=YOU-PATH --exe=YOUE-EXE --v +version
+    o-saft.pl --lib=YOU-PATH --exe=YOUE-EXE --v --v +version
+:Why so many options?  Exactly as described above, these options allow
+:the users to tune the behaviour of the tool to their needs.  A common
+:use case is to enable the use of a separate openssl build independent
+:of the openssl package used by the operating system.  This allows the
+:user fine grained control over openssl's encryption suites  which are
+:compiled/available, without affecting the core system.
+===== Caveats=====
+:Depending on your system and the used modules and executables, it can
+:be tricky to replace the configured shared libraries with own ones.
+:Reasons are:
+:  a) the linked library name contains a version number,
+:  b) the linked library uses a fixed path,
+:  c) the linked library is searched at a predefined path,
+:  d) the executable checks the library version when loaded.
+:Only the first one a) can be circumvented.  The last one d) can often
+:be ignored as it only prints a warning or error message.
+:To circumvent the "name with version number" problem try following:
+*  1. use ''ldd'' (or a similar tool) to get the names used by ''openssl'':
+:  ldd /usr/bin/openssl
+:which returns something like:
+:  libssl.so.0.9.8 => /lib/libssl.so.0.9.8 (0x00007f940cb6d000)
+:  libcrypto.so.0.9.8 => /lib/libcrypto.so.0.9.8 (0x00007f940c7de000)
+:  libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007f940c5d9000)
+:  libz.so.1 => /lib/x86_64-linux-gnu/libz.so.1 (0x00007f940c3c1000)
+:  libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f940c02c000)
+:  /lib64/ld-linux-x86-64.so.2 (0x00007f940cdea000)
+:Here only the first two libraries are important.  Both,  libcrypto.so
+:and libssl.so  need to be version "0.9.8" (in this example).
+*  2. create a directory for your libraries, i.e.:
+:  mkdir /tmp/dada
+*  3. place your libraries there, assuming they are:
+:  /tmp/dada/libssl.so.1.42
+:  /tmp/dada/libcrypto.so.1.42
+*  4. create symbolic links in that directory:
+:  ln -s libssl.so.1.42    libssl.so.0.9.8
+:  ln -s libcrypto.so.1.42 libcrypto.so.0.9.8
+*  5. test program with following option:
+    o-saft.pl +libversion --lib=/tmp/dada
+    o-saft.pl +list --v   --lib=/tmp/dada
+:  or:
+    o-saft.pl +libversion --lib=/tmp/dada -exe=/path/to-openssl
+    o-saft.pl +list --v   --lib=/tmp/dada -exe=/path/to-openssl
+*  6. start program with your options, i.e.:
+    o-saft.pl --lib=/tmp/dada +ciphers
+:This works if ''openssl(1)'' uses the same shared libraries as
+:''Net:SSLeay(3pm)'', which most likely is the case.
+:It's tested with Unix/Linux only. It may work on other platforms also
+:if they support such an environment variable and the installed
+:''Net::SSLeay(3pm)''  and ''openssl(1)''  are linked using dynamic shared
+:objects.
+:Depending on  compile time settings  and/or  the location of the used
+:tool or lib, a warning like following may occur:
+   WARNING: can't open config file: /path/to/openssl/ssl/openssl.cnf
+:This warning can be ignored, usually as  ''req''  or  ''ca''  sub commands of
+:openssl is not used here.
+:To fix the problem, either use  ''--openssl-cnf=FILE''  option or set the
+:the environment variable OPENSSL_CONF properly.
+====== Cumbersome Approach======
+:A more cumbersome approach to call  this program is to set  following
+:environment variables in your shell:
+   PATH=/tmp/dada-1.42/apps:$PATH
+   LD_LIBRARY_PATH=/tmp/dada-1.42
+====== Windows Caveats======
+:I.g. the used libraries on Windows are ''libeay32.dll'' and ''ssleay32.dll''.
+:Windows also supports the <code>LD_LIBRARY_PATH</code> environment variable. If it
+:does not work as expected with that variable, it might be possible to
+:place the libs in the same directory as the  corresponding executable
+:(which is found by the <code>PATH</code> environment variable).
+===== Using CGI mode=====
+:This script can be used as  CGI application. Output is the same as in
+:common CLI mode, using  'Content-Type:text/plain'.  Keep in mind that
+:the used modules like  ''Net::SSLeay''  will write some debug messages
+:on STDERR instead STDOUT. Therefore multiple  ''--v'' and/or  ''--trace''
+:options behave slightly different.
+:No additional external files like [[#RC-FILE|RC-FILE]] or  [[#DEBUG-FILE|DEBUG-FILE]] are read
+:in CGI mode; they are silently ignored.
+:Some options are disabled in CGI mode  because they are dangerous  or
+:don't make any sense.
+====== WARNING======
+:  There are  no  input data validation checks implemented herein. All
+:  input data is url-decoded once and then used verbatim.
+:  More advanced checks must be done outside before calling this tool.
+:It's not recommended to run this tool in CGI mode.
+:You have been warned!
+===== Using user specified code=====
+:There are some functions called within the program flow, which can be
+:filled with any Perl code.  Empty stubs of the functions are prepared
+:in  ''o-saft-usr.pm''.  See also  [[#USER-FILE|USER-FILE]].
+==== DEBUG====
+===== Debugging, Tracing=====
+:Following  options and commands  are useful for hunting problems with
+:SSL connections and/or this tool. Note that some options can be given
+:multiple times to increase amount of listed information. Also keep in
+:mind that it's best to specify  ''--v''  as very first argument.
+:Note that the file  ''o-saft-dbx.pm''  is required, if any  ''--trace*''
+:or  ''--v''  option is used.
+====== Commands======
+*  ''+dump''
+*  ''+libversion''
+*  ''+s_client''
+*  ''+todo''
+*  ''+version''
+====== Options======
+*  ''--v''
+*  ''--v--''
+*  ''--trace''
+*  ''--trace-arg''
+*  ''--trace-cmd''
+*  ''--trace-key''
+:Empty or undefined strings are written as  <code><<undefined>></code>  in texts.
+:Some parameters, in particular those of  HTTP responses,  are written
+:as  <code><<response>></code>.  Long parameter lists are abbreviated with <code>...</code>.
+====== Output======
+:When using  ''--v''  and/or  ''--trace''  options, additional output will
+:be prefixed with a  <code>#</code>  (mainly as first, left-most character.
+:Following formats are used:
+:*  #[space]
+:    Addition text for verbosity (''--v'' options).
+:*  #[variable name][TAB]
+:    Internal variable name (''--trace-key'' options).
+:*  #o-saft.pl::
+:*  #Net::SSLinfo::
+:    Trace information for ''--trace''  options.
+:*  #{
+:    Trace information from  <code>NET::SSLinfo</code>  for  ''--trace''  options.
+:    These are data lines in the format:   #{ variable name : value #}
+:    Note that  <code>value</code>  here can span multiple lines and ends with #}
+====== Using outdated modules======
+:The tools was designed to work with old Perl modules too.  When using
+:old modules, a proper  <code>**WARNING:</code>  will be printed. These warinings
+:cannot be switched of using  --no-warning  .
+:The warning also informs about the missing functionality or check.
+:I.g. it is best to install newer versions of the module if possible.
+:A good practice to check if modules are available in a proper version
+:is to call:
+  o-saft.pl +version
+  o-saft.pl +version --v --v
+:Following example shows the result without warnings:
+      === reading: ./.o-saft.pl (RC-FILE done) ===
+      === reading: Net/SSLhello.pm (O-Saft module done) ===
+      === reading: Net/SSLinfo.pm (O-Saft module done) ===
+      === ./o-saft.pl 16.09.09 ===
+          Net::SSLeay::
+             ::OPENSSL_VERSION_NUMBER()    0x268443744
+             ::SSLeay()                    0x268443744
+          Net::SSLeay::SSLeay_version()    OpenSSL 1.0.2-chacha (1.0.2f-dev)
+      = openssl =
+          version of external executable   OpenSSL 1.0.2-chacha (1.0.2f-dev)
+          external executable              /opt/openssl-chacha/bin/openssl
+          used environment variable (name) LD_LIBRARY_PATH
+          environment variable (content)   <<undef>>
+          path to shared libraries
+          full path to openssl.cnf file    <<undef>>
+          common openssl.cnf files         /usr/lib/ssl/openssl.cnf \
+                                           /etc/ssl/openssl.cnf \
+                                           /System//Library/OpenSSL/openssl.cnf \
+                                           /usr/ssl/openssl.cnf
+          URL where to find CRL file       <<undef>>
+          directory with PEM files for CAs /opt/tools/openssl-chacha/ssl/certs
+          PEM format file with CAs         /etc/ssl/certs/ca-certificates.crt
+          common paths to PEM files for CAs /etc/ssl/certs /usr/lib/certs \
+                                            /System/Library/OpenSSL
+          common PEM filenames for CAs     ca-certificates.crt \
+                                           certificates.crt certs.pem
+          number of supported ciphers      177
+          openssl supported SSL versions   SSLv3 TLSv1 TLSv11 TLSv12
+          o-saft.pl known SSL versions     SSLv2 SSLv3 TLSv1 TLSv11 TLSv12 TLSv13 \
+                                           DTLSv09 DTLSv1 DTLSv11 DTLSv12 DTLSv13
+      = o-saft.pl +cipherall =
+          default list of ciphers          0x03000000 .. 0x030000FF, 0x0300C000 .. 0x0300C0FF, \
+x0300CC00 .. 0x0300CCFF, 0x0300FE00 .. 0x0300FFFF,
+      = Required (and used) Modules =
+          @INC                 ./ ./lib . /bin /usr/share/perl5 \
+                               /usr/lib/x86_64-linux-gnu/perl5/5.20 \
+                               /usr/lib/x86_64-linux-gnu/perl/5.20 \
+                               /usr/share/perl/5.20 /usr/local/lib/site_perl .
+      =   module name            VERSION  found in
+      =   ----------------------+--------+------------------------------------------
+          IO::Socket::INET       1.35     /usr/lib/x86_64-linux-gnu/perl/5.20/IO/Socket/INET.pm
+          IO::Socket::SSL        2.002    /usr/share/perl5/IO/Socket/SSL.pm
+          Net::DNS               0.81     /usr/lib/x86_64-linux-gnu/perl5/5.20/Net/DNS.pm
+          Net::SSLeay            1.72     /usr/lib/x86_64-linux-gnu/perl5/5.20/Net/SSLeay.pm
+          Net::SSLinfo           16.06.01 Net/SSLinfo.pm
+          Net::SSLhello          16.05.16 Net/SSLhello.pm
+          osaft                  16.05.10 osaft.pm
+:Following example shows the result with warnings:
+      === reading: ./.o-saft.pl (RC-FILE done) ===
+      === reading: ./Net/SSLhello.pm (O-Saft module done) ===
+      **WARNING: ancient Net::SSLeay 1.35 < 1.49; cannot use ::initialize at /Net/SSLinfo.pm line 481.
+      === reading: ./Net/SSLinfo.pm (O-Saft module done) ===
+      **WARNING: ancient perl has no 'version' module; version checks may not be accurate; at o-saft.pl line 1662.
+      **WARNING: ancient Net::SSLeay 1.35 < 1.49 detected; at o-saft.pl line 1687.
+      **WARNING: ancient IO::Socket::SSL 1.22 < 1.37 detected; at o-saft.pl line 1687.
+      **WARNING: ancient version IO::Socket::SSL 1.22 < 1.90 does not support SNI or is known to be buggy; SNI disabled; at o-saft.pl line 5905.
+      !!Hint: --force-openssl can be used to disables this check
+      **WARNING: ancient version Net::SSLeay 1.35 < 1.49  may throw warnings and/or results may be missing; at o-saft.pl line 5934.
+      **WARNING: SSL version 'TLSv11': not supported by Net::SSLeay; not checked
+      **WARNING: SSL version 'TLSv12': not supported by Net::SSLeay; not checked
+      **WARNING: SSL version 'TLSv13': not supported by Net::SSLeay; not checked
+      === o-saft.pl 16.09.09 ===
+          Net::SSLeay::
+             ::OPENSSL_VERSION_NUMBER()    0x9470143
+      **WARNING: ancient version Net::SSLeay 1.35 < 1.49; cannot compare SSLeay with openssl version at o-saft.pl line 4778.
+             ::SSLeay()                    0x1.35
+      **WARNING: ancient version Net::SSLeay 1.35 < 1.49; detailed version not available at o-saft.pl line 4806.
+      = openssl =
+          version of external executable   OpenSSL 0.9.8y 5 Feb 2013
+          external executable              /usr/bin/openssl
+          used environment variable (name) LD_LIBRARY_PATH
+          environment variable (content)   <<undef>>
+          path to shared libraries
+          full path to openssl.cnf file    <<undef>>
+          common openssl.cnf files         /usr/lib/ssl/openssl.cnf \
+                                           /etc/ssl/openssl.cnf \
+                                           /System//Library/OpenSSL/openssl.cnf \
+                                           /usr/ssl/openssl.cnf
+          URL where to find CRL file       <<undef>>
+          directory with PEM files for CAs /System/Library/OpenSSL/certs
+          PEM format file with CAs         <<undef>>
+          common paths to PEM files for CAs /etc/ssl/certs /usr/lib/certs /System/Library/OpenSSL
+          common PEM filenames for CAs     ca-certificates.crt certificates.crt certs.pem
+          number of supported ciphers      43
+          openssl supported SSL versions   SSLv2 SSLv3 TLSv1
+          o-saft.pl known SSL versions     SSLv2 SSLv3 TLSv1 TLSv11 TLSv12 TLSv13 \
+                                           DTLSv09 DTLSv1 DTLSv11 DTLSv12 DTLSv13
+      **WARNING: ancient version Net::SSLeay 1.35 < 1.49; cannot compare SSLeay with openssl version at o-saft.pl line 4778.
+      **WARNING: used openssl version '9470143' differs from compiled Net:SSLeay '1.35'; ignored
+      = o-saft.pl +cipherall =
+          default list of ciphers          0x03000000 .. 0x030000FF, 0x0300C000 .. 0x0300C0FF,
+x0300CC00 .. 0x0300CCFF, 0x0300FE00 .. 0x0300FFFF,
+      = Required (and used) Modules =
+          @INC                 ./ ./lib /bin /Library/Perl/Updates/5.10.0 \
+                               /System/Library/Perl/5.10.0/darwin-thread-multi-2level \
+                               /System/Library/Perl/5.10.0 \
+                               /Library/Perl/5.10.0/darwin-thread-multi-2level \
+                               /Library/Perl/5.10.0 \
+                               /Network/Library/Perl/5.10.0/darwin-thread-multi-2level \
+                               /Network/Library/Perl/5.10.0 \
+                               /Network/Library/Perl \
+                               /System/Library/Perl/Extras/5.10.0/darwin-thread-multi-2level \
+                               /System/Library/Perl/Extras/5.10.0 .
+      =   module name            VERSION  found in
+      =   ----------------------+--------+------------------------------------------
+          IO::Socket::INET       1.31     /System/Library/Perl/5.10.0/darwin-thread-multi-2level/IO/Socket/INET.pm
+          IO::Socket::SSL        1.22     /System/Library/Perl/Extras/5.10.0/IO/Socket/SSL.pm
+          Net::DNS               0.65     /System/Library/Perl/Extras/5.10.0/darwin-thread-multi-2level/Net/DNS.pm
+          Net::SSLeay            1.35     /System/Library/Perl/Extras/5.10.0/darwin-thread-multi-2level/Net/SSLeay.pm
+          Net::SSLinfo           16.06.01 ./Net/SSLinfo.pm
+          Net::SSLhello          16.05.16 ./Net/SSLhello.pm
+          osaft                  16.05.10 /osaft.pm
+:Please keep in mind that the shown version numbers and the shown line
+:numbers are examples and may differ on your system.
+:When starting <code>o-saft.pl</code> with outdated modules, more <code>**WARNING:</code> will
+:be shown. The warnings depend on the installed version of the module.
+:<code>o-saft.pl</code> is known to work with at least:
+:* ''IO::Socket::INET'' 1.31, ''IO::Socket::SSL'' 1.22, ''Net::DNS'' 0.66, ''Net::SSLeay'' 1.30
+====TESTING====
+:When talking about "testing the tool", functionl tests are meant.  So
+:this section describes "developer" rather than "user" options.
+:Testing the tool is a challenging task. Beside the oddities described
+:elsewhere, for example  [[#Name Rodeo|Name Rodeo]],  there are a bunch of problems
+:and error which may occour during runtime.
+:Makefiles are used for testing  functionality and code quality during
+:development. These tests are implemented in the  <code>./t/</code>  directory, see
+:the <code>Makefile.*</code> there.
+:Following options and commands for  <code>o-saft.pl</code> are available to improve
+:testing.  They mainly can simulate error conditions or stop execution
+:properly (they are not intended for other use cases):
+======+quit======
+:Stop execution after processing all arguments and before precessing
+:any target. The runtime configuration is complete at this point.
+======--exit=KEY======
+:Terminate  <code>o-saft.pl</code>  at specified <code>KEY</code>.  For available <code>KEY</code> please see:
+    o-saft.pl --help=exit
+    grep exit= o-saft.pl
+======--cfg-init=KEY=VALUE======
+:With this option values in the internal  %cfg  hash can be set:
+    $cfg{KEY} = VALUE
+:Only (perl) scalars or arrays can be set. The type will be detected
+:automatically.
+:Example,  this option can be used to change the text used as prefix
+:in each output line triggerd by the  ''--v''  option:
+    o-saft.pl --cfg-init=prefix_verbose="#VERBOSE: "
+:or the text used as prefix triggerd by the  ''--trace''  option:
+    o-saft.pl --cfg-init=prefix_trace="#TRACE: "
+======--v======
+:Print more information about checks.
+======--trace======
+:Print debugging messages.
+:For more details, please see  [[#Options for tracing and debugging|Options for tracing and debugging]] .
+=====Internal testing=====
+:Following options and commands for  <code>o-saft.pl</code>  are for internal testing.
+:They provide informations about internal data structures and alike.
+:See also tests in t/Makefile* .
+:These options behave like the command  +quit  and  do not perform any
+:checks on the target(s).
+======--test-data======
+:Print overview of all available commands and checks.
+======--test-maps======
+:Print internal data strucures <code>%cfg{openssl}</code>, <code>%cfg{ssleay}</code>.
+======--test-prot======
+:Print internal data according protocols.
+======--test-regex======
+:Print results for applying various texts to defined regex.
+======--test-subs======
+:Print formatted list of internal functions with their description.
+:Not to be intended in conjunction with any target check.
+======--test-cipher-list======
+:Print list of hex keys of known ciphers.
+======--test-cipher-show======
+:Print complete list of ciphers.
+======--test-cipher-sorted======
+:Print list of ciphers sorted according strength.
+==== EXAMPLES====
+:($0 in all following examples is the name of the tool)
+===== General=====
+    o-saft.pl +cipher some.tld
+    o-saft.pl +info   some.tld
+    o-saft.pl +check  some.tld
+    o-saft.pl +quick  some.tld
+    o-saft.pl +help=commands
+    o-saft.pl +list
+    o-saft.pl +list --v
+    o-saft.pl +certificate  some.tld
+    o-saft.pl +fingerprint  some.tld 444
+    o-saft.pl +after +dates some.tld
+===== Some Specials=====
+*  Get an idea how messages look like
+    o-saft.pl +check --cipher=RC4 some.tld
+*  Check for Server Name Indication (SNI) usage only
+    o-saft.pl +sni some.tld
+*  Check for SNI and print certificate's subject and altname
+    o-saft.pl +sni +cn +altname some.tld
+*  Check for all SNI, certificate's subject and altname issues
+    o-saft.pl +sni_check some.tld
+*  Only print supported ciphers
+    o-saft.pl +cipher --enabled some.tld
+*  Only print unsupported ciphers
+    o-saft.pl +cipher --disabled some.tld
+*  Test for a specific ciphers
+    o-saft.pl +cipher --cipher=ADH-AES256-SHA some.tld
+* Test all ciphers, even if not supported by local SSL implementation
+    o-saft.pl +cipherraw some.tld
+    o-saft.pl +cipherall some.tld
+    o-saft.pl +cipherall some.tld --range=full
+    checkAllCiphers.pl example.tld --range=full --v
+* Show supported (enabled) ciphers with their DH parameters:
+    o-saft.pl +cipher-dh some.tld
+*  Test using a private libssl.so, libcrypto.so and openssl
+    o-saft.pl +cipher --lib=/foo/bar-1.42 --exe=/foo/bar-1.42/apps some.tld
+*  Test using a private openssl
+    o-saft.pl +cipher --openssl=/foo/bar-1.42/openssl some.tld
+*  Test using a private openssl also for testing supported ciphers
+    o-saft.pl +cipher --openssl=/foo/bar-1.42/openssl --force-openssl some.tld
+*  Show current score settings
+    o-saft.pl --help=score
+*  Change a single score setting
+    o-saft.pl --cfg_score=http_https=42   +check some.tld
+*  Use your private score settings from a file
+    o-saft.pl --help=score > magic.score
+:    # edit as needed: magic.score
+    o-saft.pl --cfg_score    magic.score  +check some.tld
+*  Use your private texts in output
+    o-saft.pl +check some.tld --cfg_text=desc=<code>my special description</code>
+*  Use your private texts from RC-FILE
+    o-saft.pl --help=cfg_text >> .o-saft.pl
+:    # edit as needed:     .o-saft.pl
+    o-saft.pl +check some.tld
+* Use your private hint texts in output
+    o-saft.pl +check some.tld --cfg-hint=renegotiation="my special hint text"
+* Get the certificate's Common Name for a bunch of servers:
+    o-saft.pl +cn example.tld some.tld other.tld
+    o-saft.pl +cn example.tld some.tld other.tld --showhost --no-header
+*  Generate simple parsable output
      o-saft.pl --legacy=quick --no-header +info  some.tld
      o-saft.pl --legacy=quick --no-header +check some.tld
      o-saft.pl --legacy=quick --no-header --trace-key +info  some.tld
      o-saft.pl --legacy=quick --no-header --trace-key +check some.tld
 *  Generate simple parsable output for multiple hosts
      o-saft.pl --legacy=quick --no-header --trace-key --showhost +check some.tld other.tld
 *  Just for curiosity
      o-saft.pl some.tld +fingerprint --format=raw
      o-saft.pl some.tld +certificate --format=raw | openssl x509 -noout -fingerprint
-===== Specials for hunting problems with connections etc.=====
+===== Testing with exit code=====
+* Test SSL/TLS connection and return exit code
-*  Show command line argument processing
+    o-saft.pl +check  --exitcode  some.tld
-     o-saft.pl +info some.tld --trace-arg
+* Test ciphers and return exit code with details about exit code
+    o-saft.pl +cipher --exitcode --exitcode-v  some.tld
-*  Simple tracing
+* Test ciphers and return exit code for ciphers only
+    o-saft.pl +cipher --exitcode --exitcode-no-prot  some.tld
+* Test with exit code but avoid checks considered 'yes' even if 'no'
+    o-saft.pl +check  --exitcode --ignore-out=ev- --ignore-out=rfc_7525 some.tld
+===== Specials for hunting problems with connections etc.=====
+*  Show command line argument processing
+     o-saft.pl +info some.tld --trace-arg
+*  Simple tracing
+    o-saft.pl +cn   some.tld --trace
+    o-saft.pl +info some.tld --trace
+*  A bit more tracing
+    o-saft.pl +cn   some.tld --trace --trace
+* Show internal variable names in output
+    o-saft.pl +info some.tld --trace-key
+* Show internal argument processeing
+    o-saft.pl +info --trace-arg some.tld
+* Show internal control flow
+    o-saft.pl +info some.tld --trace-cmd
+* Show internal timing
+    o-saft.pl +info some.tld --trace-time
+* Show checking ciphers
+    o-saft.pl +cipher some.tld --v --v
+<!-- following no longer implemented (8/2016)
+*  List checked ciphers one per line
+    o-saft.pl +cipher some.tld --v --v -v
+*  Show processing of ciphers
+    o-saft.pl +cipher some.tld --v --v --v -v
+-->
+*  Show values retrieved from target certificate directly
+    o-saft.pl +info some.tld --no-cert --no-cert --no-cert-text=Value-from-Certificate
+*  Show certificate CA verifications
+    o-saft.pl some.tld +chain_verify +verify +error_verify +chain
+*  Avoid most performance and timeout problems (don't use  --v)
-     o-saft.pl +cn   some.tld --trace
+     o-saft.pl +info some.tld --no-dns --no-sni --ignore-no-conn
-     o-saft.pl +info some.tld --trace
+     o-saft.pl +info some.tld --no-dns --no-sni --no-cert --no-http --no-openssl
-*  A bit more tracing
+* Identify timeout problems
+    o-saft.pl +info some.tld --trace-cmd
-    o-saft.pl +cn   some.tld --trace --trace
+this will show lines containing:
-*  Show internal variable names in output
+     #O-Saft  CMD: test ...
-    o-saft.pl +info some.tld --trace-key
+====DOCUMENTATION====
-* Show internal argument processeing
+=====User Documentation=====
-    o-saft.pl +info --trace-arg some.tld
+:Documentation is mainly intented for the user, which is provided with
-* Show internal control flow and timing
+  o-saft.pl --help
-    o-saft.pl +info some.tld --trace-time
+:But it may be difficult to find the proper information there.  To get
+:more selective documentations, the  ''--help=*''  options can be used. To
+:get an overview which  ''--help=*''  options are available, use:
-*  List checked ciphers
+  o-saft.pl --help=HELP
-    o-saft.pl +cipher some.tld --v --v
+:This only provides the complete user documentation, or the well known
+:parts specified by the keyword, (HELP in example above).  To find any
+:text with some lines of context, following could be used:
-*  List checked ciphers one per line
+  o-saft.pl --help | egrep -i -C 3 "some text"
-    o-saft.pl +cipher some.tld --v --v -v
+:This is simply avaiable with:
-*  Show processing of ciphers
+  o-saft -help="some text"
-    o-saft.pl +cipher some.tld --v --v --v -v
+:In the GUI a more sophisticate search is implemented, see the  "Help"
+:window there:
-*  Show values retrieved from target certificate directly
+  o-saft.tcl
-    o-saft.pl +info some.tld --no-cert --no-cert --no-cert-text=Value-from-Certificate
+=====Developer Documentation=====
-*  Show certificate CA verifications
+:Documentation for developers is provided in various ways. Information
+:for developers can be found found in:
-    o-saft.pl some.tld +chain_verify +verify +error_verify +chain
+:* the files itself
-*  Avoid most performance and timeout problems (don't use  --v)
+:* with:  <code>o-saft.pl --help=HELP</code>
-    o-saft.pl +info some.tld --no-cert --no-dns --no-http --no-openssl --no-sni
+:* using:  <code>make</code>
 ==== ATTRIBUTION====
@@ Line 3,383: / Line 4,447: @@
 ==== VERSION====
-:@(#) 16.07.16
+:@(#) 19.09.19
 ----
 <small>