Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
COURIERTLS(1)		    Double Precision, Inc.		 COURIERTLS(1)

NAME
       couriertls - the	Courier	mail server 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 mail	server
       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].

AUTHOR
       Sam Varshavchik
	   Author

NOTES
	1. couriertcpd(1)
	   [set	$man.base.url.for.relative.links]/couriertcpd.html

	2. courier(8)
	   [set	$man.base.url.for.relative.links]/courier.html

Courier	Mail Server		  02/10/2011			 COURIERTLS(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT VARIABLES | SEE ALSO | AUTHOR | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=couriertls&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help