Provided by: dacs_1.4.28b-3ubuntu1_amd64 bug

NAME

       sslclient - an SSL client

SYNOPSIS

       sslclient [dacsoptions[1]] [-caf | --ca_cert_file filename]
                 [-cad | --ca_cert_dir dirname]
                 [-ccf | --cert_chain_file filename]
                 [-C | --ciphers cipherstring]
                 [[-dvp] | [--default_verify_paths] cipherstring]
                 [-h | --help] [-kf | --key_file filename]
                 [-kft | --key_file_type pem | asn1]
                 [-p | -sp | [--server_port] portnum]
                 [-r | --random filename]
                 [[-sm | --server_match regex ]...]
                 [-vd | --verify_depth depth]
                 [-vt | --verify_type none | peer] [--] server [:port ]

DESCRIPTION

       This program is part of the DACS suite. It can be used with the usual DACS command line
       options (dacsoptions[1]), provided they all appear before the program-specific flags (note
       that the -un flag can be used to suppress configuration file processing).  sslclient is
       also used by the dacshttp(1)[2] command and by requests generated internally by DACS
       components.

       The sslclient utility acts as an SSL client. After establishing a bidirectional SSL
       connection with an SSL server, it forwards its standard input to the SSL server and writes
       data produced by the SSL server to sslclient's standard output.

       sslclient connects to server (a domain name or IP address). If a port number suffix is
       given (port), it is used; otherwise, if a port number is specified as a separate command
       line argument (--server_portportnum), that is used; failing that, the default SSL port for
       https (443)[3] is used.

       The program reads from its standard input and the server asynchronously (using
       non-blocking I/O). Note that the server side might need to see end-of-file on its input
       before its output is returned to sslclient.

       This program's underlying SSL functionality is provided by OpenSSL[4].

OPTIONS

       sslclient recognizes these options:

       -caf filename
       --ca_cert_file filename
           This identifies filename as a file of CA certificates in PEM format. This is the
           CAfile argument to the OpenSSL[4]SSL_CTX_load_verify_locations()[5] function. It is
           similar to mod_ssl's[6]SSLCACertificateFile[7] directive, except that it is used to
           verify the server's SSL certificate.

       -cad dirname
       --ca_cert_dir dirname
           This identifies dirname as a directory containing CA certificates in PEM format, one
           certificate per file. This is the CApath argument to the
           OpenSSL[4]SSL_CTX_load_verify_locations()[5] function. It is similar to
           mod_ssl's[6]SSLCACertificatePath[8] directive, except that it is used to verify the
           server's certificate.

       -ccf filename
       --cert_chain_file filename
           This causes the client certificate chain to be loaded from filename, a file containing
           certificates in PEM format. This is the file argument to the
           OpenSSL[4]SSL_CTX_use_certificate_chain_file()[9] function. It is similar to
           mod_ssl's[6]SSLCACertificateChainFile[10] directive, except that it is used for the
           client's chain.

               Tip
               If you want the client certificate to be sent you must also specify the -kf flag.

       -C cipherstring
       --ciphers cipherstring
           This sets the list of ciphers to be used to cipherstring. This is the str argument to
           the OpenSSL[4]SSL_CTX_set_cipher_list()[11] function. It is similar to
           mod_ssl's[6]SSLCipherSuite[12] directive.

       -dvp
       --default_verify_paths
           This flag tells sslclient to use default locations for finding CA certificates. It
           results in a call to the OpenSSL[4]SSL_CTX_set_default_verify_paths() function.

       -h
       --help
           Print a usage synopsis.

       -kf filename
       --key_file filename
           This sets sslclient's private key to the first private key found in filename. This is
           the file argument to the OpenSSL[4]SSL_CTX_usePrivateKey_file() function. The default
           private key file type is PEM. If the key has been encrypted, the program will prompt
           for the passphrase.

       -kft type
       --key_file_type type
           The private key file type is set to type, which must be either pem or asn1 (case
           insensitive). The default private key file type is PEM.

       -p portnum
       -sp portnum
       --server_port portnum
           Unless appended to the server argument, portnum is the port number to use, overriding
           the default port (443).

       -r filename
       --random filename
           Seed material for the PRNG is read from filename. This is the filename argument to the
           OpenSSL[4]RAND_load_file() function.

       -sm regex
       --server_match regex
           This argument, which may be repeated, specifies a constraint on the server's identity
           by matching an attribute value in the server's certificate against regex. These tests
           are made immediately after an SSL connection is established. Each regex is an IEEE Std
           1003.2 ("POSIX.2") regular expression with extended expressions and case insensitivity
           (REG_EXTENDED | REG_ICASE). See below[13] for the matching algorithm.

       -vd depth
       --verify_depth depth
           This sets the maximum depth for certificate chain verification to depth. This is the
           depth argument to the OpenSSL[4]SSL_CTX_set_verify_depth() function.

       -vt type
       --verify_type type
           This sets the verification mode to type, which must be either none or peer (case
           insensitive). This is the mode argument to the OpenSSL[4]SSL_CTX_set_verify()
           function.

       --
           This argument explicitly marks the end of the flags.

       The DACS-v (or --verbose) flag causes the program to show some of the server's SSL
       certificate, print feedback about regular expression matching, and so on. If sslclient is
       not doing what you expect, try using this flag.

   Server Identity Verification
       If the server presents a valid SSL (X.509) certificate, a set of checks is applied to it
       to help ensure that sslclient is communicating with the intended entity. Verification is
       successful and checking is terminated as soon as any test is successful. If no test
       succeeds, the program terminates immediately.

           Tip
           You can use a command like the following one to display an X.509 certificate to stdout
           in text form:

               % openssl x509 -noout -text < cert.crt

           Here, cert.crt is the certificate to display.

       The server certificate's subjectAltName extension fields have the format
       field-name:field-value. For each such field, tests are made in the following sequence:

        1. the entire field is matched against each of the regular expressions given on the
           command line.

        2. if the previous test failed and field-name is "DNS" (exact match), it is compared case
           insensitively to the server's name (as given on the command line).

        3. if the previous test failed and if the field-name is "IP Address" (exact match), it is
           compared to the server's name (exact match), which is assumed to be an IP address (as
           given on the command line).

       If the above procedure is unsuccessful and the server certificate's commonName attribute
       value is available, it is matched against each of the regular expressions given on the
       command line.

