Commands to show results of checked certificate data

Commands to show results of checked connection data

Commands to show results of checked target (connection) data

Commands to show results of checked length and count data

Commands to show results of checked HTTP vs. HTTPS data

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-dh

While +cipher prints checked ciphers, +cipher-dh prints ciphers with their DH or ECDH paramaters (if available) only for supported ciphers.

+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 cipher selected by the server for each protocol.

+cipher-selected vs. +cipher-default

+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 cipher selected by the server for each protocol.

+cipher-strong vs. +cipher-default

+strong-cipher 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 usefull 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

--help

WYSIWYG

cmd

--help=cmd

Show available commands; short form.

commands

--help=commands

Show available commands with short description.

opt

--help=opt

Show available options; short form.

options

--help=options

Show available options with their description.

checks

--help=checks

Show available checks.

tools

--help=tools

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

check-cfg

--help=check-cfg

cfg-check

--help=cfg-check

Show texts used as labels in output for checks (see +check) ready for use in RC-FILE or as option.

data

--help=data

Show available informations.

data-cfg

--help=data-cfg

cfg-data

--help=cfg-data

cfg-info

--help=cfg-info

Show texts used as labels in output for data (see +info) ready for use in RC-FILE or as option.

hint

--help=hint

Show texts used in hint messages.

hint-cfg

--help=hint-cfg

cfg-hint

--help=cfg-hint

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

text

--help=text

Show texts used in various messages.

text-cfg

--help=text-cfg

cfg-text

--help=cfg-text

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

legacy

--help=legacy

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

compliance

--help=compliance

Show available compliance checks.

intern

--help=intern

Show internal commands.

alias

--help=alias

Show alias for commands and options.

pattern

--help=pattern

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

range

--help=range

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

score

--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 score --trace and/or --cfg-score=KEY=SCORE before --help=score.

toc

--help=toc

content

--help=content

Show headlines from help text. Useful to get an overview.

SECTION

--help=SECTION

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

ourstr

--help=ourstr

Show regular expressions to match our own strings used in output.

regex

--help=regex

Show regular expressions used internally.

gen-html

--help=gen-html

Print documentation in HTML format.

gen-pod

--help=gen-pod

Print documentation in POD format.

gen-wiki

--help=gen-wiki

Print documentation in mediawiki format.

gen-cgi

--help=gen-cgi

Print documentation in format to be used for CGI.

error

--help=error

warning

--help=warning

problem

--help=problem

Show KNOWN PROBLEMS section with description of known error and warning messages.

faq

--help=faq

Show KNOWN PROBLEMS and LIMITATIONS section.

glossary

--help=glossary

Show common abbreviation used in the world of security.

links

--help=links

Show list of URLs related to SSL/TLS.

rfc

--help=rfc

Show list of RFC related to SSL/TLS.

todo

--help=todo

Show known problems and bugs.

exit

--help=exit

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

program.code

--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 PORT of target 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:

will connect to:

--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.

--starttls

Use STARTTLS command to start a TLS connection via SMTP. This option is a shortcut for --starttls=SMTP .

--starttls=SMTP

--starttls=PROT

Use STARTTLS command to start a TLS connection via protocol. PROT may be any of: SMTP, IMAP, IMAP2, POP3, FTPS, RDP, LDAP or 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

--rc

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

--no-rc

Do not read RC-FILE.

--exitcode

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

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

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

Functionality implemented experimental, may change in future.

--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-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 information 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:

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 information. 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(1)

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, 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.:

--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 when the total amount of errors increases --ssl-error-total=CNT.

Note that this may result in loss of information and/or checks.

--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:

See Note on SSL versions for a general note about SSL versions. A more detailled description of the problem and how Net::SSLeay be- haves, can be found in the source of o-saft.pl , see section starting at

--timeout=SEC

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

--call=METHOD

METHOD method to be used for specific functionality

Available methods:

Method names starting with:

The second part of the name denotes which kind of method to call:

Example:

will use the external openssl(1) executable to check the target for supported ciphers.

Default settings are:

Just for curiosity, instead of using:

consider to use your own script like:

:-))

-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

--cipher=CIPHER

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:

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 requested 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(1) like:

which occours with some versions of IO::Socket::SSL(1) when a *-MD5 ciphers will be used with other protocols than SSLv2.

Note that these ciphers will be checked for SSLv2 only.

--sslv2

--sslv3

--tlsv1

--tlsv11

--tlsv12

--tlsv13

--dtlsv09

--dtlsv1

--dtlsv11

