couriertls — the Courier mail server
TLS/SSL protocol wrapper
Synopsis
couriertls [option...] {program} {arg...}
DESCRIPTION
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.
OPTIONS
-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.
-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. If the program is not specified, the standard input and output of
couriertls itself is encrypted.
ENVIRONMENT VARIABLES
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_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).
