Difference between revisions of "O-Saft/Documentation"

Revision as of 21:57, 1 June 2014

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.

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.

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

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.

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

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

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

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

Options for SSL connection to target

Content of this wiki page generated with:

o-saft.pl --help=wiki