This site is the archived OWASP Foundation Wiki and is no longer accepting Account Requests.
To view the new OWASP Foundation website, please visit https://owasp.org

O-Saft/Documentation

From OWASP
Revision as of 23:28, 1 June 2014 by Achim (talk | contribs) (→‎--format=FORM)

Jump to: navigation, search

O-Saft

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

o-saft.pl --help

NAME

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

DESCRIPTION

This tools lists information about remote target's SSL certificate
and tests the remote target according given list of ciphers.
Note: Throughout this description $0 is used as an alias for the
program name o-saft.pl .

SYNOPSIS

o-saft.pl [COMMANDS ..] [OPTIONS ..] target [target target ...]
Where [COMMANDS] and [OPTIONS] are described below and target
is a hostname either as full qualified domain name or as IP address.
Multiple commands and targets may be combined.
All commands and options can also be specified in a rc-file, see
RC-FILE below.

QUICKSTART

Before going into a detailed description of the purpose and usage,
here are some examples of the most common use cases:
  • Show supported (enabled) ciphers of target:
   o-saft.pl +cipher --enabled example.tld
  • Show details of certificate and connection of target:
   o-saft.pl +info example.tld
  • Check certificate, ciphers and SSL connection of target:
   o-saft.pl +check example.tld
  • List all available commands:
   o-saft.pl --help=commands
For more specialised test cases, refer to the COMMANDS and OPTIONS
sections below.
If no command is given, +cipher is used.

WHY?

Why a new tool for checking SSL security and configuration when there
are already a dozen or more such tools in existence (circa 2012)?
Currently available tools suffer from some or all of following issues:
* lack of tests of unusual ciphers
* lack of tests of unusual SSL certificate configurations
* may return different results for the same checks on a given target
* missing tests for modern SSL/TLS functionality
* missing tests for specific, known SSL/TLS vulnerabilities
* no support for newer, advanced, features e.g. CRL, OCSP, EV
* limited capability to create your own customised tests
Other reasons or problems are that they are either binary and hence
not portable to other (newer) platforms.
In contrast to (all?) most other tools, including openssl, it can be
used to `ask simple questions' like `does target support STS' just by
calling:
   o-saft.pl +cipher +hsts_sts example.tld
For more, please see EXAMPLES section below.

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
Following (summary, internal) commands are simply a shortcut for
a list of other commands. For details of the list use:
   o-saft.pl --help=intern
+check
Check the SSL connection for security issues. This is the same as
+info +cipher +sizes --sslv2 --sslv3 --tls1
but also gives some kind of scoring for security issues if any.
+http
Perform HTTP checks (like STS, redirects etc.).
+info
Overview of most important details of the SSL connection.
Use --v option to show details also, which span multiple lines.
+info--v
Overview of all details of the SSL connection. This is a shortcut
for all commands listed below but not including +cipher.
This command is intended for debugging as it prints some details
from the used Net::SSLinfo module.
+quick
Quick overview of checks. Implies --enabled and --short.
+sts +hsts
Various checks according STS HTTP header.
This option implies --http, means that --no-http is ignored.
+sni
Check for Server Name Indication (SNI) usage.
+sni_check +check_sni
Check for Server Name Indication (SNI) usage and validity of all
names (CN, subjectAltName, FQDN, etc.).
+bsi
Various checks according BSI TR-02102-2 compliance.
+ev
Various checks according certificate's extended Validation (EV).
Hint: use option --v --v to get information about failed checks.
+sizes
Check length, size and count of some values in the certificate.
+s_client
Dump data retrieved from openssl s_client ... call. Should be
used for debugging only.
It can be used just like openssl itself, for example:
        openssl s_client -connect host:443 -no_sslv2
