unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

COURIERTLS(1)               Double Precision, Inc.               COURIERTLS(1)



NAME
       couriertls - Courier 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 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.

       -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. 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_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)[1], courier(8)[2].

REFERENCES
        1. couriertcpd(1)
           couriertcpd.html

        2. courier(8)
           courier.html



Double Precision, Inc.            04/22/2007                     COURIERTLS(1)