## 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, POP3 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. This is used when couriertls is compiled with OpenSSL. This is ignored when couriertls is compiled with GnuTLS. The possible options are:

  `TLS1` or `TLSv1`

    The default setting selects TLS protocol version 1 or higher.

  `TLSv1.1` or `TLSv1.1+`

    The default setting selects TLS protocol version 1.1 or higher, the connection fails if the TLS peer does not implement at least version 1.1.

  `TLSv1.2` or `TLSv1.2+`

    The default setting selects TLS protocol version 1.2 or higher, the connection fails if the TLS peer does not implement at least version 1.2

  `TLSv1.1++` or `TLSv1.2++`

    The additional “+” disables protocol renegotiation, and selects server cipher preference (`TLSv1.2++` only, uses `TLS_CIPHER_LIST`).

TLS_CIPHER_LIST=`cipherlist`

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

TLS_CACHEFILE=`filename`

  `filename` is the name of the file where TLS sessions are saved. The `filename` gets created if it does not exist. `TLS_CACHEFILE`s are optional, and result in slight performance improvements with session-aware TLS clients.

TLS_CACHESIZE=`n`

  `n` is the size of the `TLS_CACHEFILE` in bytes. Larger cache files allow more SSL/TLS sessions to be saved, and SSL/TLS sessions are saved. The `filename` gets created if it does not exist. The minimum `TLS_CACHESIZE` is 16384.

## SEE ALSO

couriertcpd(1), courier(8).