--- name: "couriertls" section: "1" platform: "linux" package: "courier-base" version: "1.4.1-3+deb13u2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/couriertls" --- # couriertls(1) the Courier mail server TLS/SSL protocol wrapper ## 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 \TLS\_CERTFILE\ 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)](/couriertcpd/1.md)\[1\], [**courier**(8)](/courier/8.md)\[2\]. ## AUTHOR **Sam Varshavchik** Author ## NOTES - 1\. [**couriertcpd**(1)](/couriertcpd/1.md) http://www.courier-mta.org/couriertcpd.html - 2\. [**courier**(8)](/courier/8.md) http://www.courier-mta.org/courier.html