path: root/tcpd/couriertls.sgml

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!-- Copyright 2000-2018 Double Precision, Inc.  See COPYING for -->
<!-- distribution information. -->
<refentry id="couriertls">
  <info><author><firstname>Sam</firstname><surname>Varshavchik</surname><contrib>Author</contrib></author><productname>Courier Mail Server</productname></info>

  <refmeta>
    <refentrytitle>couriertls</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo>Double Precision, Inc.</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>couriertls</refname>
    <refpurpose>the <application>Courier</application> mail server
TLS/SSL protocol wrapper</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis sepchar=" ">
      <command>couriertls</command>
      <arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
      <arg choice="req" rep="norepeat"><replaceable>program</replaceable></arg>
      <arg choice="req" rep="repeat"><replaceable>arg</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="couriertls_description">
    <title>DESCRIPTION</title>

    <para>
The <command>couriertls</command> 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. <command>couriertls</command> is used by the
<application>Courier</application> mail server
IMAP and ESMTP servers.</para>

    <para>
<command>couriertls</command> is not usually run directly from the commandline.
An application typically creates a network connection, then runs
<command>couriertls</command> with appropriate options to encrypt the network
connection with SSL/TLS.</para>
  </refsect1>

  <refsect1 id="couriertls_options">
    <title>OPTIONS</title>

    <variablelist>
      <varlistentry>
	<term>-host=<replaceable>host</replaceable>, -port=<replaceable>port</replaceable></term>
	<listitem>
	  <para>
These options are
used instead of <option>-remotefd</option>, mostly for debugging purposes.
<command>couriertls</command> connects to the specified server and immediately
starts SSL/TLS negotation when the connection is established.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-localfd=<replaceable>n</replaceable></term>
	<listitem>
	  <para>
Read and write data to encrypt via SSL/TLS from file descriptor
<replaceable>n</replaceable>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-statusfd=<replaceable>n</replaceable></term>
	<listitem>
	  <para>
Write SSL negotiation status to file
descriptor <replaceable>n</replaceable>, then close this file descriptor.
If SSL starts
succesfully, reading on <replaceable>n</replaceable> gets an immediate EOF.
Otherwise, a
single line of text - the error message - is read; the file descriptor is
closed; and <command>couriertls</command> terminates.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-printx509=<replaceable>n</replaceable></term>
	<listitem>
	  <para>
Print the x509 certificate on file
descriptor <replaceable>n</replaceable> then close it.  The x509 certificate is printed before
SSL/TLS encryption starts.  The application may immediately read the
certificate after running <command>couriertls</command>, until the file
descriptor is closed.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-remotefd=<replaceable>n</replaceable></term>
	<listitem>
	  <para>
File descriptor <replaceable>n</replaceable> is the network connection
where SSL/TLS encryption is to be used.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-server</term>
	<listitem>
	  <para>
Negotiate server side of the SSL/TLS connection.
If this option is not used the client side of the SSL/TLS connection is
negotiated.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-tcpd</term>
	<listitem>
	  <para>
<command>couriertls</command> is being called from
<command>couriertcpd</command>, and the remote socket is present on descriptors
0 and 1.  <option>-tcpd</option> means, basically, the same as
<option>-remotefd=0</option>, but <command>couriertls</command> closes file
descriptor 1, and redirects file descriptor 1 to file descriptor 2.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-user=<replaceable>username</replaceable></term>
	<listitem>
	  <para>
	    Used when
	    <command>couriertls</command> needs to get started as root
	    and fork off a root child process (see below), before dropping
	    root and running as the specified user.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-verify=<replaceable>domain</replaceable></term>
	<listitem>
	  <para>
Verify that <replaceable>domain</replaceable> 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: <literal>CN=*.example</literal> will match
<option>-verify=foo.example.com</option>. For
SSL/TLS clients,
<envar>TLS_VERIFYPEER</envar> must be set to PEER (see below).</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-protocol=<replaceable>proto</replaceable></term>
	<listitem>
	  <para>
