Sophie: courier-base-4.5.0-1mdv2010.0 i586

courier-base-4.5.0-1mdv2010.0.i586.rpm

<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>couriertls</title><link rel="stylesheet" href="style.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"/><link rel="home" href="#couriertls" title="couriertls"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--

Copyright 1998 - 2009 Double Precision, Inc.  See COPYING for distribution
information.

--></head><body><div class="refentry" lang="en" xml:lang="en"><a id="couriertls" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>couriertls — the <span class="application">Courier</span> mail server
TLS/SSL protocol wrapper</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">couriertls</code>  [<em class="replaceable"><code>option</code></em>...] {<em class="replaceable"><code>program</code></em>} {<em class="replaceable"><code>arg</code></em>...}</p></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="id313485" shape="rect"> </a><h2>DESCRIPTION</h2><p>
The <span class="command"><strong>couriertls</strong></span> 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. <span class="command"><strong>couriertls</strong></span> is used by the
<span class="application">Courier</span> mail server
IMAP and ESMTP servers.</p><p>
<span class="command"><strong>couriertls</strong></span> is not usually run directly from the commandline.
An application typically creates a network connection, then runs
<span class="command"><strong>couriertls</strong></span> with appropriate options to encrypt the network
connection with SSL/TLS.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="id330611" shape="rect"> </a><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term">-host=<em class="replaceable"><code>host</code></em>, -port=<em class="replaceable"><code>port</code></em></span></dt><dd><p>
These options are
used instead of <code class="option">-remotefd</code>, mostly for debugging purposes.
<span class="command"><strong>couriertls</strong></span> connects to the specified server and immediately
starts SSL/TLS negotation when the connection is established.</p></dd><dt><span class="term">-localfd=<em class="replaceable"><code>n</code></em></span></dt><dd><p>
Read and write data to encrypt via SSL/TLS from file descriptor
<em class="replaceable"><code>n</code></em>.</p></dd><dt><span class="term">-statusfd=<em class="replaceable"><code>n</code></em></span></dt><dd><p>
Write SSL negotiation status to file
descriptor <em class="replaceable"><code>n</code></em>, then close this file descriptor.
If SSL starts
succesfully, reading on <em class="replaceable"><code>n</code></em> gets an immediate EOF.
Otherwise, a
single line of text - the error message - is read; the file descriptor is
closed; and <span class="command"><strong>couriertls</strong></span> terminates.</p></dd><dt><span class="term">-printx509=<em class="replaceable"><code>n</code></em></span></dt><dd><p>
Print the x509 certificate on file
descriptor <em class="replaceable"><code>n</code></em> then close it.  The x509 certificate is printed before
SSL/TLS encryption starts.  The application may immediately read the
certificate after running <span class="command"><strong>couriertls</strong></span>, until the file
descriptor is closed.</p></dd><dt><span class="term">-remotefd=<em class="replaceable"><code>n</code></em></span></dt><dd><p>
File descriptor <em class="replaceable"><code>n</code></em> is the network connection
where SSL/TLS encryption is to be used.</p></dd><dt><span class="term">-server</span></dt><dd><p>
Negotiate server side of the SSL/TLS connection.
If this option is not used the client side of the SSL/TLS connection is
negotiated.</p></dd><dt><span class="term">-tcpd</span></dt><dd><p>
<span class="command"><strong>couriertls</strong></span> is being called from
<span class="command"><strong>couriertcpd</strong></span>, and the remote socket is present on descriptors
0 and 1.  <code class="option">-tcpd</code> means, basically, the same as
<code class="option">-remotefd=0</code>, but <span class="command"><strong>couriertls</strong></span> closes file
descriptor 1, and redirects file descriptor 1 to file descriptor 2.</p></dd><dt><span class="term">-verify=<em class="replaceable"><code>domain</code></em></span></dt><dd><p>
Verify that <em class="replaceable"><code>domain</code></em> 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: <code class="literal">CN=*.example</code> will match
<code class="option">-verify=foo.example.com</code>. For
SSL/TLS clients,
<code class="envar">TLS_VERIFYPEER</code> must be set to PEER (see below).</p></dd><dt><span class="term">-protocol=<em class="replaceable"><code>proto</code></em></span></dt><dd><p>
Send <em class="replaceable"><code>proto</code></em> protocol
commands before enabling SSL/TLS on the remote connection. <em class="replaceable"><code>proto</code></em> is
either "<code class="literal">smtp</code>" or "<code class="literal">imap</code>".
This is a debugging option that can be used to
troubleshoot SSL/TLS with a remote IMAP or SMTP server.</p></dd></dl></div><p>
If the <code class="option">-remotefd=<em class="replaceable"><code>n</code></em></code> 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
<span class="command"><strong>couriertls</strong></span> itself is encrypted.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="id295601" shape="rect"> </a><h2>ENVIRONMENT VARIABLES</h2><p>
<span class="command"><strong>couriertls</strong></span> reads the following environment variables in
order to configure the SSL/TLS protocol:</p><div class="variablelist"><dl><dt><span class="term">TLS_PROTOCOL=<em class="replaceable"><code>proto</code></em></span></dt><dd><p>
Set the protocol version.  The possible versions are:
<code class="literal">SSL2</code>, <code class="literal">SSL3</code>,
<code class="literal">TLS1</code>.</p></dd><dt><span class="term">TLS_CIPHER_LIST=<em class="replaceable"><code>cipherlist</code></em></span></dt><dd><p>
Optionally set the list of protocol ciphers to be used.
See OpenSSL's documentation for more information.</p></dd><dt><span class="term">TLS_TIMEOUT=<em class="replaceable"><code>seconds</code></em></span></dt><dd><p>
Currently not implemented, and
reserved for future use.  This is supposed to be an inactivity timeout,
but it's not yet implemented.</p></dd><dt><span class="term">TLS_DHCERTFILE=<em class="replaceable"><code>filename</code></em></span></dt><dd><p>
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
<em class="replaceable"><code>filename</code></em> must not be world-readable.</p></dd><dt><span class="term">TLS_CERTFILE=<em class="replaceable"><code>filename</code></em></span></dt><dd><p>
The certificate to use.
<code class="envar">TLS_CERTFILE</code> is required for SSL/TLS servers, and is optional
for SSL/TLS clients.
<em class="replaceable"><code>filename</code></em> must not be world-readable.</p></dd><dt><span class="term">TLS_TRUSTCERTS=<em class="replaceable"><code>pathname</code></em></span></dt><dd><p>
Load trusted root certificates
from <em class="replaceable"><code>pathname</code></em>.  <em class="replaceable"><code>pathname</code></em>
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
<span class="command"><strong>c_rehash</strong></span> script. <code class="envar">TLS_TRUSTCERTS</code> is used by
SSL/TLS clients (by
specifying the <code class="option">-domain</code> option) and by SSL/TLS servers
(<code class="envar">TLS_VERIFYPEER</code> is set to <code class="literal">PEER</code> or
<code class="literal">REQUIREPEER</code>).</p></dd><dt><span class="term">TLS_VERIFYPEER=<em class="replaceable"><code>level</code></em></span></dt><dd><p>
Whether to verify peer's
X.509 certificate.  The exact meaning of this option depends upon whether
<span class="command"><strong>couriertls</strong></span> is used in the client or server mode.
In server mode:
<code class="literal">NONE</code> - do not request an X.509 certificate from the client;
<code class="literal">PEER</code> - 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);
<code class="literal">REQUIREPEER</code> - 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:
<code class="literal">NONE</code> - ignore the server's X.509 certificate;
<code class="literal">PEER</code> - verify the server's
X.509 certificate according to the <code class="option">-domain</code> option,
(see above).</p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="id340014" shape="rect"> </a><h2>SEE ALSO</h2><p>
<a class="ulink" href="couriertcpd.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">couriertcpd</span>(1)</span></a>,
<a class="ulink" href="courier.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">courier</span>(8)</span></a>.</p></div></div></body></html>