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.

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

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

SEE ALSO

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

AUTHOR

       Sam Varshavchik
           Author

NOTES

        1. couriertcpd(1)
           http://www.courier-mta.org/couriertcpd.html

        2. courier(8)
           http://www.courier-mta.org/courier.html