+dump
Dumps internal data for SSL connection and target certificate.
This is mainly for debugging and should not be used together with
other commands (except +cipher).
Each key-value pair is enclosed in #{ and #} .
Using --trace --trace dumps data of Net::SSLinfo too.
+exec
Command used internally when requested to use other libraries.
This command should not be used directly.
Commands to test target's ciphers
+cipher
Check target for ciphers, either all ciphers or ciphers specified
with --cipher=* option.
Note that ciphers not supported by the local SSL implementation
are not checked by default, use --local option for that.
+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
--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
--cipher=CIPHER
CIPHER can be any string accepeted by openssl or following:
yeast use all ciphers from list defined herein, see +list
Beside the cipher names accepted by openssl, CIPHER can be the name
of the constant or the (hex) value as defined in openssl's files.
Currently supported are the names and constants of openssl 1.0.1c .
Example:
        --cipher=DHE_DSS_WITH_RC4_128_SHA
        --cipher=0x03000066
        --cipher=66
will be mapped to DHE-DSS-RC4-SHA
Note: if more than one cipher matches, just one will be selected.
Default is ALL:NULL:eNULL:aNULL:LOW as specified in Net::SSLinfo
--no-md5-cipher
Do not use *-MD5 ciphers for other protocols than SSLv2.
This option is only effective with +cipher command.
The purpose is to avoid warnings from IO::Socket::SSL like:
        Use of uninitialized value in subroutine entry at lib/IO/Socket/SSL.pm line 430.
