COURIERTLS(1)

🌸 COURIERTLS(1) — the couriertls glow-up ✨

okay bestie, we're in section 1 of the manual, the command-line one, and this page is your girl couriertls. it's the Courier mail server's TLS/SSL protocol wrapper, and ngl it's lowkey the bouncer at the club that handles all the scary handshake stuff so your app doesn't have to. let's get into it 💅

---

💖 NAME 💖

couriertls — the Courier mail server TLS/SSL protocol wrapper. that's her. that's the whole vibe. 🎀

---

✨ SYNOPSIS ✨

couriertls [option...] {program} {arg...}

---

🦋 DESCRIPTION 🦋

so here's the tea: couriertls exists so that applications can encrypt a network connection using SSL/TLS without having to deal with the gory details of SSL/TLS themselves. it's giving "I got you, babe." 🤝

couriertls is used by the Courier mail server IMAP, POP3 and ESMTP servers. iconic behavior, truly.

and like, couriertls is not usually run directly from the commandline. an application typically creates a network connection first, then runs couriertls with the appropriate options to encrypt that network connection with SSL/TLS. it's the supportive bestie who shows up after the connection is already made 🫶

---

👑 OPTIONS 👑

• -host=host, -port=port — these two 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. (yes, the typo is canon, we keep her exactly as she is 🙈)
• -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. 💀 so basically it's the "did it work or not" hotline.
• -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. two-for-one deal, kind of ✨
• -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. 🛠️

fr fr, listen up about this next part: 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. main character energy honestly 🌟

---

🌈 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. 💀 so bestie, it's a placeholder. we wait.
• 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. ⚠️ no password protection allowed here, that's the rule.
• 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). 🕵️ like a vibe check but for certs.
• 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_CACHEFILEs 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. 📏 do not go below that number, bestie.

---

💜 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

---

and that's the whole page, periodt 💅 this was Courier Mail Server, dated 01/10/2026 — go forth and encrypt responsibly, bestie 💖✨🦋