couriertls - the Courier mail server TLS/SSL protocol wrapper
couriertls [option...] {program}
{arg...}
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 mail
server 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.
-statusfd=n
Write SSL negotiation status to file descriptor n,
then close this file descriptor. If SSL starts succesfully, reading on
n gets an immediate EOF. Otherwise, a single line of text - the error
message - is read; the file descriptor is closed; and couriertls
terminates.
-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.
-user=username
Used when couriertls needs to get started as root
and fork off a root child process (see below), before dropping root and
running as the specified user.
-verify=domain
Verify that domain is set in the CN field of the
trusted X.509 certificate presented by the SSL/TLS peer. TLS_TRUSTCERTS must
be initialized (see below), and the certificate must be signed by one of the
trusted certificates. The CN field can contain a wildcard: CN=*.example will
match -verify=foo.example.com. For SSL/TLS clients,
TLS_VERIFYPEER must be set to PEER (see below).
-protocol=proto
Send proto protocol commands before enabling
SSL/TLS on the remote connection. proto is either "smtp" or
"imap". This is a debugging option that can be used to troubleshoot
SSL/TLS with a remote IMAP or SMTP server.
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. This is done before the -user option drops
root and couriertls continues to run as the indicated user. If the
program is not specified, the standard input and output of couriertls
itself is encrypted.
couriertls reads the following environment variables in
order to configure the SSL/TLS protocol:
TLS_PROTOCOL=proto
Set the protocol version. The possible versions are:
SSL2, SSL3, TLS1.
TLS_CIPHER_LIST=cipherlist
Optionally set the list of protocol ciphers to be used.
See OpenSSL's documentation for more information.
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_PRIVATE_KEYFILE=filename
SSL/TLS private key for decrypting client data.
TLS_PRIVATE_KEY is optional because
<term>TLS_CERTFILE</term> is generated including cert and private
key both. filename must not be world-readable, and must be accessible
without a pass-phrase, i.e. it must not be encrypted.
TLS_TRUSTCERTS=pathname
Load trusted root certificates from pathname.
pathname can be a file or a directory. If a file, the file should
contain a list of trusted certificates, in PEM format. If a directory, the
directory should contain the trusted certificates, in PEM format, one per file
and hashed using OpenSSL's c_rehash script. TLS_TRUSTCERTS is
used by SSL/TLS clients (by specifying the -domain option) and by
SSL/TLS servers (TLS_VERIFYPEER is set to PEER or REQUIREPEER).
TLS_VERIFYPEER=level
Whether to verify peer's X.509 certificate. The exact
meaning of this option depends upon whether couriertls is used in the
client or server mode. In server mode: NONE - do not request an X.509
certificate from the client; PEER - request an optional X.509 certificate from
the client, if the client returns one, the SSL/TLS connection is shut down
unless the certificate is signed by a trusted certificate authority (see
TLS_TRUSTCERTS); REQUIREPEER - same as PEER, except that the SSL/TLS connects
is also shut down if the client does not return the optional X.509
certificate. In client mode: NONE - ignore the server's X.509 certificate;
PEER - verify the server's X.509 certificate according to the -domain
option, (see above).