| rev |
line source |
|
yuuji@0
|
1 /* ========================================================================
|
|
yuuji@0
|
2 * Copyright 1988-2007 University of Washington
|
|
yuuji@0
|
3 *
|
|
yuuji@0
|
4 * Licensed under the Apache License, Version 2.0 (the "License");
|
|
yuuji@0
|
5 * you may not use this file except in compliance with the License.
|
|
yuuji@0
|
6 * You may obtain a copy of the License at
|
|
yuuji@0
|
7 *
|
|
yuuji@0
|
8 * http://www.apache.org/licenses/LICENSE-2.0
|
|
yuuji@0
|
9 *
|
|
yuuji@0
|
10 *
|
|
yuuji@0
|
11 * ========================================================================
|
|
yuuji@0
|
12 */
|
|
yuuji@0
|
13
|
|
yuuji@0
|
14 SSL/TLS BUILD AND INSTALLATION NOTES FOR UNIX
|
|
yuuji@0
|
15 Last Updated: 15 November 2007
|
|
yuuji@0
|
16
|
|
yuuji@0
|
17 PREREQUISITES BEFORE STARTING:
|
|
yuuji@0
|
18 1) Review the information in imap-2007/docs/BUILD.
|
|
yuuji@0
|
19 2) Obtain a copy of OpenSSL. OpenSSL is available from third parties. We
|
|
yuuji@0
|
20 do not provide OpenSSL.
|
|
yuuji@0
|
21 3) Make sure that you know how to build OpenSSL properly on the standard
|
|
yuuji@0
|
22 /usr/local/ssl directory. In particular, /usr/local/ssl/include (and
|
|
yuuji@0
|
23 /usr/local/ssl/include/openssl) and /usr/local/ssl/lib must be set up
|
|
yuuji@0
|
24 from the OpenSSL build. If you have a non-standard installation, then
|
|
yuuji@0
|
25 you must modify the imap-2007/src/osdep/unix/Makefile file to point
|
|
yuuji@0
|
26 to the appropriate locations.
|
|
yuuji@0
|
27 4) Make sure that you know how to obtain appropriate certificates on your
|
|
yuuji@0
|
28 system.
|
|
yuuji@0
|
29
|
|
yuuji@0
|
30 NOTE: We can NOT provide you with support in building/installing OpenSSL, or
|
|
yuuji@0
|
31 in obtaining certificates. If you need help in doing this, try the contacts
|
|
yuuji@0
|
32 mentioned in the OpenSSL README.
|
|
yuuji@0
|
33
|
|
yuuji@0
|
34
|
|
yuuji@0
|
35 SSL BUILD:
|
|
yuuji@0
|
36
|
|
yuuji@0
|
37 By default, the IMAP toolkit builds with SSL and disabling plaintext
|
|
yuuji@0
|
38 passwords unless SSL/TLS encryption is in effect (SSLTYPE=nopwd). This
|
|
yuuji@0
|
39 produces an IMAP server which is compliant with RFC 3501 security
|
|
yuuji@0
|
40 requirements.
|
|
yuuji@0
|
41
|
|
yuuji@0
|
42 To build with SSL but allow plaintext passwords in insecure sessions,
|
|
yuuji@0
|
43 add "SSLTYPE=unix" to the make command line. Note that doing so will
|
|
yuuji@0
|
44 produce an IMAP server which is NON-COMPLIANT with RFC 3501.
|
|
yuuji@0
|
45
|
|
yuuji@0
|
46 To build without SSL, add "SSLTYPE=none" to the make command line.
|
|
yuuji@0
|
47 Note that doing so will produce an IMAP server which is NON-COMPLIANT
|
|
yuuji@0
|
48 with RFC 3501.
|
|
yuuji@0
|
49
|
|
yuuji@0
|
50 There are other make options relevant to SSL, described in
|
|
yuuji@0
|
51 imap-2007/src/osdep/unix/Makefile
|
|
yuuji@0
|
52 The most important of these are SSLDIR, SSLCRYPTO, and SSLRSA.
|
|
yuuji@0
|
53
|
|
yuuji@0
|
54 SSLDIR is set to /usr/local/ssl by default. This is the normal
|
|
yuuji@0
|
55 installation directory for OpenSSL. If your system uses a different directory
|
|
yuuji@0
|
56 you will need to change this.
|
|
yuuji@0
|
57
|
|
yuuji@0
|
58 SSLCRYPTO is set to -lcrypto by default. Older versions of MIT Kerberos
|
|
yuuji@0
|
59 also have a libcrypto and will cause a library name conflict. If you are
|
|
yuuji@0
|
60 using an older version of Kerberos, you may need to change SSLCRYPTO to
|
|
yuuji@0
|
61 $(SSLLIB)/libcrypto.a
|
|
yuuji@0
|
62
|
|
yuuji@0
|
63 SSLRSA is set empty by default. It can be set to specify the RSAREF
|
|
yuuji@0
|
64 libraries, which you once had to use with OpenSSL to use RSA algorithms
|
|
yuuji@0
|
65 legally if you are in the USA, due to patent issues. Since RSA Security Inc.
|
|
yuuji@0
|
66 released the RSA algorithm into the public domain on September 6, 2000, there
|
|
yuuji@0
|
67 is no longer any reason to do this.
|
|
yuuji@0
|
68
|
|
yuuji@0
|
69
|
|
yuuji@0
|
70 SSL INSTALLATION:
|
|
yuuji@0
|
71
|
|
yuuji@0
|
72 Binaries from the build are:
|
|
yuuji@0
|
73 imap-2007/mtest/mtest c-client testbed program
|
|
yuuji@0
|
74 imap-2007/ipopd/ipop2d POP2 daemon
|
|
yuuji@0
|
75 imap-2007/ipopd/ipop3d POP3 daemon
|
|
yuuji@0
|
76 imap-2007/imapd/imapd IMAP4rev1 daemon
|
|
yuuji@0
|
77
|
|
yuuji@0
|
78 mtest is normally not used except by c-client developers.
|
|
yuuji@0
|
79
|
|
yuuji@0
|
80 STEP 1: inetd setup
|
|
yuuji@0
|
81
|
|
yuuji@0
|
82
|
|
yuuji@0
|
83 The ipop2d, ipop3d, and imapd daemons should be installed in a system
|
|
yuuji@0
|
84 daemon directory and invoked by a listener such as xinetd or inetd. In the
|
|
yuuji@0
|
85 following examples, /usr/local/etc is used).
|
|
yuuji@0
|
86
|
|
yuuji@0
|
87 STEP 1(A): xinetd-specific setup
|
|
yuuji@0
|
88
|
|
yuuji@0
|
89 If your system uses xinetd, the daemons are invoked by files in your
|
|
yuuji@0
|
90 /etc/xinetd.d directory with names corresponding to the service names (that
|
|
yuuji@0
|
91 is: imap, imaps, pop2, pop3, pop3s). You will need to consult your local
|
|
yuuji@0
|
92 xinetd documentation to see what should go into these files. Here is a a
|
|
yuuji@0
|
93 sample /etc/xinetd.d/imaps file:
|
|
yuuji@0
|
94
|
|
yuuji@0
|
95 service imaps
|
|
yuuji@0
|
96 {
|
|
yuuji@0
|
97 disable = no
|
|
yuuji@0
|
98 socket_type = stream
|
|
yuuji@0
|
99 wait = no
|
|
yuuji@0
|
100 user = root
|
|
yuuji@0
|
101 server = /usr/local/etc/imapd
|
|
yuuji@0
|
102 groups = yes
|
|
yuuji@0
|
103 flags = REUSE IPv6
|
|
yuuji@0
|
104 }
|
|
yuuji@0
|
105
|
|
yuuji@0
|
106 STEP 1(B): inetd-specific setup
|
|
yuuji@0
|
107
|
|
yuuji@0
|
108 If your system still uses inetd, the daemons are invoked by your
|
|
yuuji@0
|
109 /etc/inetd.conf file with lines such as:
|
|
yuuji@0
|
110
|
|
yuuji@0
|
111 pop stream tcp nowait root /usr/local/etc/ipop2d ipop2d
|
|
yuuji@0
|
112 pop3 stream tcp nowait root /usr/local/etc/ipop3d ipop3d
|
|
yuuji@0
|
113 imap stream tcp nowait root /usr/local/etc/imapd imapd
|
|
yuuji@0
|
114 pop3s stream tcp nowait root /usr/local/etc/ipop3d ipop3d
|
|
yuuji@0
|
115 imaps stream tcp nowait root /usr/local/etc/imapd imapd
|
|
yuuji@0
|
116
|
|
yuuji@0
|
117 Please refer to imap-2007/docs/BUILD for an important note about inetd's
|
|
yuuji@0
|
118 limit on the number of new connections. If that note applies to you, and you
|
|
yuuji@0
|
119 can configure the number of connection in /etc/inetd.conf as described in
|
|
yuuji@0
|
120 imap-2007/docs/build, here is the sample /etc/inetd.conf entry with SSL:
|
|
yuuji@0
|
121
|
|
yuuji@0
|
122 pop3 stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d
|
|
yuuji@0
|
123 pop3s stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d
|
|
yuuji@0
|
124 imap stream tcp nowait.100 root /usr/local/etc/imapd imapd
|
|
yuuji@0
|
125 imaps stream tcp nowait.100 root /usr/local/etc/imapd imapd
|
|
yuuji@0
|
126 (or, if you use TCP wrappers)
|
|
yuuji@0
|
127 pop3 stream tcp nowait.100 root /usr/local/etc/tcpd ipop3d
|
|
yuuji@0
|
128 imap stream tcp nowait.100 root /usr/local/etc/tcpd imapd
|
|
yuuji@0
|
129 pop3s stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d
|
|
yuuji@0
|
130 imaps stream tcp nowait.100 root /usr/local/etc/imapd imapd
|
|
yuuji@0
|
131
|
|
yuuji@0
|
132 NOTE: do *NOT* use TCP wrappers (tcpd) for the imaps and pop3s services! I
|
|
yuuji@0
|
133 don't know why, but it doesn't work with TCP wrappers.
|
|
yuuji@0
|
134
|
|
yuuji@0
|
135
|
|
yuuji@0
|
136 STEP 2: services setup
|
|
yuuji@0
|
137
|
|
yuuji@0
|
138 You may also have to edit your /etc/services (or Yellow Pages,
|
|
yuuji@0
|
139 NetInfo, etc. equivalent) to register these services, such as:
|
|
yuuji@0
|
140
|
|
yuuji@0
|
141 pop 109/tcp
|
|
yuuji@0
|
142 pop3 110/tcp
|
|
yuuji@0
|
143 imap 143/tcp
|
|
yuuji@0
|
144 imaps 993/tcp
|
|
yuuji@0
|
145 pop3s 995/tcp
|
|
yuuji@0
|
146
|
|
yuuji@0
|
147 NOTE: The SSL IMAP service *MUST* be called "imaps", and the SSL POP3 service
|
|
yuuji@0
|
148 *MUST* be called "pop3s".
|
|
yuuji@0
|
149
|
|
yuuji@0
|
150
|
|
yuuji@0
|
151 STEP 3: PAM setup
|
|
yuuji@0
|
152
|
|
yuuji@0
|
153 If your system has PAM (Pluggable Authentication Modules -- most
|
|
yuuji@0
|
154 modern systems do) then you need to set up PAM authenticators for imap and
|
|
yuuji@0
|
155 pop. The correct file names are
|
|
yuuji@0
|
156 /etc/pam.d/imap
|
|
yuuji@0
|
157 and
|
|
yuuji@0
|
158 /etc/pam.d/pop
|
|
yuuji@0
|
159
|
|
yuuji@0
|
160 It probably works to copy your /etc/pam.d/ftpd file to the above two
|
|
yuuji@0
|
161 names.
|
|
yuuji@0
|
162
|
|
yuuji@0
|
163 Many people get these file names wrong, and then spend a lot of time
|
|
yuuji@0
|
164 trying to figure out why it doesn't work. Common mistakes are:
|
|
yuuji@0
|
165 /etc/pam.d/imapd
|
|
yuuji@0
|
166 /etc/pam.d/imap4
|
|
yuuji@0
|
167 /etc/pam.d/imap4rev1
|
|
yuuji@0
|
168 /etc/pam.d/imaps
|
|
yuuji@0
|
169 /etc/pam.d/ipop3d
|
|
yuuji@0
|
170 /etc/pam.d/pop3d
|
|
yuuji@0
|
171 /etc/pam.d/popd
|
|
yuuji@0
|
172 /etc/pam.d/pop3
|
|
yuuji@0
|
173 /etc/pam.d/pop3s
|
|
yuuji@0
|
174
|
|
yuuji@0
|
175
|
|
yuuji@0
|
176 STEP 4: certificates setup
|
|
yuuji@0
|
177
|
|
yuuji@0
|
178 NOTE: We can NOT provide you with support in obtaining certificates. If you
|
|
yuuji@0
|
179 need help in doing this, try the contacts mentioned in the OpenSSL README.
|
|
yuuji@0
|
180
|
|
yuuji@0
|
181 WARNING: Do NOT install servers built with SSL support unless you also plan to
|
|
yuuji@0
|
182 install proper certificates! It is NOT supported to run SSL-enabled servers
|
|
yuuji@0
|
183 on a system without the proper certificates.
|
|
yuuji@0
|
184
|
|
yuuji@0
|
185 You must set up certificates on /usr/local/ssl/certs (this may be
|
|
yuuji@0
|
186 different if you have a non-standard installation of OpenSSL; for example,
|
|
yuuji@0
|
187 FreeBSD has modified OpenSSL to use /usr/local/certs). You should install
|
|
yuuji@0
|
188 both the certificate authority certificates from the SSL distribution after
|
|
yuuji@0
|
189 building OpenSSL, plus your own certificates. The latter should have been
|
|
yuuji@0
|
190 purchased from a certificate authority, although self-signed certificates are
|
|
yuuji@0
|
191 permissible. A sample certificate file is at the end of this document.
|
|
yuuji@0
|
192
|
|
yuuji@0
|
193 Install the resulting certificate file on /usr/local/ssl/certs, with a
|
|
yuuji@0
|
194 file name consisting of the server name and a suffix of ".pem". For example,
|
|
yuuji@0
|
195 install the imapd certificate on /usr/local/ssl/certs/imapd.pem and the ipop3d
|
|
yuuji@0
|
196 certificate on /usr/local/ssl/certs/ipop3d.pem. These files should be
|
|
yuuji@0
|
197 protected against random people accessing them. It is permissible for
|
|
yuuji@0
|
198 imapd.pem and ipop3d.pem to be links to the same file.
|
|
yuuji@0
|
199
|
|
yuuji@0
|
200 The imapd.pem and ipop3d.pem must contain a private key and a
|
|
yuuji@0
|
201 certificate. The private key must not be encrypted.
|
|
yuuji@0
|
202
|
|
yuuji@0
|
203 The following command to openssl can be used to create a self-signed
|
|
yuuji@0
|
204 certificate with a 10-year expiration:
|
|
yuuji@0
|
205 req -new -x509 -nodes -out imapd.pem -keyout imapd.pem -days 3650
|
|
yuuji@0
|
206
|
|
yuuji@0
|
207 *** IMPORTANT ***
|
|
yuuji@0
|
208 We DO NOT recommend, encourage, or sanction the use of self-signed
|
|
yuuji@0
|
209 certificates. Nor will we be responsible for any problems (including security
|
|
yuuji@0
|
210 problems!) which result from your use of a self-signed certificate. Use of
|
|
yuuji@0
|
211 self-signed certificates should be limited to testing only. Buy a real
|
|
yuuji@0
|
212 certificate from a certificate authority!
|
|
yuuji@0
|
213
|
|
yuuji@0
|
214 *** IMPORTANT ***
|
|
yuuji@0
|
215
|
|
yuuji@0
|
216 If you have a multihomed system with multiple domain names (and hence
|
|
yuuji@0
|
217 separate certificates for each domain name), you can append the IP address
|
|
yuuji@0
|
218 to the service name. For example, the IMAP certificate for [12.34.56.78]
|
|
yuuji@0
|
219 would be /usr/local/ssl/certs/imapd-12.34.56.78.pem and so on. You only need
|
|
yuuji@0
|
220 to use this feature if you need to use multiple certificates (because different
|
|
yuuji@0
|
221 DNS names are used).
|
|
yuuji@0
|
222
|
|
yuuji@0
|
223
|
|
yuuji@0
|
224 SAMPLE CERTIFICATE FILE
|
|
yuuji@0
|
225
|
|
yuuji@0
|
226 Here is a sample certificate file. Do *NOT* use this on your own
|
|
yuuji@0
|
227 machine; it is simply an example of what one would look like.
|
|
yuuji@0
|
228
|
|
yuuji@0
|
229 -----BEGIN RSA PRIVATE KEY-----
|
|
yuuji@0
|
230 MIICXQIBAAKBgQDHkqs4YDbakYxRkYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP
|
|
yuuji@0
|
231 7mN87g+aaiQzwXUVndaCw3Zm6cOG4mytf20jPZq0tvWnjEB3763sorpfpOe/4Vsn
|
|
yuuji@0
|
232 VBFjyQY6YdqYXNmjmzff5gTAecEXOcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQAB
|
|
yuuji@0
|
233 AoGBAMd3YkZAc9LUsig8iDhYsJuAzUb4Qi7Cppj73EBjyqKR18BaM3Z+T1VoIpQ1
|
|
yuuji@0
|
234 DeXkr39heCrN7aNCdTh1SiXGPG6+fkGj9HVw7LmjwXclp4UZwWp3fVbSAWfe3VRe
|
|
yuuji@0
|
235 LM/6p65qogEYuBRMhbSmsn9rBgz3tYVU0lDMZvWxQmUWWg7BAkEA6EbMJeCVdAYu
|
|
yuuji@0
|
236 nQsjwf4vhsHJTChKv/He6kT93Yr/rvq5ihIAPQK/hwcmWf05P9F6bdrA6JTOm3xu
|
|
yuuji@0
|
237 TvJsT/rIvQJBANv0yczI5pUQszw4s+LTzH+kZSb6asWp316BAMDedX+7ID4HaeKk
|
|
yuuji@0
|
238 e4JnBK//xHKVP7xmHuioKYtRlsnuHpWVtNkCQQDPru2+OE6pTRXEqT8xp3sLPJ4m
|
|
yuuji@0
|
239 ECi18yfjxAhRXIU9CUV4ZJv98UUbEJOEBtx3aW/UZbHyw4rwj5N511xtLsjpAkA9
|
|
yuuji@0
|
240 p1XRYxbO/clfvf0ePYP621fHHzZChaUo1jwh07lXvloBSQ6zCqvcF4hG1Qh5ncAp
|
|
yuuji@0
|
241 zO4pBMnwVURRAb/s6fOxAkADv2Tilu1asafmqVzpnRsdfBZx2Xt4oPtquR9IN0Q1
|
|
yuuji@0
|
242 ewRxOC13KZwoAWtkS7l0mY19WD27onF6iAaF7beuK/Va
|
|
yuuji@0
|
243 -----END RSA PRIVATE KEY-----
|
|
yuuji@0
|
244 -----BEGIN CERTIFICATE-----
|
|
yuuji@0
|
245 MIIECTCCA3KgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBujELMAkGA1UEBhMCVVMx
|
|
yuuji@0
|
246 EzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1NlYXR0bGUxHzAdBgNVBAoT
|
|
yuuji@0
|
247 FkJsdXJkeWJsb29wIEluZHVzdHJpZXMxFjAUBgNVBAsTDUlTIERlcGFydG1lbnQx
|
|
yuuji@0
|
248 ITAfBgNVBAMTGEJvbWJhc3RpYyBULiBCbHVyZHlibG9vcDEoMCYGCSqGSIb3DQEJ
|
|
yuuji@0
|
249 ARYZYm9tYmFzdGljQGJsdXJkeWJsb29wLmNvbTAeFw0wMDA2MDYwMDUxMTRaFw0x
|
|
yuuji@0
|
250 MDA2MDQwMDUxMTRaMIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv
|
|
yuuji@0
|
251 bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0
|
|
yuuji@0
|
252 cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj
|
|
yuuji@0
|
253 IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5
|
|
yuuji@0
|
254 Ymxvb3AuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDHkqs4YDbakYxR
|
|
yuuji@0
|
255 kYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP7mN87g+aaiQzwXUVndaCw3Zm6cOG
|
|
yuuji@0
|
256 4mytf20jPZq0tvWnjEB3763sorpfpOe/4VsnVBFjyQY6YdqYXNmjmzff5gTAecEX
|
|
yuuji@0
|
257 OcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQABo4IBGzCCARcwHQYDVR0OBBYEFD+g
|
|
yuuji@0
|
258 lcPrnpsSvIdkm/eol4sYYg09MIHnBgNVHSMEgd8wgdyAFD+glcPrnpsSvIdkm/eo
|
|
yuuji@0
|
259 l4sYYg09oYHApIG9MIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv
|
|
yuuji@0
|
260 bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0
|
|
yuuji@0
|
261 cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj
|
|
yuuji@0
|
262 IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5
|
|
yuuji@0
|
263 Ymxvb3AuY29tggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADgYEAwEEk
|
|
yuuji@0
|
264 JXpVXVaFTuG2VJGIzPOxQ+X3V1Cl86y4gM1bDbqlilOUdByUEG4YfSb8ILIn+eXk
|
|
yuuji@0
|
265 WzMAw63Ww5t0/jkO5JRs6i1SUt0Oy80DryNRJYLBVBi499WEduro8GCVD8HuSkDC
|
|
yuuji@0
|
266 yL1Rdq8qlNhWPsggcbhuhvpbEz4pAfzPkrWMBn4=
|
|
yuuji@0
|
267 -----END CERTIFICATE-----
|
