sslclient

SSLCLIENT(1)                  DACS Commands Manual                  SSLCLIENT(1)



NAME
       sslclient - an SSL/TLS client

SYNOPSIS
       sslclient [dacsoptions[1]] [-caf | --ca_cert_file filename]
                 [-cad | --ca_cert_dir dirname]
                 [-ccf | --cert_chain_file filename]
                 [-C | --ciphers cipherstring]
                 [--disable-sni]
                 [[-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 ]...]
                 [-sni | --enable-sni]
                 [-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/TLS client. After establishing a
       bidirectional SSL/TLS connection with an SSL/TLS server, it forwards its
       standard input to the SSL/TLS server and writes data produced by the
       SSL/TLS 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_port portnum),
       that is used; failing that, the default SSL/TLS 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/TLS 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 SSL/TLS 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. Also see the
           --with-default-cipher-list[13] build option.

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

       --disable-sni
           This flag tells sslclient not to use Server Name Indication (SNI), a
           TLS extension.

       -h
       --help
           Print a usage synopsis, which includes the default cipher list.

       -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/TLS 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[14] for the
           matching algorithm.

       -sni
       --enable-sni
           When it is provided by its OpenSSL[4] library, the Server Name
           Indication (SNI) TLS extension is used by default, so it should not
           be necessary to specify this flag. Refer to RFC 6066[15] for details.

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

           % printf "GET https://example.com:443 HTTP/1.0\r\n\r\n" | sslclient example.com:443


           Tip
           When connecting to a web server, note that the request-line and every
           header-field should be terminated by a CRLF (carriage return, line
           feed/newline), otherwise the web server may respond with a 400 (Bad
           Request) error or a 301 (Moved Permanently) redirect. Apparently,
           Apache has become more strict in this regard[16]. In particular, this
           may trip you up if you use sslclient interactively, since your input
           will end with only a newline. Refer to RFC 7230[17], Section 3.

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/TLS
       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/TLS. This mode might run on a firewall host to
       forward an approved incoming SSL/TLS 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)[18], stunnel(1)[19],
       curl(1)[20], sslwrap(1)[21], and others, and regex(3)[22].

       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[23], Netscape SSL 3.0
       Specification[24], RFC 2246[25], and RFC 6066[15].

AUTHOR
       Distributed Systems Software (www.dss.ca[26])

COPYING
       Copyright © 2003-2018 Distributed Systems Software. See the LICENSE[27]
       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/TLS 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. --with-default-cipher-list
           http://dacs.dss.ca/man/dacs.install.7.html#build_flag_--with-default-cipher-list

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

       15. RFC 6066
           http://www.rfc-editor.org/rfc/rfc6066.txt

       16. Apache has become more strict in this regard
           https://bz.apache.org/bugzilla/show_bug.cgi?id=60695

       17. RFC 7230
           http://www.rfc-editor.org/rfc/rfc7230.txt

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

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

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

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

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

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

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

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

       26. www.dss.ca
           http://www.dss.ca

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



DACS 1.4.40                        02/19/2019                       SSLCLIENT(1)