O-Saft/Documentation

From OWASP
Revision as of 18:20, 28 July 2014 by Achim (Talk | contribs)

Jump to: navigation, search

O-Saft

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

o-saft.pl --help


NAME

o-saft.pl - OWASP SSL audit for testers
OWASP SSL advanced forensic tool

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.

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 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
  • List all available commands:
   o-saft.pl --help=commands
For more specialised test cases, refer to the COMMANDS and OPTIONS
sections below.
If no command is given, +cipher is used.

WHY?

Why a new tool for checking SSL security and configuration when there
are already a dozen or more such tools in existence (circa 2012)?
Currently available tools suffer from some or all of following issues:
* lack of tests of unusual ciphers
* 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 they are either binary and hence
not portable to other (newer) 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 +cipher +hsts_sts example.tld
For more, please see EXAMPLES section below.

TECHNICAL INFORMATION

It is important to understand, which provided information is based on
data returned by underlaying (used) libraries and the information
computed directly.
In general the tool uses perl's Net::SSLeay(1) 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
  • --force-openssl
  • --exe-path=PATH --exe=PATH
All checks according the validity of the certificate chain are based
on the root CAs installed on the system. NOTE that Net::SSLeay(1)
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
Above applies to all commands except +cipherall which uses no other
libraries.

RESULTS

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.
+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.
ll output is designed to make it easily parsable by postprocessors.
lease see OUTPUT section below for details.

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=cmd
The summary and internal commands return requested information or the
results of checks. These are described below.
The description of all other commands will be printed with
   o-saft.pl --help=commands
Commands for information about this tool
All these commands will exit after execution (cannot be used together
with other commands).
+ciphers
Show ciphers offerd by local SSL implementation.
This commands prints the ciphers in format like openssl ciphers
does. It also accepts the -v and -V option.
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
Use --v option to show more details.
+abbr +abk
Show common abbreviation used in the world of security.
+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.
+todo
Show known problems and bugs.
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. This is the same as
+info +cipher +sizes --sslv2 --sslv3 --tls1
but also gives some kind of scoring for security issues if any.
+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 --short.
+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 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 target's ciphers
+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 --local option for that.
+cipherraw
Check target for all possible ciphers.
Does not depend on local SSL implementation.
WARNING: needs to be extensively tested (04/2014)


Commands to test SSL connection to target
Please see:
   o-saft.pl --help=commands
Commands to show details of the target's certificate
Please see:
   o-saft.pl --help=commands

OPTIONS

All options are written in lowercase. Words written in all capital in
the description here is text provided by the user.
General options
--h
--help
WYSIWYG
Note: The documentation is written with perl's POD format and uses
perl's POD module to print it. Unfortunately the first line
written by POD is:
            'User Contributed Perl Documentation'
which may be a bit misleading because all descriptions of the
documentation belong to this tool itself.
--help=cmd
Show available commands.
--help=commands
Show available commands with short description.
--help=checks
Show available checks.
--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=RANG).
--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=text
Show texts used in various messages.
--help=text-cfg
Show texts used in various messages ready for use in in RC-FILE or
as option.
--help=regex
Show regular expressions used internally.
--help=wiki
Show help text in mediawiki format.
--no-rc
Do not read RC-FILE .
--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 and --port=PORT and HOST:PORT and 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 uses 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.
--proxyuser=PROXYUSER
Specify username for proxy authentication.
--proxypass=PROXYPASS
Specify password for proxy authentication.
--proxy=PROXYUSER:PROXYPASS@PROXYHOST:PROXYPORT is also possible.
--proxyport=PROXYPORT
Make all connection to target using PROXYHOST:PROXYPORT.
--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
*EXPERIMENTAL* option; please use --experimental to enable it.
--cgi, --cgi-exec
Internal use for CGI mode only.
Options for SSL tool
--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 following informations
are missing on Windows:
      compression, expansion, renegotiation, resumption,
      selfsigned, verify, chain, protocols
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.
--openssl=TOOL
TOOL can be a path to openssl executable; default: openssl
--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 the 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-lazy
if the --lib=PATH option doesn't work (for example due to changes
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 ...
-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
CIPHER can be any string accepeted 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.1c .
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
--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 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 when a *-MD5
ciphers will be used with other protocols than SSLv2.
Note that these ciphers will be checked for SSLv2 only.
--cipherrange=RANGE, --range=RANGE
Specify range of cipher constants to be tested by +cipherall .
Following RANGEs are supported:
  • rfc all ciphers defined in various RFCs
  • long like rfc but more lazy list of constants
  • 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 ...
--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.
--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).
--force-sni
Do not check if SNI seems to be supported by Net::SSLeay.
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.
--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 Net::SSLinfo.pm's
default string (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.
--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 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.
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:
  • 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 don't expect identical output as the TOOL, it's a best guess
and should be parsable in a very similar way.
TOOL may also be set to any of following internally defined values:
  • compact
Mainly avoid tabs and spaces format is as follows
        Some Label:<-- anything right of colon is data
  • full
Pretty print: each label in its own line, followed by data in
next line prepended by tab character (useful for +info only)
  • quick
Use tab as separator; print ciphers with bit length (--tab not necessary)
  • simple
Default format
--format=FORM
FORM may be one of follwoing:
  • 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 :.
--header
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.
--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.
--win-CR
Print windows-Style with CR LF as end of line. Default is NL only.
Options for compatibility with other programs
Please see other programs for detailed description (if not obvious:).
Note that only the long form options are accepted as most short form
options are ambiguous.
  • --capath DIR (curl) same as --ca-path DIR
  • --CApath=DIR (openssl) same as --ca-path DIR
  • --ca-directory=DIR (wget) same as --ca-path DIR:
  • --cacert FILE (curl) same as --ca-file DIR
  • --CAfile=FILE (openssl) same as --ca-file DIR
  • --ca-certificate=FILE (wget) same as --ca-path DIR
  • -c PATH (ssldiagnos) same as --ca-path DIR
  • --hide_rejected_ciphers (sslyze) same as --disabled
  • --http_get (ssldiagnos) same as --http
  • --printcert (ssldiagnos) same as +ciphers
  • --protocol SSL (ssldiagnos) same as --SSL
  • --no-failed (sslscan) same as --disabled
  • --regular (sslyze) same as --http
  • --reneg (sslyze) same as +renegotiation
  • --resum (sslyze) same as +resumtion
  • -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
  • -noSSL same as --no-SSL
  • -no_SSL same as --no-SSL
For definition of SSL see --SSL and --no-SSL above.
  • --insecure (cnark.pl) ignored
  • --nopct --nocolor (ssldiagnos) ignored
  • --ism, --pci -x (ssltest.pl) ignored
  • --timeout, --grep (ssltest.pl) ignored
  • -r, -s, -t (ssltest.pl) ignored
  • -connect, --fips, -H, -u, -url, -U ignored
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
are written without the leading +.
CMD can be any of: bsi, check, http, info, quick, sni, sizes
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 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:
   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=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.
--call=METHOD
See Options for SSL tool
--usr
Execute functions defined in o-saft-usr.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).
--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 --v --v
Print remotely checked ciphers one per line.
--v --v --v --v
Print processed ciphers (check, skip, etc.).
--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--
--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
  • --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=FILE
Use FILE instead of the default rc-file (.o-saft.pl, see RC-FILE).
--trace-sub +traceSUB
Print formatted list of internal functions with their description.
Not to be intended in conjunction with any target check.
--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.
--no-warning
Do not print warning messages (**WARNING:).
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 - and/or underscore _ in option names are optional.
--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 in
the near future (Any help appreciated ...).
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 heartbleed extension is supported by target.
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
Currently (2014) only a simple check is used: only RC4 ciphers used.
Which is any cipher with RC4, ARC4 or ARCFOUR.
TLSv1.2 checks are not yet implemented.
CRIME
Connection is vulnerable if target supports SSL-level compression.
HEARTBLEED
Check if target is vulnerable to heartbleed attack, see CVE-2014-0160
and http://heartbleed.com/ .
Lucky 13
NOT YET IMPLEMENTED
RC4
Check if RC4 ciphers are supported.
They are assumed to be broken.
PFS
Currently (2014) only a simple check is used: only DHE ciphers used.
Which is any cipher with DHE or ECDHE. SSLv2 does not support PFS.
TLSv1.2 checks are not yet implemented.
Target (server) Configuration and Support
Target (server) Certificate
Root CA
Provided certificate by target should not be a Root CA.
Self-signed Certificate
Certificate should not be self-signed.
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.
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
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
Publix Key Pins header
TBD - to be described ...
Compliances
FIPS-140
ISM
PCI
BSI TR-02102
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 there)
  • 3.2.1 Empfohlene Cipher Suites
  • 3.2.2 Übergangsregelungen
RC4 allowed temporary for TLS 1.0. Only if TLS 1.1 and TLS 1.2
cannot be supported.
  • 3.2.3 Mindestanforderungen für Interoperabilität
Must at least support: ECDHE-ECDSA-* and ECDHE-RSA-*
  • 3.3 Session Renegotation
Only server-side (secure) renegotiation allowed (see RFC5280).
  • 3.4 Zertifikate und Zertifikatsverifikation
Must have CRLDistributionPoint or AuthorityInfoAccess.
MUST have OCSP URL.
PrivateKeyUsage must not exceed three years for certificate and
must not exceed five years for CA certificates.
Subject, CommonName and SubjectAltName must not contain
a wildcard.
Certificate itself must be valid according dates if validity.
Note that the validity check relies on the years provided by the
certificate's before and after 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.
**NOT YET IMPLEMENTED**
Above conditions are not required for lazy checks.
  • 3.5 Domainparameter und Schlüssellängen
**NOT YET IMPLEMENTED**
  • 3.6 Schlüsselspeicherung
This requirement is not testable from remote.
  • 3.7 Umgang mit Ephemeralschlüsseln
This requirement is not testable from remote.
  • 3.8 Zufallszahlen
This requirement is not testable from remote.

SCORING

TBD Coming soon ...

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 **.
  • 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, ...
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:
        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: 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.
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=KEY=LIST
  • --cfg_score=KEY=SCORE
  • --cfg_checks=KEY=TEXT
  • --cfg_data=KEY=TEXT
  • --cfg_text=KEY=TEXT
Here 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.
CONFIGURATION FILE
Note that the file can contain KEY=TEXT pairs for the 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 is not used when KEY=TEXT is an
existing filename. Though, it's recommended to use a non-existing key,
for example: --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 or score 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 perl's @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 perl's @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.

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 --v 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. 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 .
It's each tool's responsibility 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 sources mention this. And for curiosity these
sources use both in cypher names but allow only EDH as shortcut in
openssl's `ciphers' command.
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

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 --timout=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
instead of:
        EXP-KRB5-RC4-MD5                no       weak
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 ....
This error may occur on systems where SSL's DTLSv1 is not supported.
The full message looks like:
      invalid SSL_version specified at C:/programs/perl/perl/vendor/lib/IO/Socket/SSL.
Workaround: use --no-dtlsv1 option.
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.
Performance Problems
There are various reasons when the program responds slow, or seems to
hang. Beside the problems described below performance issues are most
likely a target-side problem. Most common reasons are:
  • 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
Try to use following options to narrow down the cause of the problem:
  • use of external openssl executable
Use --no-openssl
Other options which may help to get closer to the problem's cause:
--timeout=SEC, --trace, --trace=cmd

LIMITATIONS

Commands
Some commands cannot be used together with others, for example:
+list, +libversion, +version, +check, +help.
+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 characters + and = cannot be used for --separator 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 (2014) a limitation in $0.
Broken pipe
This error message most likely means that the connection to specified
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.
Following table shows the openssl option and how to disbale it within
o-saft:
-nextprotoneg --no-nextprotoneg
-reconnect --no-reconnect
-tlsextdebug --no-tlsextdebug
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=.. 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.

DEPENDENCIES

All perl modules and all private moduels and files will be searched
for using paths available in perl's @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(1)
  • IO::Socket::INET(1)
  • Net::SSLeay(1)
  • Net::SSLinfo(1)
  • Net::SSLhello(1)
Additional Files used if requested
  • .o-saft.pl
  • o-saft-dbx.pm
  • o-saft-usr.pm
  • o-saft-README

SEE ALSO

openssl(1), Net::SSLeay(1), Net::SSLinfo(1), timeout(1)
http://www.openssl.org/docs/apps/ciphers.html
IO::Socket::SSL(1), IO::Socket::INET(1)

HACKER's INFO

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 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=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=FILE 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.
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 e.g. the encryption suites that
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(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 my occur:
WARNING: can't open config file: /path/to-openssl/ssl/openssl.cnf
This warning can be ignored, usually.
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.
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.
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.
Please see WARNING above if used in CGI mode. It's not recommended
to run this tool in CGI mode. You have been warned!

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

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 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
  • 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
Special 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
  • List checked ciphers
   o-saft.pl +cipher some.tld --v --v
  • 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
   o-saft.pl +info some.tld --no-cert --no-dns --no-http --no-openssl --no-sni

ATTRIBUTION

Based on ideas (in alphabetical order) of:
cnark.pl, SSLAudit.pl sslscan, ssltest.pl, sslyze.py
O-Saft - OWASP SSL advanced forensic tool
Thanks to Gregor Kuznik for this title.
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

AUTHOR

Achim Hoffmann

VERSION

@(#) 14.07.25

Content of this wiki page generated with:

o-saft.pl --usr +gen-wiko