GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
SST(1) FreeBSD General Commands Manual SST(1)

sst - simple SSL tunnel

sst [-cdeilnsvrS] [-p [host':']port] [-t timeout] [-C SSL_cert] [-K priv_key] [-D SSL_dir] [-M SSL_method] [-V SSL_cert_depth] [-- {auxiliary command}]

Sst can be used to connect to SSL-encrypted network services or it can be used as an SSL front-end to network servers. Sst can be used interactively, or in an inetd setting, or it can be embedded inside other programs (eg. Amanda).

One of the main goals of sst is to be as basic as possible so in most non-embedded cases sst uses netcat to setup the networking I/O. Sst uses a socketpair(2) pipe to stay in contact with its netcat child process. In this way sst has only to concern itself with file descriptors.

In the embedded mode sst expects the parent program to handle the actual networking I/O and to provide the appropriate file descriptors. In embedded client mode ("-c"), clear data is read from (or written to) stdin (fildes 0) and SSL-encrypted data is read from (or written to) stdout (fildes 1). In embedded server mode ("-s"), SSL-encrypted data is read from (or written to) stdin and clear data read from (or written to) stdout.

-v
Be verbose. Display operational messages.

-d
Display debugging messages. This option implies "-v". This option can be repeated to increase the amount of detail.

-l
Use syslog(3) instead of printing to stderr (fildes 2) for output resulting from the verbose ("-v") or debugging ("-d") options.

-n
Don't invoke SSL to encrypt/decrypt the I/O. This yields a plain raw pipe. It's mainly useful for testing raw unencrypted connections.

-c
Client mode (default). Input read from stdin is SSL-encrypted and then sent to the remote server. Data received from the remote server is decrypted and then printed to stdout.

-e
Shutdown the SSL connection after EOF from the client side. otherwise sst expects the server side to be the first to shut down the SSL connection. Only useful in client mode ("-c").

-p [host':']port
Open a TCP connection to port on host If the host part is not specified, then 127.0.0.1 (ie. localhost) is used. This option causes a netcat process to be launched to handle the raw network I/O.

-t timeout
Set the maximum number of seconds to wait for input from either the local or the remote side. The default is no timeout (ie. wait forever).

-s
Set server mode. Check that both the SSL certificate and the SSL private key exist and check that they are both in order. Input from the remote client is decrypted and printed to stdout. Input from stdin is SSL-encrypted and sent to the remote client.

-i
Set inetd mode. This option imples "-l". This option also implies "-s" except that both stdin and stdout are connected with the remote client. In this mode, sst can act as a forwarder ( sst relays the decrypted data to the local server via a TCP connection) or as a wrapper ( sst launches the local server as a child process - ie. like TCP wrappers). Note that in this mode, if the inetd service is run under a non-root userid then that userid should have read access to the SSL certificate and private key file(s).

-D SSL_dir
Search an alternate directory for SSL files. The default directory is /local/lib/openssl/.
-C SSL_cert
Use an alternate SSL certificate file. The default path is [SSL_dir]/cert/sst.pem.
-K SSL_priv_key
Use an alternate SSL private key file. The default path is [SSL_dir]/[SSL_cert].

-M SSL_method
Use a specific SSL method. The SSL methods currently supported are "ssl2", "ssl3" or "tls1". The default SSL method is ssl23 (ie. start with ssl3 but fall back to ssl2). This option is useful when the client is only able to use a specific method (eg. when using netscape to access email via IMAP over SSL, netscape seems to want SSLv2).

-r
Require a peer certificate. In server mode, this means that the client must provide a certificate. In client mode, this causes the certificate and the private key to be loaded.

-V SSL_cert_depth
Set the default certificate verification depth. See SSL_CTX_set_verify(3) for an explanation.

-S
Strict certificate verification. By default, self-signed certificates are permitted. With this flag, self-signed certificates are treated as errors.

-- aux_prog aux_arg1 aux_arg2 ...
Launch an auxiliary command to be used instead of the default netcat. The "--" prevents getopt(3) from processing any further command-line arguments. The remaining command-line arguments make up the auxiliary command which is to be launched by sst as a child process (this feature uses execvp(3) so aux_prog does not have to be a full pathname if the auxiliary program can be expected to be in the user's PATH). For example, the following two usages are identical in that they both result in the launch of a netcat child process to make a TCP connection to "hostname" on "port":
sst -p hostname:port
sst -- nc hostname port

The only options of any significance for the embedded mode are "-e", "-s" and the SSL-specific options. Since the parent process is expected to provide the file descriptors for an embedded sst, the only things which matter are strictly SSL-related (ie. which fildes should be encrypted, which side is expected to provide certification, and which side will be expected to shutdown the connection).

sst -p mainbox:993
Interactively connect to host "mainbox" on port 993 (IMAP over SSL).
sst -s -p 1789
Interactively start a standalone server on port 1789 (this is really only useful for debugging).
sst -p 1789
Interactively connect to the standalone server in the preceding example.
sst -- nc 127.0.0.1 1789
Same as the preceding example but demonstrating the auxiliary feature
sst -- socat TCP4:127.0.0.1:1789 STDOUT
Same as the preceding example but using socat(1) instead of netcat
sst -e -p 1789
Same as the three preceding examples but the connection closes on EOF from the client instead of on EOF from the server.
simap stream tcp nowait nobody /local/bin/sst sst -i -M ssl2 -p 143
An example inetd.conf entry to provide SSL-encrypted access to the local IMAP server. This is an example of forwarding. In this case sst acts as an SSL front-end to the localhost's IMAP2 server. Here, sst will process the SSL-encrypted stream (inherited from inetd) and it will launch a netcat child process to do the TCP connection to the localhost's IMAP2 port. Here, to accomodate netscape clients the SSL method is set at ssl2.

sqotd stream tcp nowait nobody /local/bin/sst sst -i -- /usr/games/fortune -l
An example inetd.conf entry to provide some SSL-encrypted random text. This is an example of wrapping. In this case sst launches the server/service (ie. "/usr/games/fortune -l") as a child process and communicates with that child by way of a socketpair(2) pipe.

/local/lib/openssl/
default location for SSL files.
/local/lib/openssl/certs/sst.pem
default SSL certificate file.
/local/lib/openssl/certs/sst.pem
default SSL private key file.

socat(1), socketpair(2), exec(3), getopt(3), syslog(3)
OpenSSL
http://www.openssl.org/
Netcat (nc)
There's no man page for netcat.
Run "nc -h" to display its usage summary.
SSL encryption for Amanda
http://utcc.utoronto.ca/~pkern/stuff/amanda-patch
ssl-auth
http://web.purplefrog.com/~thoth/netpipes/ssl-auth.html

I discovered this long after writing sst.
It might have saved some time if I'd found it earlier. It seems to have some of the same basic ideas. It certainly looks more polished.

Written by P Kern <pkern@utcc.utoronto.ca> to try to provide a generic way for Amanda to encrypt backup images (to prevent disk backups from traversing networks in the clear).

Sst was written after pondering sslwrap [ written by Rick Kaseguma, http://www.rickk.com/sslwrap ] and especially stunnel [written by Michal Trojnara <Michal.Trojnara@centertel.pl>, http://mike.daewoo.com.pl/computer/stunnel ]

Most of the command-line options don't apply in the cases where sst is embedded. If those options are used in an embedded situation then they'll probably result in the parent processes hanging or becoming severely confused.

This man page should probably be rewritten for clarity.

March 22 2000

Search for    or go to Top of page |  Section 1 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.