.\" Copyright (c) 2003-2012
.\" Distributed Systems Software.  All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\"     Title: sslclient
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Commands Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "SSLCLIENT" "1" "02/19/2019" "DACS 1.4.40" "DACS Commands Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sslclient \- an SSL/TLS client
.SH "SYNOPSIS"
.HP \w'\fBsslclient\fR\ 'u
\fBsslclient\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR] [\fB\-caf\fR\ |\ \fB\-\-ca_cert_file\fR\ \fIfilename\fR]
.br
[\fB\-cad\fR\ |\ \fB\-\-ca_cert_dir\fR\ \fIdirname\fR]
.br
[\fB\-ccf\fR\ |\ \fB\-\-cert_chain_file\fR\ \fIfilename\fR]
.br
[\fB\-C\fR\ |\ \fB\-\-ciphers\fR\ \fIcipherstring\fR]
.br
[\fB\-\-disable\-sni\fR] [[\fB\-dvp\fR]\ |\ [\fB\-\-default_verify_paths\fR]\ \fIcipherstring\fR]
.br
[\fB\-h\fR\ |\ \fB\-\-help\fR] [\fB\-kf\fR\ |\ \fB\-\-key_file\fR\ \fIfilename\fR]
.br
[\fB\-kft\fR\ |\ \fB\-\-key_file_type\fR\ pem\ |\ asn1]
.br
[\fB\-p\fR\ |\ \fB\-sp\fR\ |\ [\fB\-\-server_port\fR]\ \fIportnum\fR]
.br
[\fB\-r\fR\ |\ \fB\-\-random\fR\ \fIfilename\fR]
.br
[[\fB\-sm\fR\ |\ \fB\-\-server_match\fR\ \fIregex\fR\ ]...]
.br
[\fB\-sni\fR\ |\ \fB\-\-enable\-sni\fR]
.br
[\fB\-vd\fR\ |\ \fB\-\-verify_depth\fR\ \fIdepth\fR]
.br
[\fB\-vt\fR\ |\ \fB\-\-verify_type\fR\ none\ |\ peer] [\fB\-\-\fR] \fIserver\fR\ [:\fIport\fR\ ] 
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&. It can be used with the usual
\fBDACS\fR
command line options (\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2),
\fIprovided they all appear before the program\-specific flags\fR
(note that the
\fB\-un\fR
flag can be used to suppress configuration file processing)\&.
\fBsslclient\fR
is also used by the
\m[blue]\fBdacshttp(1)\fR\m[]\&\s-2\u[2]\d\s+2
command and by requests generated internally by
\fBDACS\fR
components\&.
.PP
The
\fBsslclient\fR
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
\fBsslclient\*(Aqs\fR
standard output\&.
.PP
\fBsslclient\fR
connects to
\fIserver\fR
(a domain name or IP address)\&. If a port number suffix is given (\fIport\fR), it is used; otherwise, if a port number is specified as a separate command line argument (\fB\-\-server_port\fR
\fIportnum\fR), that is used; failing that, the
\m[blue]\fBdefault SSL/TLS port for https (443)\fR\m[]\&\s-2\u[3]\d\s+2
is used\&.
.PP
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
\fBsslclient\fR\&.
.PP
This program\*(Aqs underlying SSL/TLS functionality is provided by
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[4]\d\s+2\&.
.SH "OPTIONS"
.PP
\fBsslclient\fR
recognizes these options:
.PP
\fB\-caf\fR \fIfilename\fR
.br
\fB\-\-ca_cert_file\fR \fIfilename\fR
.RS 4
This identifies
\fIfilename\fR
as a file of CA certificates in PEM format\&. This is the
\fICAfile\fR
argument to the
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[4]\d\s+2
\m[blue]\fB\fBSSL_CTX_load_verify_locations()\fR\fR\m[]\&\s-2\u[5]\d\s+2
function\&. It is similar to
\m[blue]\fBmod_ssl\*(Aqs\fR\m[]\&\s-2\u[6]\d\s+2
\m[blue]\fBSSLCACertificateFile\fR\m[]\&\s-2\u[7]\d\s+2
directive, except that it is used to verify the server\*(Aqs SSL certificate\&.
.RE
.PP
\fB\-cad\fR \fIdirname\fR
.br
\fB\-\-ca_cert_dir\fR \fIdirname\fR
.RS 4
This identifies
\fIdirname\fR
as a directory containing CA certificates in PEM format, one certificate per file\&. This is the
\fICApath\fR
argument to the
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[4]\d\s+2
\m[blue]\fB\fBSSL_CTX_load_verify_locations()\fR\fR\m[]\&\s-2\u[5]\d\s+2
function\&. It is similar to
\m[blue]\fBmod_ssl\*(Aqs\fR\m[]\&\s-2\u[6]\d\s+2
\m[blue]\fBSSLCACertificatePath\fR\m[]\&\s-2\u[8]\d\s+2
directive, except that it is used to verify the server\*(Aqs certificate\&.
.RE
.PP
\fB\-ccf\fR \fIfilename\fR
.br
\fB\-\-cert_chain_file\fR \fIfilename\fR
.RS 4
This causes the client certificate chain to be loaded from
\fIfilename\fR, a file containing certificates in PEM format\&. This is the
\fIfile\fR
argument to the
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[4]\d\s+2
\m[blue]\fB\fBSSL_CTX_use_certificate_chain_file()\fR\fR\m[]\&\s-2\u[9]\d\s+2
function\&. It is similar to
\m[blue]\fBmod_ssl\*(Aqs\fR\m[]\&\s-2\u[6]\d\s+2
\m[blue]\fBSSLCACertificateChainFile\fR\m[]\&\s-2\u[10]\d\s+2
directive, except that it is used for the client\*(Aqs chain\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
If you want the client certificate to be sent you must also specify the
\fB\-kf\fR
flag\&.
.sp .5v
.RE
.RE
.PP
\fB\-C\fR \fIcipherstring\fR
.br
\fB\-\-ciphers\fR \fIcipherstring\fR
.RS 4
This sets the list of SSL/TLS ciphers to be used to
\fIcipherstring\fR\&. This is the
\fIstr\fR
argument to the
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[4]\d\s+2
\m[blue]\fB\fBSSL_CTX_set_cipher_list()\fR\fR\m[]\&\s-2\u[11]\d\s+2
function\&. It is similar to
\m[blue]\fBmod_ssl\*(Aqs\fR\m[]\&\s-2\u[6]\d\s+2
\m[blue]\fBSSLCipherSuite\fR\m[]\&\s-2\u[12]\d\s+2
directive\&. Also see the
\m[blue]\fB\fB\-\-with\-default\-cipher\-list\fR\fR\m[]\&\s-2\u[13]\d\s+2
build option\&.
.RE
.PP
\fB\-dvp\fR
.br
\fB\-\-default_verify_paths\fR
.RS 4
This flag tells
\fBsslclient\fR
to use default locations for finding CA certificates\&. It results in a call to the
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[4]\d\s+2
\fBSSL_CTX_set_default_verify_paths()\fR
function\&.
.RE
.PP
\fB\-\-disable\-sni\fR
.RS 4
This flag tells
\fBsslclient\fR
not to use Server Name Indication (SNI), a TLS extension\&.
.RE
.PP
\fB\-h\fR
.br
\fB\-\-help\fR
.RS 4
Print a usage synopsis, which includes the default cipher list\&.
.RE
.PP
\fB\-kf\fR \fIfilename\fR
.br
\fB\-\-key_file\fR \fIfilename\fR
.RS 4
This sets
\fBsslclient\*(Aqs\fR
private key to the first private key found in
\fIfilename\fR\&. This is the
\fIfile\fR
argument to the
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[4]\d\s+2
\fBSSL_CTX_usePrivateKey_file()\fR
function\&. The default private key file type is
PEM\&. If the key has been encrypted, the program will prompt for the passphrase\&.
.RE
.PP
\fB\-kft\fR \fItype\fR
.br
\fB\-\-key_file_type\fR \fItype\fR
.RS 4
The private key file type is set to
\fItype\fR, which must be either
pem
or
asn1
(case insensitive)\&. The default private key file type is
PEM\&.
.RE
.PP
\fB\-p\fR \fIportnum\fR
.br
\fB\-sp\fR \fIportnum\fR
.br
\fB\-\-server_port\fR \fIportnum\fR
.RS 4
Unless appended to the
\fIserver\fR
argument,
\fIportnum\fR
is the port number to use, overriding the default port (443)\&.
.RE
.PP
\fB\-r\fR \fIfilename\fR
.br
\fB\-\-random\fR \fIfilename\fR
.RS 4
Seed material for the PRNG is read from
\fIfilename\fR\&. This is the
\fIfilename\fR
argument to the
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[4]\d\s+2
\fBRAND_load_file()\fR
function\&.
.RE
.PP
\fB\-sm\fR \fIregex\fR
.br
\fB\-\-server_match\fR \fIregex\fR
.RS 4
This argument, which may be repeated, specifies a constraint on the server\*(Aqs identity by matching an attribute value in the server\*(Aqs certificate against
\fIregex\fR\&. These tests are made immediately after an SSL/TLS connection is established\&. Each
\fIregex\fR
is an IEEE Std 1003\&.2 ("POSIX\&.2") regular expression with extended expressions and case insensitivity (REG_EXTENDED | REG_ICASE)\&. See
\m[blue]\fBbelow\fR\m[]\&\s-2\u[14]\d\s+2
for the matching algorithm\&.
.RE
.PP
\fB\-sni\fR
.br
\fB\-\-enable\-sni\fR
.RS 4
When it is provided by its
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[4]\d\s+2
library, the Server Name Indication (SNI) TLS extension is used by default, so it should not be necessary to specify this flag\&. Refer to
\m[blue]\fBRFC 6066\fR\m[]\&\s-2\u[15]\d\s+2
for details\&.
.RE
.PP
\fB\-vd\fR \fIdepth\fR
.br
\fB\-\-verify_depth\fR \fIdepth\fR
.RS 4
This sets the maximum depth for certificate chain verification to
\fIdepth\fR\&. This is the
\fIdepth\fR
argument to the
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[4]\d\s+2
\fBSSL_CTX_set_verify_depth()\fR
function\&.
.RE
.PP
\fB\-vt\fR \fItype\fR
.br
\fB\-\-verify_type\fR \fItype\fR
.RS 4
This sets the verification mode to
\fItype\fR, which must be either
none
or
peer
(case insensitive)\&. This is the
\fImode\fR
argument to the
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[4]\d\s+2
\fBSSL_CTX_set_verify()\fR
function\&.
.RE
.PP
\fB\-\-\fR
.RS 4
This argument explicitly marks the end of the flags\&.
.RE
.PP
The
\fBDACS\fR
\fB\-v\fR
(or
\fB\-\-verbose\fR) flag causes the program to show some of the server\*(Aqs SSL certificate, print feedback about regular expression matching, and so on\&. If
\fBsslclient\fR
is not doing what you expect, try using this flag\&.
.SS "Server Identity Verification"
.PP
If the server presents a valid SSL (X\&.509) certificate, a set of checks is applied to it to help ensure that
\fBsslclient\fR
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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
You can use a command like the following one to display an X\&.509 certificate to
stdout
in text form:
.sp
.if n \{\
.RS 4
.\}
.nf
% openssl x509 \-noout \-text < cert\&.crt
.fi
.if n \{\
.RE
.\}
.sp
Here,
cert\&.crt
is the certificate to display\&.
.sp .5v
.RE
.PP
The server certificate\*(Aqs
subjectAltName
extension fields have the format
field\-name:field\-value\&. For each such field, tests are made in the following sequence:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
the entire field is matched against each of the regular expressions given on the command line\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
if the previous test failed and
field\-name
is "DNS" (exact match), it is compared case insensitively to the server\*(Aqs name (as given on the command line)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
if the previous test failed and if the
field\-name
is "IP Address" (exact match), it is compared to the server\*(Aqs name (exact match), which is assumed to be an IP address (as given on the command line)\&.
.RE
.PP
If the above procedure is unsuccessful and the server certificate\*(Aqs
commonName
attribute value is available, it is matched against each of the regular expressions given on the command line\&.
.SH "EXAMPLES"
.PP
The following command line attempts to connect to port
443
at
example\&.com
and prints to
stdout
the server\*(Aqs response to a request for the home page:
.sp
.if n \{\
.RS 4
.\}
.nf
% printf "GET https://example\&.com:443 HTTP/1\&.0\er\en\er\en" | sslclient example\&.com:443
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
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,
\m[blue]\fBApache has become more strict in this regard\fR\m[]\&\s-2\u[16]\d\s+2\&. In particular, this may trip you up if you use
\fBsslclient\fR
interactively, since your input will end with only a newline\&. Refer to
\m[blue]\fBRFC 7230\fR\m[]\&\s-2\u[17]\d\s+2, Section 3\&.
.sp .5v
.RE
.SH "DIAGNOSTICS"
.PP
When used with
\fBDACS\fR
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\&.
.SH "NOTES"
.PP
A wrapper mode of operation might be useful\&.
.PP
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
\fBDACS\fR
ruleset) to a service running on an interior host, for instance\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacshttp(1)\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fBopenssl(1)\fR\m[]\&\s-2\u[4]\d\s+2,
\m[blue]\fBs_client(1)\fR\m[]\&\s-2\u[18]\d\s+2,
\m[blue]\fBstunnel(1)\fR\m[]\&\s-2\u[19]\d\s+2,
\m[blue]\fBcurl(1)\fR\m[]\&\s-2\u[20]\d\s+2,
\m[blue]\fBsslwrap(1)\fR\m[]\&\s-2\u[21]\d\s+2, and others, and
\m[blue]\fBregex(3)\fR\m[]\&\s-2\u[22]\d\s+2\&.
.PP
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\*(AqReilly & Associates, Inc\&., 2002\&. Also useful are
\m[blue]\fBSSL/TLS Strong Encryption: An Introduction\fR\m[]\&\s-2\u[23]\d\s+2,
\m[blue]\fBNetscape SSL 3\&.0 Specification\fR\m[]\&\s-2\u[24]\d\s+2,
\m[blue]\fBRFC 2246\fR\m[]\&\s-2\u[25]\d\s+2, and
\m[blue]\fBRFC 6066\fR\m[]\&\s-2\u[15]\d\s+2\&.
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[26]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[27]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacsoptions
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 2." 4
dacshttp(1)
.RS 4
\%http://dacs.dss.ca/man/dacshttp.1.html
.RE
.IP " 3." 4
default SSL/TLS port for
https (443)
.RS 4
\%http://www.iana.org/assignments/port-numbers
.RE
.IP " 4." 4
OpenSSL
.RS 4
\%http://www.openssl.org
.RE
.IP " 5." 4
\fBSSL_CTX_load_verify_locations()\fR
.RS 4
\%http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html
.RE
.IP " 6." 4
mod_ssl's
.RS 4
\%http://httpd.apache.org/docs-2.2/mod/mod_ssl.html
.RE
.IP " 7." 4
SSLCACertificateFile
.RS 4
\%http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#sslcacertificatefile
.RE
.IP " 8." 4
SSLCACertificatePath
.RS 4
\%http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#sslcacertificatepath
.RE
.IP " 9." 4
\fBSSL_CTX_use_certificate_chain_file()\fR
.RS 4
\%http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html
.RE
.IP "10." 4
SSLCACertificateChainFile
.RS 4
\%http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#sslcacertificatechainfile
.RE
.IP "11." 4
\fBSSL_CTX_set_cipher_list()\fR
.RS 4
\%http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html
.RE
.IP "12." 4
SSLCipherSuite
.RS 4
\%http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#sslciphersuite
.RE
.IP "13." 4
\fB--with-default-cipher-list\fR
.RS 4
\%http://dacs.dss.ca/man/dacs.install.7.html#build_flag_--with-default-cipher-list
.RE
.IP "14." 4
below
.RS 4
\%http://dacs.dss.ca/man/#verificaton
.RE
.IP "15." 4
RFC 6066
.RS 4
\%http://www.rfc-editor.org/rfc/rfc6066.txt
.RE
.IP "16." 4
Apache has become more strict in this regard
.RS 4
\%https://bz.apache.org/bugzilla/show_bug.cgi?id=60695
.RE
.IP "17." 4
RFC 7230
.RS 4
\%http://www.rfc-editor.org/rfc/rfc7230.txt
.RE
.IP "18." 4
s_client(1)
.RS 4
\%http://www.openssl.org/docs/apps/s_client.html
.RE
.IP "19." 4
stunnel(1)
.RS 4
\%http://www.stunnel.org
.RE
.IP "20." 4
curl(1)
.RS 4
\%http://directory.fsf.org/project/curl
.RE
.IP "21." 4
sslwrap(1)
.RS 4
\%http://www.rickk.com/sslwrap
.RE
.IP "22." 4
regex(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "23." 4
SSL/TLS Strong Encryption: An Introduction
.RS 4
\%http://httpd.apache.org/docs-2.2/ssl/ssl_intro.html
.RE
.IP "24." 4
Netscape SSL 3.0 Specification
.RS 4
\%http://web.archive.org/web/20070717014933rn_1/wp.netscape.com/eng/ssl3//
.RE
.IP "25." 4
RFC 2246
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2246.txt
.RE
.IP "26." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "27." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE