SSLCLIENT(1) | DACS Commands Manual | SSLCLIENT(1) |
NAME¶
sslclient - an SSL clientSYNOPSIS¶
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 filenameThis 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
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
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
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
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
Print a usage synopsis.
-kf 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
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
Unless appended to the server argument,
portnum is the port number to use, overriding the default port
(443).
-r 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
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
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
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.% openssl x509 -noout -text < cert.crt
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
- 2.
- dacshttp(1)
- 3.
- default SSL port for https (443)
- 4.
- OpenSSL
- 5.
- SSL_CTX_load_verify_locations()
- 6.
- mod_ssl's
- 7.
- SSLCACertificateFile
- 8.
- SSLCACertificatePath
- 9.
- SSL_CTX_use_certificate_chain_file()
- 10.
- SSLCACertificateChainFile
- 11.
- SSL_CTX_set_cipher_list()
- 12.
- SSLCipherSuite
- 13.
- below
- 14.
- s_client(1)
- 15.
- stunnel(1)
- 16.
- curl(1)
- 17.
- sslwrap(1)
- 18.
- regex(3)
- 19.
- SSL/TLS Strong Encryption: An Introduction
- 20.
- Netscape SSL 3.0 Specification
- 21.
- RFC 2246
- 22.
- www.dss.ca
- 23.
- LICENSE
07/17/2013 | DACS 1.4.28b |