O-Saft/Documentation

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    is used as an alias for the
 * program name.
 * program name.

SYNOPSIS

 * o-saft.pl [COMMANDS ..] [OPTIONS ..] target [target target ...]
 * Where [COMMANDS]  and  [OPTIONS]  are described below  and
 * 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.
 * 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,    or     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     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.


 * All output is designed to make it easily parsable by postprocessors.
 * please 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 offered by local SSL implementation.


 * This commands prints the ciphers in format like
 * 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


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

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

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

--user +gen-html

 * Show help text in HTML format.

--user +gen-wiki

 * Show help text in mediawiki format.

--user +gen-cgi

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

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

--s_client

 * Use   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  for details.


 * If used together with --trace, s_client data will also be printed
 * in debug output of.

--no-openssl

 * Do not use external  tool to retrieve informations. Use of
 * 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   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:.
 * Option used with +ciphers  command only.

-V

 * Print list of ciphers in style like:.
 * Option used with +ciphers  command only.

--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  as specified in Net::SSLinfo
 * Default is  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   but more lazy list of
 * huge           all constants  0x03000000 .. 0x0300FFFF
 * safe           all constants  0x03000000 .. 0x032FFFFF
 * full           all constants  0x03000000 .. 0x0300FFFF
 * SSLv2          all ciphers according RFC for SSLv2


 * Note:  is the internal list used for testing SSLv2 ciphers.
 * It does not make sense to use it for other protocols; however ...

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

--no-http

 * Do not make HTTP request.
 * Do not make HTTP request.

--sni

 * Make SSL connection in SNI mode.
 * Make SSL connection in SNI mode.

--no-sni

 * Do not make SSL connection in SNI mode (default: SNI mode).
 * 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.
 * 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).
 * default string (see --no-cert-text TEXT  option).

--no-cert-text TEXT

 * Set TEXT  to be returned from    if no certificate
 * data is collected due to use of --no-cert.
 * data is collected due to use of --no-cert.

--ca-depth INT

 * Check certificate chain to depth INT (like openssl's -verify).
 * 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.
 * 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.
 * Use DIR  where to find CA certificates in PEM format.

--no-nextprotoneg

 * Do not use    option for openssl.
 * Do not use    option for openssl.

--no-reconnect

 * Do not use    option for openssl.
 * Do not use    option for openssl.

--no-tlsextdebug

 * Do not use    option for openssl.
 * Do not use    option for openssl.

--sclient-opt=VALUE

 * Argument or option passed to openssl s_client command.
 * Argument or option passed to openssl s_client command.

Options for checks and results

 * Options used for +check  command:
 * Options used for +check  command:

--enabled

 * Only print result for ciphers accepted by target.
 * Only print result for ciphers accepted by target.

--disabled

 * Only print result for ciphers not accepted by target.
 * Only print result for ciphers not accepted by target.

--ignorecase

 * Checks are done case insensitive.
 * 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.

--short

 * Use short less descriptive text labels for +check   and  +info
 * command.
 * 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.
 * 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.
 * Print scoring results. Default for +check.

--no-score

 * Do not print scoring results.
 * Do not print scoring results.

--sep=CHAR

 * CHAR     will be used as separator between  label and value of the
 * printed results. Default is :
 * 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.
 * 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    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.
 * 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  ..   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
 * See Options for SSL tool

--usr

 * Execute functions defined in o-saft-usr.pm.
 * 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.
 * when this option is given.

--n

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

--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).
 * are missing.
 * Note that --v  is different from  -v  (see above).
 * Note that --v  is different from  -v  (see above).

--v --v

 * Print remotely checked ciphers.
 * Print remotely checked ciphers.

--v --v --v

 * Print remotely checked ciphers one per line.
 * Print remotely checked ciphers one per line.

--v --v --v --v

 * Print processed ciphers (check, skip, etc.).
 * Print processed ciphers (check, skip, etc.).

--trace

 * Print debugging messages.
 * Print debugging messages.

--trace --trace

 * Print more debugging messages and pass  to Net::SSLeay and
 * Net::SSLinfo.
 * Net::SSLinfo.

--trace --trace --trace

 * Print more debugging messages and pass  to Net::SSLeay and
 * Net::SSLinfo.
 * Net::SSLinfo.

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

 * Print processing of all command line arguments.
 * Print processing of all command line arguments.

--trace-arg

 * Print command line argument processing.
 * Print command line argument processing.

--trace-cmd

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

--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=key                       same as --trace-key

--trace=FILE

 * Use FILE instead of the default rc-file (.o-saft.pl, see RC-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.
 * variable names and program flow.

--no-warning

 * Do not print warning messages (**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

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.
 * This applies to all such options, --no-dns is just an example.
 * This applies to all such options, --no-dns is just an example.

Targets
o-saft.pl http://some.tld other.tld:3889/some/path?a=b
 * Following syntax is supported also:
 * Following syntax is supported also:
 * Note that only the hostname and the port are used from an URL.
 * Note that only the hostname and the port are used from an URL.

Options vs. Commands

 * See Options vs. Commands  in  OPTIONS  section above
 * 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.

heartbeat

 * Check if heartbleed extension is supported by target.

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.

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  field
 * Common Name  in    or   field
 * Domain name in  or   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  Cn subject field
 * Organization name must be less to 64 characters
 * Business Category  in   field
 * Registration Number  in   field
 * Address of Place of Business in  field


 * Required are:,  ,


 * Optional are: ,


 * Validation period does not exceed 27 month


 * See LIMITATIONS  also.

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

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


 * MUST have.


 * must not exceed three years for certificate and
 * must not exceed five years for CA certificates.


 * ,    and     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    and     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.


 * is used when no proper informations was found or provided.


 * Replace   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
 * section. Texts of keys in %checks are used for output
 * in  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   is the key used in the internal data structure and
 * is the value to be set for this key. Note that  unknown keys will be
 * ignored silently.


 * If    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    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.    is not used when     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:.


 * 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    instead
 * of.


 * Configurations options must be written like
 * 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    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    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])
 * 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
 * 6. name variants are supported, as long as they are unique
 * 7. hex numbers can be used
 * 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 cipher names.


 * For example the cipher commonly known as  is identified
 * by  (in openssl) and has
 * as constant name. A definition is missing in IANA, but there is
 * It's each tool's responsibility to map the human readable cipher name
 * to the correct (hex, integer) identifier.
 * to the correct (hex, integer) identifier.


 * For example Firefox uses ,  which is what?


 * Furthermore, there are different acronyms for the same thing in use.
 * For example    and     both mean.
 * Comments in the openssl sources mention this. And for curiosity these
 * sources use both in cypher names but allow only   as shortcut in
 * openssl's `ciphers' command.


 * Next example is    which is also known as    or
 * or    or.


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

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

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
 * 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:
 * as they my trigger the ---header  option unintentional.
 * 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   and
 * as used in the output for +cipher  command.

+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:  >>.
 * 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   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    variable.     will
 * be prepended by following paths:


 * ./lib
 * INSTALL_PATH
 * INSTALL_PATH/lib
 * INSTALL_PATH/lib


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

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
 * itself recursively with all given options, except the option
 * itself. The environment variables    and    are
 * set before executing as follows:


 * prepend    with all values given with  --exe=PATH
 * prepend    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    (see above).


 * Note that    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  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   (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!

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    in texts.
 * Some parameters, in particular those of HTTP responses,  are written
 * as  .  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:




 * Addition text for verbosity (--v options).


 * #[variable name]


 * Internal variable name (--trace-key options).


 * #o-saft.pl::
 * #Net::SSLinfo::


 * Trace information for --trace options.




 * Trace information from    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=


 * 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

o-saft.pl +info some.tld --trace-key
 * Show internal variable names in output


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


 * +cipherall and some proxy functionality implemented by Torsten Gigler.


 * For re-writing some docs in proper English, thanks to Robb Watson.


 * Code to check heartbleed vulnerability adapted from
 * Steffen Ullrich (08. April 2014):
 * https://github.com/noxxi/p5-scripts/blob/master/check-ssl-heartbleed.pl

AUTHOR
Achim Hoffmann

VERSION

 * @(#) 14.07.25

Content of this wiki page generated with: o-saft.pl --usr +gen-wiki