EXAMPLES

       The following command line attempts to connect to port 443 at example.com and prints to
       stdout the server's response to a request for the home page:

           % perl -e 'printf "GET / HTTP/1.0\n\n";' | sslclient example.com:443

DIAGNOSTICS

       When used with DACS logging configured, messages are directed to a log file, otherwise
       error messages and verbose output are written to stderr. The program exits 0 if everything
       was fine, 1 if an error occurred.

NOTES

       A wrapper mode of operation might be useful.

       It would also be useful to have a mode where it listens for an SSL connection for input
       (rather than its standard input) and then relays data over that connection to a specified
       server, possibly but not necessarily via SSL. This mode might run on a firewall host to
       forward an approved incoming SSL connection (presumably authenticated by a client
       certificate, and possibly by a DACS ruleset) to a service running on an interior host, for
       instance.

SEE ALSO

       dacshttp(1)[2], openssl(1)[4], s_client(1)[14], stunnel(1)[15], curl(1)[16],
       sslwrap(1)[17], and others, and regex(3)[18].

       A variety of reference material on SSL/TLS is available. Perhaps best is Network Security
       with OpenSSL by John Viega, Matt Messier, and Pravir Chandra, O'Reilly & Associates, Inc.,
       2002. Also useful are SSL/TLS Strong Encryption: An Introduction[19], Netscape SSL 3.0
       Specification[20], and RFC 2246[21].

AUTHOR

       Distributed Systems Software (www.dss.ca[22])

COPYING

       Copyright2003-2013 Distributed Systems Software. See the LICENSE[23] file that accompanies
       the distribution for licensing information.

NOTES

        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. dacshttp(1)
           http://dacs.dss.ca/man/dacshttp.1.html

        3. default SSL port for https (443)
           http://www.iana.org/assignments/port-numbers

        4. OpenSSL
           http://www.openssl.org

        5. SSL_CTX_load_verify_locations()
           http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html

        6. mod_ssl's
           http://httpd.apache.org/docs-2.2/mod/mod_ssl.html

        7. SSLCACertificateFile
           http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#sslcacertificatefile

        8. SSLCACertificatePath
           http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#sslcacertificatepath

        9. SSL_CTX_use_certificate_chain_file()
           http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html

       10. SSLCACertificateChainFile
           http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#sslcacertificatechainfile

       11. SSL_CTX_set_cipher_list()
           http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html

       12. SSLCipherSuite
           http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#sslciphersuite

       13. below
           http://dacs.dss.ca/man/#verificaton

       14. s_client(1)
           http://www.openssl.org/docs/apps/s_client.html

       15. stunnel(1)
           http://www.stunnel.org

       16. curl(1)
           http://directory.fsf.org/project/curl

       17. sslwrap(1)
           http://www.rickk.com/sslwrap

       18. regex(3)
           http://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE&format=html

       19. SSL/TLS Strong Encryption: An Introduction
           http://httpd.apache.org/docs-2.2/ssl/ssl_intro.html

       20. Netscape SSL 3.0 Specification
           http://web.archive.org/web/20070717014933rn_1/wp.netscape.com/eng/ssl3//

       21. RFC 2246
           http://www.rfc-editor.org/rfc/rfc2246.txt

       22. www.dss.ca
           http://www.dss.ca

       23. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE