'\" t
.\"
.\"
.\" Title: couriertls
.\" Author: Sam Varshavchik
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 10/28/2020
.\" Manual: Double Precision, Inc.
.\" Source: Courier Mail Server
.\" Language: English
.\"
.TH "COURIERTLS" "1" "10/28/2020" "Courier Mail Server" "Double Precision, Inc."
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
couriertls \- the Courier mail server TLS/SSL protocol wrapper
.SH "SYNOPSIS"
.HP \w'\fBcouriertls\fR\ 'u
\fBcouriertls\fR [\fIoption\fR...] {\fIprogram\fR} {\fIarg\fR...}
.SH "DESCRIPTION"
.PP
The
\fBcouriertls\fR
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\&.
\fBcouriertls\fR
is used by the
Courier
mail server IMAP and ESMTP servers\&.
.PP
\fBcouriertls\fR
is not usually run directly from the commandline\&. An application typically creates a network connection, then runs
\fBcouriertls\fR
with appropriate options to encrypt the network connection with SSL/TLS\&.
.SH "OPTIONS"
.PP
\-host=\fIhost\fR, \-port=\fIport\fR
.RS 4
These options are used instead of
\fB\-remotefd\fR, mostly for debugging purposes\&.
\fBcouriertls\fR
connects to the specified server and immediately starts SSL/TLS negotation when the connection is established\&.
.RE
.PP
\-localfd=\fIn\fR
.RS 4
Read and write data to encrypt via SSL/TLS from file descriptor
\fIn\fR\&.
.RE
.PP
\-statusfd=\fIn\fR
.RS 4
Write SSL negotiation status to file descriptor
\fIn\fR, then close this file descriptor\&. If SSL starts succesfully, reading on
\fIn\fR
gets an immediate EOF\&. Otherwise, a single line of text \- the error message \- is read; the file descriptor is closed; and
\fBcouriertls\fR
terminates\&.
.RE
.PP
\-printx509=\fIn\fR
.RS 4
Print the x509 certificate on file descriptor
\fIn\fR
then close it\&. The x509 certificate is printed before SSL/TLS encryption starts\&. The application may immediately read the certificate after running
\fBcouriertls\fR, until the file descriptor is closed\&.
.RE
.PP
\-remotefd=\fIn\fR
.RS 4
File descriptor
\fIn\fR
is the network connection where SSL/TLS encryption is to be used\&.
.RE
.PP
\-server
.RS 4
Negotiate server side of the SSL/TLS connection\&. If this option is not used the client side of the SSL/TLS connection is negotiated\&.
.RE
.PP
\-tcpd
.RS 4
\fBcouriertls\fR
is being called from
\fBcouriertcpd\fR, and the remote socket is present on descriptors 0 and 1\&.
\fB\-tcpd\fR
means, basically, the same as
\fB\-remotefd=0\fR, but
\fBcouriertls\fR
closes file descriptor 1, and redirects file descriptor 1 to file descriptor 2\&.
.RE
.PP
\-user=\fIusername\fR
.RS 4
Used when
\fBcouriertls\fR
needs to get started as root and fork off a root child process (see below), before dropping root and running as the specified user\&.
.RE
.PP
\-verify=\fIdomain\fR
.RS 4
Verify that
\fIdomain\fR
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
\fB\-verify=foo\&.example\&.com\fR\&. For SSL/TLS clients,
\fBTLS_VERIFYPEER\fR
must be set to PEER (see below)\&.
.RE
.PP
\-protocol=\fIproto\fR
.RS 4
Send
\fIproto\fR
protocol commands before enabling SSL/TLS on the remote connection\&.
\fIproto\fR
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\&.
.RE
.PP
If the
\fB\-remotefd=\fR\fB\fIn\fR\fR
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
\fB\-user\fR
option drops root and
\fBcouriertls\fR
continues to run as the indicated user\&. If the program is not specified, the standard input and output of
\fBcouriertls\fR
itself is encrypted\&.
.SH "ENVIRONMENT VARIABLES"
.PP
\fBcouriertls\fR
reads the following environment variables in order to configure the SSL/TLS protocol:
.PP
TLS_PROTOCOL=\fIproto\fR
.RS 4
Set the protocol version\&. The possible versions are:
SSL2,
SSL3,
TLS1\&.
.RE
.PP
TLS_CIPHER_LIST=\fIcipherlist\fR
.RS 4
Optionally set the list of protocol ciphers to be used\&. See OpenSSL\*(Aqs documentation for more information\&.
.RE
.PP
TLS_TIMEOUT=\fIseconds\fR
.RS 4
Currently not implemented, and reserved for future use\&. This is supposed to be an inactivity timeout, but it\*(Aqs not yet implemented\&.
.RE
.PP
TLS_DHCERTFILE=\fIfilename\fR
.RS 4
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
\fIfilename\fR
must not be world\-readable\&.
.RE
.PP
TLS_CERTFILE=\fIfilename\fR
.RS 4
The certificate to use\&.
\fBTLS_CERTFILE\fR
is required for SSL/TLS servers, and is optional for SSL/TLS clients\&.
\fIfilename\fR
must not be world\-readable\&.
.RE
.PP
TLS_PRIVATE_KEYFILE=\fIfilename\fR
.RS 4
SSL/TLS private key for decrypting client data\&.
\fBTLS_PRIVATE_KEY\fR
is optional because
TLS_CERTFILE
is generated including cert and private key both\&.
\fIfilename\fR
must not be world\-readable, and must be accessible without a pass\-phrase, i\&.e\&. it must not be encrypted\&.
.RE
.PP
TLS_TRUSTCERTS=\fIpathname\fR
.RS 4
Load trusted root certificates from
\fIpathname\fR\&.
\fIpathname\fR
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\*(Aqs
\fBc_rehash\fR
script\&.
\fBTLS_TRUSTCERTS\fR
is used by SSL/TLS clients (by specifying the
\fB\-domain\fR
option) and by SSL/TLS servers (\fBTLS_VERIFYPEER\fR
is set to
PEER
or
REQUIREPEER)\&.
.RE
.PP
TLS_VERIFYPEER=\fIlevel\fR
.RS 4
Whether to verify peer\*(Aqs X\&.509 certificate\&. The exact meaning of this option depends upon whether
\fBcouriertls\fR
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\*(Aqs X\&.509 certificate;
PEER
\- verify the server\*(Aqs X\&.509 certificate according to the
\fB\-domain\fR
option, (see above)\&.
.RE
.SH "SEE ALSO"
.PP
\m[blue]\fB\fBcouriertcpd\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2,
\m[blue]\fB\fBcourier\fR(8)\fR\m[]\&\s-2\u[2]\d\s+2\&.
.SH "AUTHOR"
.PP
\fBSam Varshavchik\fR
.RS 4
Author
.RE
.SH "NOTES"
.IP " 1." 4
\fBcouriertcpd\fR(1)
.RS 4
\%http://www.courier-mta.org/couriertcpd.html
.RE
.IP " 2." 4
\fBcourier\fR(8)
.RS 4
\%http://www.courier-mta.org/courier.html
.RE