couriertls [ options ] [program arg1 arg2 ...]
The couriertls
program is used by applications to encrypt a
network connection using SSL/TLS, without having the application deal with the
gory details of SSL/TLS. couriertls
is used by the Courier IMAP
and ESMTP servers.
couriertls
is not usually run directly from the commandline.
An application typically creates a network connection, then runs
couriertls
with appropriate options to encrypt the network
connection with SSL/TLS.
-host=host, -port=port
- these options are
used instead of -remotefd
, mostly for debugging purposes.
couriertls
connects to the specified server and immediately
starts SSL/TLS negotation when the connection is established.-localfd=n
- read and write data to encrypt via
SSL/TLS from file descriptor n.-printx509=n
- print the x509 certificate on file
descriptor n then close it. The x509 certificate is printed before
SSL/TLS encryption starts. The application may immediately read the
certificate after running couriertls
, until the file
descriptor is closed.-remotefd=n
- file descriptor n is the
network connection where SSL/TLS encryption is to be used.-server
- negotiate server side of the SSL/TLS connection.
If this option is not used the client side of the SSL/TLS connection is
negotiated.-tcpd
- couriertls
is being called from
couriertcpd
, and the remote socket is present on descriptors
0 and 1. -tcpd
means, basically, the same as
-remotefd=0
, but couriertls
closes file
descriptor 1, and redirects file descriptor 1 to file descriptor 2.-verify=domain
- verify the domain in the
x509 certificate presented by the SSL/TLS peer.If the -remotefd=n
option is not specified, the rest of
the command line specifies the program to run -- and its arguments -- whose
standard input and output is encrypted via SSL/TLS over the network
connection. If the program is not specified, the standard input and output of
couriertls
itself is encrypted.
couriertls
reads the following environment variables for the
particular details of SSL/TLS negotiations:
TLS_PROTOCOL=proto
- TLS_PROTOCOL sets the protocol
version. The possible versions are: SSL2, SSL3, TLS1.TLS_CIPHER_LIST=cipherlist
- optionally set the list
of ciphers to be used.TLS_TIMEOUT=seconds
- currently not implemented, and
reserved for future use. This is supposed to be an inactivity timeout,
but it's not yet implemented.TLS_DHCERTFILE=filename
- PEM file that stores our
Diffie-Hellman cipher pair. When OpenSSL is compiled to use Diffie-Hellman
ciphers instead of RSA you must generate a DH pair that will be used. In
most situations the DH pair is to be treated as confidential, and
filename must not be world-readable.TLS_CERTFILE=filename
- the certificate to use.
TLS_CERTFILE is required for SSL/TLS servers, and is optional for SSL/TLS
clients. filename must not be world-readable.TLS_PEERCERTDIR=directory
- see TLS_OURCACERT.TLS_OURCACERT=filename
- when it is required that
all peer certificates are signed by a specific certificate authority, set
TLS_OURCACERT to the name of the file containing the certificate authority
root key, and set TLS_PEERCERTDIR to the name of the directory containing
the allowed certificates.TLS_VERIFYPEER=level
- how to verify peer
certificates. level is: NONE - do not verify anything; PEER -
verify the peer certificate, if one's presented; REQUIREPEER - require a
peer certificate, fail if one's not presented.TLS_ALLOWSELFSIGNEDCERT=flag
- if flag is 1
this is an alternative to clients using TLS_VERIFYPEER=NONE.
TLS_ALLOWSELFSIGNEDCERT ignores server certificates that are not signed by
a recognized certificate authority. This allows clients to simply verify
that a server certificate is available.