Provided by: dacs_1.4.40-2_amd64 
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