--dtlsv12

--dtlsv13

--SSL, -protocol SSL

--no-sslv2

--no-sslv3

--no-tlsv1

--no-tlsv11

--no-tlsv12

--no-tlsv13

--no-dtlsv09

--no-dtlsv1

--no-dtlsv11

--no-dtlsv12

--no-dtlsv13

--no-SSL

(--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(1). 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 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 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.

--ca-force

--force-ca

NOT YET IMPLEMENTED I. g. openssl uses default settings where to find certificate files. When --ca-file=FILE and/or --ca-path=DIR was used, this default will be overwritten by appropriate options passed to openssl. If the default does not work as expected, --force-ca can be used to force setting of proper values according well known common defaults. See:

to see the used settings.

--alpn

Use -alpn option for openssl.

--no-alpn

Do not use -alpn option for openssl.

--no-npn

--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 s_client command.

Options for +cipher command

--connect-delay=SEC

Additional delay in seconds after each connect for a cipher check. This is useful when connecting to servers which have IPS in place, or are slow in accepting new connections or requests.

--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-npn=, sets empty list. --cipher-npn=,, 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:

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

Some servers do not answer (i.g. they disconnect) if none of the offered ciphers is supported by the server.

Continue testing with next ciphers when the target disconnects or does not send data within specified timeout (see --timeout). Useful for TLS intolerant servers.

--no-ssl-nodata-nocipher

Abort testing with next ciphers when the target disconnects.

--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

--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 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:

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=quick

Internal format: use tab as separator; ciphers are printed with bit length (implies --tab).

--legacy=simple

Internal default format.

--legacy=key

Internal format: print name of key instead of text as label. Key is that of the internal data structure(s). For ciphers and protocols, the corresponding hex value is used as key. Note that these values are unique.

--format=0x

--format=\x

--format=/x

--format=hex

--format=raw

This option is used to specify the format of the result lines. This covers the value of the result line only.

--header

Print formatting header. Default for +check, +info, +quick and 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.

--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:

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:

alias

Following list contains only those options not shown with:

alias

Tool's Option (Tool) o-saft.pl Option

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

Options for customization

For general descriptions please see CUSTOMIZATION section below.

--cfg_cmd=CMD=LIST

--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:

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

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

--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: 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-checks=KEY=TEXT

--cfg_data=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: cfg-checks

--cfg-cipher=CIPHER=value

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

--cfg_text=KEY=TEXT

--cfg-text=KEY=TEXT

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

To get a list of preconfigured texts, use: 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: cfg-hint

--cfg-init=KEY=VALUE

Set the internal %cfg hash. This options is intended for testing and debugging only. Please see TESTING below.

--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

Do not execute, just show commands (only useful in conjunction with using openssl).

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 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-arg

--trace--

Print command line argument processing.

--trace-cmd

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

--trace-key

--trace@

Print some internal variable names in output texts (labels). Variable names are prefixed to printed line and enclosed in # . Example without --trace-key :

Example with --trace-key :

--trace-time

Prints trace output with timestamps. More timestamps are printed if used together with --trace-cmd.

--trace=VALUE

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

Trace Option Alias Option

--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 itself.

--trace-sub

+traceSUB

Print formatted list of internal functions with their description. Not to be intended in conjunction with any target check.

--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:

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:

A warning will be printed.

Options

We support following options, which are all identical, for lazy users and for compatibility with other programs.

This applies to most such options, --port is just an example. When used in the RC-FILE, the --OPTION=VALUE variant must be used.

Dash -, dot . and/or underscore _ in option names are optional, all following are the same:

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

Targets

Following syntax is supported also:

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

Check if heartbeat extension is supported by target.

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

Check if target is vulnerable to ROBOT attack (server offers ciphers with RSA encryption).

Check if target is vulnerable to SLOTH attack (server offers RSA-MD5 or ECDSA-MD5 ciphers).

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.

Check if target supports ALPN. Following messages are evaluated:

Please see also CHECKS ALPN and NPN below.

SSL Vulnerabilities

Check if ciphers for anonymous key exchange are supported: ADH|DHA. Such key exchanges can be sniffed.

Check if ephemeral ciphers are supported: DHE|EDH. They are necessary to support Perfect Forward Secrecy (PFS).

Check if ciphers with CBC for protocol SSLv1, SSLv3 or TLSv1 are used. TLSv1.2 checks are not yet implemented.

Connection is vulnerable if target supports SSL-level compression, or supports SPDY/3 (because SPDY/3 uses compression). See http://zoompf.com/2012/09/explaining-the-crime-weakness-in-spdy-and-ssl

Note: SPDY/3 is only possible if the client explicitely asks for this alternate protocol (for example openssl ... -nextprotoneg spdy/3).

Connection is vulnerable if target supports SSLv2.

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/ .

Check if target is vulnerable to heartbleed attack, see CVE-2014-0160 and http://heartbleed.com/ .

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.

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.

Check if target is vulenerable to Logjam attack. Check if target suports EXPORT ciphers and/or DH Parameter is less than 2048 bits. ECDH must be greater to 511 bits.

Check if CBC ciphers are offered. NOTE the recommendation to be safe against Lucky13 was to use RC4 ciphers. But they are also subject to attacks (see below). Hence the check is only for CBC ciphers.

Check if RC4 ciphers are supported. They are assumed to be broken. Note that +rc4 reports the vulnerabilitiy to the RC4 Attack, while +cipher-rc4 simply reports if RC4 ciphers are offered. However the check, and hence the result, is the same.

Check if DHE ciphers are used. Checks also if the TLS session ticket is random or not used at all. TLSv1.2 checks are not yet implemented.

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

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.

Bleichebacher's Oracle attack against SSL/TLS ciphers.

Not implemented. https://robotattack.org/

Currently (2016) we check for ciphers with ECDSA, RSA-MD5. Checking the TLS extension tls-unique is not yet implemented.

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

NOT YET IMPLEMENTED Check if target is vulnerable to ticketbleed, means that it returns up to 31 random bytes from memory as Session Ticket, see CVE-2016-9244 and https://filippo.io/Ticketbleed/ .

Target (server) Configuration and Support

See above.

Check if the server allows client-side initiated renegotiation.

NOT YET IMPLEMENTED Check if the server allows changing the protocol.

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

Target (server) Certificate

Check that fingerprint is not MD5. Check that certificate private key signature is SHA2 or better.

Provided certificate by target should not be a Root CA.

Certificate should not be self-signed.

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.

NOT YET IMPLEMENTED

Certificate extension Basic Constraints should be CA:FALSE.

Certificate should contain URL for OCSP and CRL.

Certificates signature key supports encryption.

Certificates signature key encryption algorithm is well known.

Certificates public key supports encryption.

Certificates public key encryption algorithm is well known.

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

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 ecliptive curves are used, the result for these checks is always no (<<N/A ...).

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

...

The Certificate must provide:

This check is performed according the requirements defined by the CA/ Browser Forum https://www.cabforum.org/contents.html . The certificate must provide:

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

Optional are: /street=, /postalCode=

See LIMITATIONS also.

Target (server) HTTP(S) Support

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.

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

Additionally, the site must have:

Except the last requirement, +preload will do the checks. Note that +preload is defined in .o-saft.pl only.

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:

For some details of these cjecks, 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:

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:

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 compliance, and it is also difficult to check all these conditions. That is why some compliance checks are not completely implemented. For details see below please.

Also note that in the RC-FILE the output of results for some checks is disabled by default. A !!Hint: message will be printed, if any of these checks are used.

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 die EC-Verfahren ... und weitere Erläuterungen siehe Bemerkung 4 in Kapitel 3 in [TR-02102-1] .

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 RFC 5746).

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 Lucky13-Angriff 3.4.5 Die Encrypt-then-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 > 2048 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.2 Umgang mit Ephemeralschlüsseln

This requirement is not testable from remote.

4.3 Zufallszahlen

This requirement is not testable from remote.

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 +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.

Check if the FQDN is listed in the certificates subjectAltname.

Checks values CommonName, Subject and SubjectAltname of the certificate for:

Same as STS header +hsts .

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 bits with EC. (Check currently, 4/2016, based on openssl which may not provide DH

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 not described above, will have the form (by default):

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.

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:

More examples for postprocessing the output can be found here:

CUSTOMIZATION

This tools can be customized as follows:

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

A configuration file can contain multiple configuration settings. Syntax is simply KEY=VALUE. Please see CONFIGURATION FILE below.

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.

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.

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 Information 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 files must be specified with one of the --cfg-* options. The specified file can be a valid path. Please note that only the characters: a-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.

Resource files are searched for and used automatically. For details see RC-FILE below.

Debug files are searched for and used automatically. For details see DEBUG-FILE below.

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:

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 are 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:

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 only values for %data will be set, and so on. KEY will not be used when KEY=TEXT is an existing filename. It i 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 intern 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:

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

[openssl] ... openssl 1.0.1

If in any doubt, use +list --v to get an idea about the mapping. regex Use --help=regex to see which regex are used to handle all 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 if 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):

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):

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.

The default behaviour will be to use the cipher names like openssl(1) does. If a name is ambigous, the first matching will be choosen. This -first matching- only applies to names provided by the user by option or whatever, internally the latest IANA number will be used, because they have the most less ambiguities.

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(1) 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:

