sslclient1

Usage

Overview

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.

% openssl x509 -noout -text < cert.crt

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

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.

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