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.

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.


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

+list

 * Show all ciphers known by this tool.  This includes cryptogrphic
 * details of the cipher and some internal details about the rating.


 * 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

 * Check for SSL connection in SNI mode and if given  FQDN  matches
 * certificate's subject.


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


 * The rating is mainly based on the information given in
 * http://ssllabs.com/.....

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

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

+cipherall

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

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

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

ssleay:  use installed SSLeay library for perl local:   use installed openssl (found via PATH envrionment variable) Note that this disables use of SSLeay x86_32:  use  ** NOT YET IMPLEMENTED ** x86_64:  use  ** NOT YET IMPLEMENTED ** x86Mac:  use  ** NOT YET IMPLEMENTED ** arch:    use  ** NOT YET IMPLEMENTED **

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

Options for SSL connection to target
Content of this wiki page generated with: o-saft.pl --help=wiki