instead of:

**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:

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):

occurs if the target refused a connection on port 80. This is considered a bug in Net::SSLeay(1). 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:

See also Note on SSL versions .

Workaround: use option: --no-sslv2 --no-sslv3 --no-tlsv13 --no-dtlsv1

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. See also Note on SSL versions .

Workaround: use --ssl-lazy option, or corresponding --no-SSL option.

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:

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:

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

does not print anything.

Workaround: use --v option.

or

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: gen-pod

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

On some (mainly Windows-based) systems this may happen when calling for example: FAQ

which then may produce:

Workaround: use full path to perl.exe, for example 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):

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:

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. It is the only command which allows +cipher together with other commands.

+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:

Following commands and options are useful to get more information:

User Provided Files

Please note that there cannot be any guarantee that the code provided in the DEBUG-FILE o-saft-dbx.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 disable it within o-saft.pl:

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, leads 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:

This means that no more connections are made when more than

Examples:

no more connections are made if for example any sequence of timeouts occour:

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):

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:

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 a correct path for --openssl=TOOL option. Variants are:

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:

Where INSTALL_PATH is the path where the tool is installed. To see which files have been included use:

Perl Modules

Additional files used if requested

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 the purpose of this tool is to detect such insecure settings, functions, etc., it needs these dirty things enabled. It needs (incomplete list):

Therefore we recommend to compile and install at least following:

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:

The sources are available at

For all following installation examples we assume:

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:

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:

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.

Building our own library and module (with openssl from /usr/local):

SSLeay.xs needs to be changed as follows:

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:

Testing OpenSSL

After installation as descibed above finished, openssl may be tested:

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:

we should see a line similar to follwong at the end of the output:

Now check for supported (known) ciphers:

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:

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:

For more details, please refer to:

BUILD DOCKER IMAGE

The Docker image can be installed as follows:

The image can also easily be build from the Dockerfile (which is part of the distribution) as follows:

To build the image from the Dockerfile with docker commands, see:

For more details, please refer to:

SEE ALSO

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:

There're some workarounds implemented since version 15.11.15 .

There're some workarounds implemented since version 15.11.15 .

We try to detect unsupported versions and disable them automatically, a warning like follwoing is shown then:

All such warnings look like:

If problems occour with SSL versions, following commands and options may help to get closer to the reason or can be used as workaround:

Checking for SSL version is done at one place in the code, search for

However, there are some dirty hacks where SSLv2 and SSLv3 is checked again.

Using private libssl.so and libcrypt.so

For all cryptographic functionality the libraries installed on the system will be used. In particular perl's Net::SSLeay(1) module, the system's libssl.so and libcrypt.so and the openssl(1) executable.

It is possible to provide your own libraries, if the perl 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_PATH environment 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=TOOL

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:

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(1) 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:

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:

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:

which returns something like:

Here only the first two libraries are important. Both, libcrypto.so and libssl.so need to be version 0.9.8 (in this example).

or:

This works if openssl(1) uses the same shared libraries as Net::SSLeay(1), 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(1) 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:

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.

A more cumbersome approach to call this program is to set following environment variables in your shell:

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(1) 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.

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 is 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

Options

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:

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:

Following example shows the result without warnings:

Following example shows the result with warnings (line nr. may vary):

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.

TESTING

When talking about testing the tool, functional tests are meant. So this section describes developer rather that 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 errors which may occour during runtime.

Following options and commands 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 tool at specified KEY. For available KEY, please see: exit

--cfg-init=KEY=VALUE

With this option values in the internal %cfg hash can be set:

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:

or the text used as prefix triggerd by the --trace option:

EXAMPLES

(o-saft.pl in all following examples is the name of the tool)

General

Some specials

Specials for hunting problems with connections etc.

this will show lines containing: #O-Saft CMD: test ...

ATTRIBUTION

Based on ideas (in alphabetical order) of:

VERSION

@(#) 18.11.18

AUTHOR

31. July 2012 Achim Hoffmann (at) sicsec de

Project Home: https://www.owasp.org/index.php/O-Saft

© sic[✓]sec GmbH, 2012 - 2017