1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
'\" t
.\"<!-- Copyright 2000-2009 Double Precision, Inc. See COPYING for -->
.\"<!-- distribution information. -->
.\" Title: couriertls
.\" Author: Sam Varshavchik
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 04/04/2011
.\" Manual: Double Precision, Inc.
.\" Source: Courier Mail Server
.\" Language: English
.\"
.TH "COURIERTLS" "1" "04/04/2011" "Courier Mail Server" "Double Precision, Inc."
.\" -----------------------------------------------------------------
.\" * 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
\-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\&. 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\'s 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\'s 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_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\'s
\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\'s 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\'s X\&.509 certificate;
PEER
\- verify the server\'s 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
\%[set $man.base.url.for.relative.links]/couriertcpd.html
.RE
.IP " 2." 4
\fBcourier\fR(8)
.RS 4
\%[set $man.base.url.for.relative.links]/courier.html
.RE
|