Send <replaceable>proto</replaceable> protocol
commands before enabling SSL/TLS on the remote connection. <replaceable>proto</replaceable> is
either "<literal>smtp</literal>" or "<literal>imap</literal>".
This is a debugging option that can be used to
troubleshoot SSL/TLS with a remote IMAP or SMTP server.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
If the <option>-remotefd=<replaceable>n</replaceable></option> 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 <option>-user</option> option drops root and
<command>couriertls</command> continues to run as the indicated user.
If the program is not specified, the standard input and output of
<command>couriertls</command> itself is encrypted.</para>

  </refsect1>

  <refsect1 id="couriertls_environment_variables">
    <title>ENVIRONMENT VARIABLES</title>

<para>
<command>couriertls</command> reads the following environment variables in
order to configure the SSL/TLS protocol:</para>

    <variablelist>
      <varlistentry>
	<term>TLS_PROTOCOL=<replaceable>proto</replaceable></term>
	<listitem>
	  <para>
Set the protocol version.  The possible versions are:
<literal>SSL2</literal>, <literal>SSL3</literal>,
<literal>TLS1</literal>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>TLS_CIPHER_LIST=<replaceable>cipherlist</replaceable></term>
	<listitem>
	  <para>
Optionally set the list of protocol ciphers to be used.
See OpenSSL's documentation for more information.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>TLS_TIMEOUT=<replaceable>seconds</replaceable></term>
	<listitem>
	  <para>
Currently not implemented, and
reserved for future use.  This is supposed to be an inactivity timeout,
but it's not yet implemented.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>TLS_DHCERTFILE=<replaceable>filename</replaceable></term>
	<listitem>
	  <para>
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
<replaceable>filename</replaceable> must not be world-readable.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>TLS_CERTFILE=<replaceable>filename</replaceable></term>
	<listitem>
	  <para>
The certificate to use.
<envar>TLS_CERTFILE</envar> is required for SSL/TLS servers, and is optional
for SSL/TLS clients.
<replaceable>filename</replaceable> must not be world-readable.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>TLS_PRIVATE_KEYFILE=<replaceable>filename</replaceable></term>
	<listitem>
	  <para>
SSL/TLS private key for decrypting client data.
<envar>TLS_PRIVATE_KEY</envar> is optional because <term>TLS_CERTFILE</term> is generated including cert and private key both.
<replaceable>filename</replaceable> must not be world-readable, and must be accessible without a pass-phrase, i.e. it must not be encrypted.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>TLS_TRUSTCERTS=<replaceable>pathname</replaceable></term>
	<listitem>
	  <para>
Load trusted root certificates
from <replaceable>pathname</replaceable>.  <replaceable>pathname</replaceable>
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
<command>c_rehash</command> script. <envar>TLS_TRUSTCERTS</envar> is used by
SSL/TLS clients (by
specifying the <option>-domain</option> option) and by SSL/TLS servers
(<envar>TLS_VERIFYPEER</envar> is set to <literal>PEER</literal> or
<literal>REQUIREPEER</literal>).</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>TLS_VERIFYPEER=<replaceable>level</replaceable></term>
	<listitem>
	  <para>
Whether to verify peer's
X.509 certificate.  The exact meaning of this option depends upon whether
<command>couriertls</command> is used in the client or server mode.
In server mode:
<literal>NONE</literal> - do not request an X.509 certificate from the client;
<literal>PEER</literal> - 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);
<literal>REQUIREPEER</literal> - 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:
<literal>NONE</literal> - ignore the server's X.509 certificate;
<literal>PEER</literal> - verify the server's
X.509 certificate according to the <option>-domain</option> option,
(see above).</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="couriertls_see_also">
    <title>SEE ALSO</title>

    <para>
<ulink url="couriertcpd.html"><citerefentry><refentrytitle>couriertcpd</refentrytitle><manvolnum>1</manvolnum></citerefentry></ulink>,
<ulink url="courier.html"><citerefentry><refentrytitle>courier</refentrytitle><manvolnum>8</manvolnum></citerefentry></ulink>.</para>
  </refsect1>
</refentry>