COURIERTLS(1)						      Double Precision, Inc.						     COURIERTLS(1)

NAME

       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).

SEE ALSO

       couriertcpd(1)[1], courier(8)[2].

AUTHOR

       Sam Varshavchik
	   Author

NOTES

	1. couriertcpd(1)
	   [set $man.base.url.for.relative.links]/couriertcpd.html

	2. courier(8)
	   [set $man.base.url.for.relative.links]/courier.html

Courier Mail Server						    04/04/2011							     COURIERTLS(1)