which occours with some versions of IO::Socket::SSL when a *-MD5
ciphers will be used with other protocols than SSLv2.
Note that these ciphers will be checked for SSLv2 only.
--SSL, -protocol SSL
--no-SSL
SSL can be any of: ssl, ssl2, ssl3, sslv2, sslv3, tls1,
tls1, tls11, tls1.1, tls1-1, tlsv1, tlsv11, tlsv1.1, tlsv1-1
(and similar variants for tlsv1.2).
For example --tls1 --tlsv1 --tlsv1_1 are all the same.
(--SSL variants): Test ciphers for this SSL/TLS version.
(--no-SSL variants): Don't test ciphers for this SSL/TLS version.
--nullsslv2
This option forces to assume that SSLv2 is enabled even if the
target does not accept any ciphers.
The target server may accept connections with SSLv2 but not allow
any cipher. Some checks verify if SSLv2 is enabled at all, which
then would result in a failed test.
The default behaviour is to assume that SSLv2 is not enabled if no
ciphers are accepted.
--http
Make a HTTP request if cipher is supported.
If used twice debugging will be enabled using environment variable
HTTPS_DEBUG .
--no-http
Do not make HTTP request.
--sni
Make SSL connection in SNI mode.
--no-sni
Do not make SSL connection in SNI mode (default: SNI mode).
--force-sni
Do not check if SNI seems to be supported by Net::SSLeay.
Older versions of openssl and its libries do not support SNI or the
SNI support is implemented buggy. By default it's checked if SNI is
properly supported. With this option this check can be disabled.
Be warned that this may result in improper results.
--no-cert
Do not get data from target's certificate, return empty string.
--no-cert --no-cert
Do not get data from target's certificate, return Net::SSLinfo.pm's
default string (see --no-cert-text TEXT option).
--no-cert-text TEXT
Set TEXT to be returned from Net::SSLinfo.pm if no certificate
data is collected due to use of --no-cert.
--ca-depth INT
Check certificate chain to depth INT (like openssl's -verify).
--ca-file FILE
Use FILE with bundle of CAs to verify target's certificate chain.
--ca-path DIR
Use DIR where to find CA certificates in PEM format.
--no-nextprotoneg
Do not use -nextprotoneg option for openssl.
--no-reconnect
Do not use -reconnect option for openssl.
--no-tlsextdebug
Do not use -tlsextdebug option for openssl.
--sclient-opt=VALUE
Argument or option passed to openssl s_client command.
Options for checks and results
Options used for +check command:
--enabled
Only print result for ciphers accepted by target.
--disabled
Only print result for ciphers not accepted by target.
--ignorecase
Checks are done case insensitive.
--no-ignorecase
Checks are done case sensitive. Default: case insensitive.
Currently only checks according CN, alternate names in the target's
certificate compared to the given hostname are effected.
Options for output format
--short
Use short less descriptive text labels for +check and +info
command.
--legacy=TOOL
For compatibility with other tools, the output format used for the
result of the +cipher command can be adjusted to mimic the format
of other SSL testing tools.
The argument to the --legacy=TOOL option is the name of the tool
to be simulated.
Following TOOLs are supported:
   sslaudit:     format of output similar to  sslaudit
   sslcipher:    format of output similar to  ssl-cipher-check
   ssldiagnos:   format of output similar to  ssldiagnos
   sslscan:      format of output similar to  sslscan
   ssltest:      format of output similar to  ssltest
   ssltestg:     format of output similar to  ssltest -g
   ssltest-g:    format of output similar to  ssltest -g
   sslyze:       format of output similar to  sslyze
   ssl-cipher-check:    same as sslcipher:
   ssl-cert-check:  format of output similar to  ssl-cert-check
   testsslserver:format of output similar to  TestSSLServer.jar
   thcsslcHeck:  format of output similar to  THCSSLCheck
Note that these legacy formats only apply to output of the checked
ciphers. Other texts like headers and footers are adapted slightly.
Please don't expect identical output as the TOOL, it's a best guess
and should be parsable in a very similar way.
TOOL may also be set to any of following internally defined values:
compact: mainly avoid tabs and spaces
format is as follows
Some Label:<-- anything right of colon is data
full: pretty print: each label in its own line, followed
by data in next line prepended by tab character
(useful for +info only)
quick: use tab as separator; print ciphers with bit length
(--tab not necessary)
simple: default format
--format=FORM
FORM may be one of follwoing:
raw print raw data as passed from Net::SSLinfo
Note: all data is printed as is, without additional
label or formatting. It is recommended to use this
option in conjunction with exactly one command.
Otherwise the user needs to know how to `read' the
printed data.
hex convert some data to hex: 2 bytes separated by :
--header
Print formatting header. Default for +check, +info, +quick.
and +cipher only.
--no-header
Do not print formatting header.
Usefull if raw output should be passed to other programs.
--score
Print scoring results. Default for +check.
--no-score
Do not print scoring results.
--separator=CHAR
--sep=CHAR
CHAR will be used as separator between label and value of the
printed results. Default is  :
--tab
TAB character (0x09, \t) will be used as separator between label
and value of the printed results.
As label and value are already separated by a TAB character, this
options is only useful in conjunction with the --legacy=compact
option.
--showhost
Prefix each printed line with the given hostname (target).
The hostname will be followed by the separator character.
--win-CR
Print windows-Style with CR LF as end of line. Default is NL only.
Options for compatibility with other programs
Please see other programs for detailed description (if not obvious:).
Note that only the long form options are accepted as most short form
options are ambiguous.
--capath DIR (curl) same as --ca-path DIR
--CApath=DIR (openssl) same as --ca-path DIR
--ca-directory=DIR (wget) same as --ca-path DIR:
--cacert FILE (curl) same as --ca-file DIR
--CAfile=FILE (openssl) same as --ca-file DIR
--ca-certificate=FILE (wget) same as --ca-path DIR
-c PATH (ssldiagnos) same as --ca-path DIR
--hide_rejected_ciphers (sslyze) same as --disabled
--http_get (ssldiagnos) same as --http
--printcert (ssldiagnos) same as +ciphers
--protocol SSL (ssldiagnos) same as --SSL
--no-failed (sslscan) same as --disabled
--regular (sslyze) same as --http
--reneg (sslyze) same as +renegotiation
--resum (sslyze) same as +resumtion
-h, -h=HOST (various tools) same as --host HOST
-p, -p=PORT (various tools) same as --port PORT
-t HOST (ssldiagnos) same as --host HOST
-noSSL same as --no-SSL
-no_SSL same as --no-SSL
For definition of SSL see --SSL and --no-SSL above

.

--insecure (cnark.pl) ignored
--nopct --nocolor (ssldiagnos) ignored
--ism, --pci -x (ssltest.pl) ignored
--timeout, --grep (ssltest.pl) ignored
-r, -s, -t (ssltest.pl) ignored
-connect, --fips, -H, -u, -url, -U ignored
Options for customization
For general descriptions please see CUSTOMIZATION section below.
--cfg_cmd=CMD=LIST
Redefine list of commands. Sets  %cfg{cmd-CMD} to LIST. Commands
are written without the leading +.
CMD can be any of: bsi, check, http, info, quick, sni, sizes
Example:
--cfg_cmd=sni=sni hostname
To get a list of commands and their settings, use:
   o-saft.pl --help=intern
Main purpose is to reduce list of commands or print them sorted.
--cfg_score=KEY=SCORE
Redefine value for scoring. Sets  %checks{KEY}{score} to SCORE.
Most score values are set to 10 by default. Values 0 .. 10

0 are

allowed.
To get a list of current score settings, use:
   o-saft.pl --help=score
For deatils how scoring works, please see SCORING section.
Use the --trace-key option for the +info and/or +check
command to get the values for KEY.
--cfg_checks=KEY=TEXT --cfg_data=KEY=TEXT
Redefine texts used for labels in output. Sets  %data{KEY}{txt} or
 %checks{KEY}{txt} to TEXT.
To get a list of preconfigured labels, use:
   o-saft.pl --help=cfg_checks
   o-saft.pl --help=cfg_data
--cfg_text=KEY=TEXT
Redefine general texts used in output. Sets  %text{KEY} to TEXT.
To get a list of preconfigured texts, use:
   o-saft.pl --help=cfg_text
Note that \n, \r and \t are replaced by the corresponding character
when read from RC-FILE.
--call=METHOD
See Options for SSL tool
--usr
Execute functions defined in o-saft-usr.pm.
Options for tracing and debugging
--n
Do not execute, just show commands (only useful in conjunction with
using openssl).
--v
--verbose
Print more information about checks.
Note that this option should be first otherwise some debug messages
are missing.
--v --v
Print remotely checked ciphers.
--v --v --v
Print remotely checked ciphers one per line.
--v --v --v --v
Print processed ciphers (check, skip, etc.).
--trace
Print debugging messages.
--trace --trace
Print more debugging messages and pass trace=2 to Net::SSLeay and
Net::SSLinfo.
--trace --trace --trace
Print more debugging messages and pass trace=3 to Net::SSLeay and
Net::SSLinfo.
--trace --trace --trace --trace
Print processing of all command line arguments.
--trace--
--trace-arg
Print command line argument processing.
--trace-cmd
Trace execution of command processing (those given as +*).
--trace@
--trace-key
Print some internal variable names in output texts (labels).
Variable names are prefixed to printed line and enclosed in # .
Example without --trace-key :
      Certificate Serial Number:          deadbeef
Example with --trace-key :
      #serial#          Certificate Serial Number:          deadbeef
--trace=VALUE
--trace=1 same as --trace
--trace=2 same as --trace --trace
--trace=arg same as --trace-arg
--trace=cmd same as --trace-cmd
--trace=key same as --trace-key
--trace=FILE
Use FILE instead of the default rc-file (.o-saft.pl, see RC-FILE).
--trace-sub +traceSUB
Print formatted list of internal functions with their description.
Not to be intended in conjunction with any target check.
--trace vs. --v
While --v is used to print more data, --trace is used to print
more information about internal data such as procedure names and/or
variable names and program flow.
--no-warning
Do not print warning messages (**WARNING:).
Options vs. Commands
For compatibility with other programs and lazy users, some arguments
looking like options are silently taken as commands. This means that
--THIS becomes +THIS then. These options are:
--help
--abbr
--todo
--chain
--default
--fingerprint
--list
--version
Take care that this behaviour may be removed in future versions as it
conflicts with those options and commands which actually exist, like:
 --sni  vs.  +sni

LAZY SYNOPSIS

We support following options, which are all identical, for lazy users
and for compatibility with other programs.
Option Variants
--port PORT
--port=PORT
This applies to most such options, --port is just an example.
When used in the RC-FILE, the --OPTION=VALUE variant must be used.
Option Names
Dash - and/or underscore _ in option names are optional.
--no-dns
--no_dns
--nodns
This applies to all such options, --no-dns is just an example.
Targets
Following syntax is supported also:
   o-saft.pl http://some.tld other.tld:3889/some/path?a=b
Note that only the hostname and the port are used from an URL.
Options vs. Commands
See Options vs. Commands in OPTIONS section above

CHECKS

Content of this wiki page generated with: 

o-saft.pl --help=wiki

Retrieved from "https://wiki.owasp.org/index.php?title=O-Saft/Documentation&oldid=176157"