# couriertls

## Name

couriertls -- Courier 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 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), courier(8).