1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/SSLBUILD	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,267 @@
     1.4 +/* ========================================================================
     1.5 + * Copyright 1988-2007 University of Washington
     1.6 + *
     1.7 + * Licensed under the Apache License, Version 2.0 (the "License");
     1.8 + * you may not use this file except in compliance with the License.
     1.9 + * You may obtain a copy of the License at
    1.10 + *
    1.11 + *     http://www.apache.org/licenses/LICENSE-2.0
    1.12 + *
    1.13 + * 
    1.14 + * ========================================================================
    1.15 + */
    1.16 +
    1.17 +		  SSL/TLS BUILD AND INSTALLATION NOTES FOR UNIX
    1.18 +			 Last Updated: 15 November 2007
    1.19 +
    1.20 +PREREQUISITES BEFORE STARTING:
    1.21 + 1) Review the information in imap-2007/docs/BUILD.
    1.22 + 2) Obtain a copy of OpenSSL.  OpenSSL is available from third parties.  We
    1.23 +    do not provide OpenSSL.
    1.24 + 3) Make sure that you know how to build OpenSSL properly on the standard
    1.25 +    /usr/local/ssl directory.  In particular, /usr/local/ssl/include (and
    1.26 +    /usr/local/ssl/include/openssl) and /usr/local/ssl/lib must be set up
    1.27 +    from the OpenSSL build.  If you have a non-standard installation, then
    1.28 +    you must modify the imap-2007/src/osdep/unix/Makefile file to point
    1.29 +    to the appropriate locations.
    1.30 + 4) Make sure that you know how to obtain appropriate certificates on your
    1.31 +    system.
    1.32 +
    1.33 +NOTE: We can NOT provide you with support in building/installing OpenSSL, or
    1.34 +in obtaining certificates.  If you need help in doing this, try the contacts
    1.35 +mentioned in the OpenSSL README.
    1.36 +
    1.37 +
    1.38 +SSL BUILD:
    1.39 +
    1.40 +     By default, the IMAP toolkit builds with SSL and disabling plaintext
    1.41 +passwords unless SSL/TLS encryption is in effect (SSLTYPE=nopwd).  This
    1.42 +produces an IMAP server which is compliant with RFC 3501 security
    1.43 +requirements.
    1.44 +
    1.45 +     To build with SSL but allow plaintext passwords in insecure sessions,
    1.46 +add "SSLTYPE=unix" to the make command line.  Note that doing so will
    1.47 +produce an IMAP server which is NON-COMPLIANT with RFC 3501.
    1.48 +
    1.49 +     To build without SSL, add "SSLTYPE=none" to the make command line.
    1.50 +Note that doing so will produce an IMAP server which is NON-COMPLIANT
    1.51 +with RFC 3501.
    1.52 +
    1.53 +     There are other make options relevant to SSL, described in
    1.54 + imap-2007/src/osdep/unix/Makefile
    1.55 +The most important of these are SSLDIR, SSLCRYPTO, and SSLRSA.
    1.56 +
    1.57 +     SSLDIR is set to /usr/local/ssl by default.  This is the normal
    1.58 +installation directory for OpenSSL.  If your system uses a different directory
    1.59 +you will need to change this.
    1.60 +
    1.61 +     SSLCRYPTO is set to -lcrypto by default.  Older versions of MIT Kerberos
    1.62 +also have a libcrypto and will cause a library name conflict.  If you are
    1.63 +using an older version of Kerberos, you may need to change SSLCRYPTO to
    1.64 +$(SSLLIB)/libcrypto.a
    1.65 +
    1.66 +     SSLRSA is set empty by default.  It can be set to specify the RSAREF
    1.67 +libraries, which you once had to use with OpenSSL to use RSA algorithms
    1.68 +legally if you are in the USA, due to patent issues.  Since RSA Security Inc.
    1.69 +released the RSA algorithm into the public domain on September 6, 2000, there
    1.70 +is no longer any reason to do this.
    1.71 +
    1.72 +
    1.73 +SSL INSTALLATION:
    1.74 +
    1.75 +     Binaries from the build are:
    1.76 +	imap-2007/mtest/mtest		c-client testbed program
    1.77 +	imap-2007/ipopd/ipop2d		POP2 daemon
    1.78 +	imap-2007/ipopd/ipop3d		POP3 daemon
    1.79 +	imap-2007/imapd/imapd		IMAP4rev1 daemon
    1.80 +
    1.81 +     mtest is normally not used except by c-client developers.
    1.82 +
    1.83 +STEP 1:	inetd setup
    1.84 +
    1.85 +
    1.86 +     The ipop2d, ipop3d, and imapd daemons should be installed in a system
    1.87 +daemon directory and invoked by a listener such as xinetd or inetd.  In the
    1.88 +following examples, /usr/local/etc is used).
    1.89 +
    1.90 +STEP 1(A): xinetd-specific setup
    1.91 +
    1.92 +     If your system uses xinetd, the daemons are invoked by files in your
    1.93 +/etc/xinetd.d directory with names corresponding to the service names (that
    1.94 +is: imap, imaps, pop2, pop3, pop3s).  You will need to consult your local
    1.95 +xinetd documentation to see what should go into these files.  Here is a a
    1.96 +sample /etc/xinetd.d/imaps file:
    1.97 +
    1.98 +service imaps
    1.99 +{
   1.100 +	disable		= no
   1.101 +	socket_type	= stream
   1.102 +	wait		= no
   1.103 +	user		= root
   1.104 +	server		= /usr/local/etc/imapd
   1.105 +	groups		= yes
   1.106 +	flags		= REUSE IPv6
   1.107 +}
   1.108 +
   1.109 +STEP 1(B): inetd-specific setup
   1.110 +
   1.111 +     If your system still uses inetd, the daemons are invoked by your
   1.112 +/etc/inetd.conf file with lines such as:
   1.113 +
   1.114 +pop	stream	tcp	nowait	root	/usr/local/etc/ipop2d	ipop2d
   1.115 +pop3	stream	tcp	nowait	root	/usr/local/etc/ipop3d	ipop3d
   1.116 +imap	stream	tcp	nowait	root	/usr/local/etc/imapd	imapd
   1.117 +pop3s	stream	tcp	nowait	root	/usr/local/etc/ipop3d	ipop3d
   1.118 +imaps	stream	tcp	nowait	root	/usr/local/etc/imapd	imapd
   1.119 +
   1.120 +     Please refer to imap-2007/docs/BUILD for an important note about inetd's
   1.121 +limit on the number of new connections.  If that note applies to you, and you
   1.122 +can configure the number of connection in /etc/inetd.conf as described in
   1.123 +imap-2007/docs/build, here is the sample /etc/inetd.conf entry with SSL:
   1.124 +
   1.125 +pop3	stream	tcp	nowait.100	root	/usr/local/etc/ipop3d	ipop3d
   1.126 +pop3s	stream	tcp	nowait.100	root	/usr/local/etc/ipop3d	ipop3d
   1.127 +imap	stream	tcp	nowait.100	root	/usr/local/etc/imapd	imapd
   1.128 +imaps	stream	tcp	nowait.100	root	/usr/local/etc/imapd	imapd
   1.129 + (or, if you use TCP wrappers)
   1.130 +pop3	stream	tcp	nowait.100	root	/usr/local/etc/tcpd	ipop3d
   1.131 +imap	stream	tcp	nowait.100	root	/usr/local/etc/tcpd	imapd
   1.132 +pop3s	stream	tcp	nowait.100	root	/usr/local/etc/ipop3d	ipop3d
   1.133 +imaps	stream	tcp	nowait.100	root	/usr/local/etc/imapd	imapd
   1.134 +
   1.135 +NOTE: do *NOT* use TCP wrappers (tcpd) for the imaps and pop3s services!  I
   1.136 +don't know why, but it doesn't work with TCP wrappers.
   1.137 +
   1.138 +
   1.139 +STEP 2:	services setup
   1.140 +
   1.141 +     You may also have to edit your /etc/services (or Yellow Pages,
   1.142 +NetInfo, etc. equivalent) to register these services, such as:
   1.143 +
   1.144 +pop		109/tcp
   1.145 +pop3		110/tcp
   1.146 +imap		143/tcp
   1.147 +imaps		993/tcp
   1.148 +pop3s		995/tcp
   1.149 +
   1.150 +NOTE: The SSL IMAP service *MUST* be called "imaps", and the SSL POP3 service
   1.151 +*MUST* be called "pop3s".
   1.152 +
   1.153 +
   1.154 +STEP 3: PAM setup
   1.155 +
   1.156 +     If your system has PAM (Pluggable Authentication Modules -- most
   1.157 +modern systems do) then you need to set up PAM authenticators for imap and
   1.158 +pop.  The correct file names are
   1.159 +	/etc/pam.d/imap
   1.160 +and
   1.161 +	/etc/pam.d/pop
   1.162 +
   1.163 +     It probably works to copy your /etc/pam.d/ftpd file to the above two
   1.164 +names.
   1.165 +
   1.166 +     Many people get these file names wrong, and then spend a lot of time
   1.167 +trying to figure out why it doesn't work.  Common mistakes are:
   1.168 +	/etc/pam.d/imapd
   1.169 +	/etc/pam.d/imap4
   1.170 +	/etc/pam.d/imap4rev1
   1.171 +	/etc/pam.d/imaps
   1.172 +	/etc/pam.d/ipop3d
   1.173 +	/etc/pam.d/pop3d
   1.174 +	/etc/pam.d/popd
   1.175 +	/etc/pam.d/pop3
   1.176 +	/etc/pam.d/pop3s
   1.177 +
   1.178 +
   1.179 +STEP 4:	certificates setup
   1.180 +
   1.181 +NOTE: We can NOT provide you with support in obtaining certificates.  If you
   1.182 +need help in doing this, try the contacts mentioned in the OpenSSL README.
   1.183 +
   1.184 +WARNING: Do NOT install servers built with SSL support unless you also plan to
   1.185 +install proper certificates!  It is NOT supported to run SSL-enabled servers
   1.186 +on a system without the proper certificates.
   1.187 +
   1.188 +     You must set up certificates on /usr/local/ssl/certs (this may be
   1.189 +different if you have a non-standard installation of OpenSSL; for example,
   1.190 +FreeBSD has modified OpenSSL to use /usr/local/certs).  You should install
   1.191 +both the certificate authority certificates from the SSL distribution after
   1.192 +building OpenSSL, plus your own certificates.  The latter should have been
   1.193 +purchased from a certificate authority, although self-signed certificates are
   1.194 +permissible.  A sample certificate file is at the end of this document.
   1.195 +
   1.196 +     Install the resulting certificate file on /usr/local/ssl/certs, with a
   1.197 +file name consisting of the server name and a suffix of ".pem".  For example,
   1.198 +install the imapd certificate on /usr/local/ssl/certs/imapd.pem and the ipop3d
   1.199 +certificate on /usr/local/ssl/certs/ipop3d.pem.  These files should be
   1.200 +protected against random people accessing them.  It is permissible for
   1.201 +imapd.pem and ipop3d.pem to be links to the same file.
   1.202 +
   1.203 +     The imapd.pem and ipop3d.pem must contain a private key and a
   1.204 +certificate.  The private key must not be encrypted.
   1.205 +
   1.206 +     The following command to openssl can be used to create a self-signed
   1.207 +certificate with a 10-year expiration:
   1.208 +	req -new -x509 -nodes -out imapd.pem -keyout imapd.pem -days 3650
   1.209 +
   1.210 +			*** IMPORTANT ***
   1.211 +     We DO NOT recommend, encourage, or sanction the use of self-signed
   1.212 +certificates.  Nor will we be responsible for any problems (including security
   1.213 +problems!) which result from your use of a self-signed certificate.  Use of
   1.214 +self-signed certificates should be limited to testing only.  Buy a real
   1.215 +certificate from a certificate authority!
   1.216 +
   1.217 +			*** IMPORTANT ***
   1.218 +
   1.219 +     If you have a multihomed system with multiple domain names (and hence
   1.220 +separate certificates for each domain name), you can append the IP address
   1.221 +to the service name.  For example, the IMAP certificate for [12.34.56.78]
   1.222 +would be /usr/local/ssl/certs/imapd-12.34.56.78.pem and so on.  You only need
   1.223 +to use this feature if you need to use multiple certificates (because different
   1.224 +DNS names are used).
   1.225 +
   1.226 +
   1.227 +SAMPLE CERTIFICATE FILE
   1.228 +
   1.229 +     Here is a sample certificate file.  Do *NOT* use this on your own
   1.230 +machine; it is simply an example of what one would look like.
   1.231 +
   1.232 +-----BEGIN RSA PRIVATE KEY-----
   1.233 +MIICXQIBAAKBgQDHkqs4YDbakYxRkYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP
   1.234 +7mN87g+aaiQzwXUVndaCw3Zm6cOG4mytf20jPZq0tvWnjEB3763sorpfpOe/4Vsn
   1.235 +VBFjyQY6YdqYXNmjmzff5gTAecEXOcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQAB
   1.236 +AoGBAMd3YkZAc9LUsig8iDhYsJuAzUb4Qi7Cppj73EBjyqKR18BaM3Z+T1VoIpQ1
   1.237 +DeXkr39heCrN7aNCdTh1SiXGPG6+fkGj9HVw7LmjwXclp4UZwWp3fVbSAWfe3VRe
   1.238 +LM/6p65qogEYuBRMhbSmsn9rBgz3tYVU0lDMZvWxQmUWWg7BAkEA6EbMJeCVdAYu
   1.239 +nQsjwf4vhsHJTChKv/He6kT93Yr/rvq5ihIAPQK/hwcmWf05P9F6bdrA6JTOm3xu
   1.240 +TvJsT/rIvQJBANv0yczI5pUQszw4s+LTzH+kZSb6asWp316BAMDedX+7ID4HaeKk
   1.241 +e4JnBK//xHKVP7xmHuioKYtRlsnuHpWVtNkCQQDPru2+OE6pTRXEqT8xp3sLPJ4m
   1.242 +ECi18yfjxAhRXIU9CUV4ZJv98UUbEJOEBtx3aW/UZbHyw4rwj5N511xtLsjpAkA9
   1.243 +p1XRYxbO/clfvf0ePYP621fHHzZChaUo1jwh07lXvloBSQ6zCqvcF4hG1Qh5ncAp
   1.244 +zO4pBMnwVURRAb/s6fOxAkADv2Tilu1asafmqVzpnRsdfBZx2Xt4oPtquR9IN0Q1
   1.245 +ewRxOC13KZwoAWtkS7l0mY19WD27onF6iAaF7beuK/Va
   1.246 +-----END RSA PRIVATE KEY-----
   1.247 +-----BEGIN CERTIFICATE-----
   1.248 +MIIECTCCA3KgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBujELMAkGA1UEBhMCVVMx
   1.249 +EzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1NlYXR0bGUxHzAdBgNVBAoT
   1.250 +FkJsdXJkeWJsb29wIEluZHVzdHJpZXMxFjAUBgNVBAsTDUlTIERlcGFydG1lbnQx
   1.251 +ITAfBgNVBAMTGEJvbWJhc3RpYyBULiBCbHVyZHlibG9vcDEoMCYGCSqGSIb3DQEJ
   1.252 +ARYZYm9tYmFzdGljQGJsdXJkeWJsb29wLmNvbTAeFw0wMDA2MDYwMDUxMTRaFw0x
   1.253 +MDA2MDQwMDUxMTRaMIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv
   1.254 +bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0
   1.255 +cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj
   1.256 +IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5
   1.257 +Ymxvb3AuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDHkqs4YDbakYxR
   1.258 +kYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP7mN87g+aaiQzwXUVndaCw3Zm6cOG
   1.259 +4mytf20jPZq0tvWnjEB3763sorpfpOe/4VsnVBFjyQY6YdqYXNmjmzff5gTAecEX
   1.260 +OcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQABo4IBGzCCARcwHQYDVR0OBBYEFD+g
   1.261 +lcPrnpsSvIdkm/eol4sYYg09MIHnBgNVHSMEgd8wgdyAFD+glcPrnpsSvIdkm/eo
   1.262 +l4sYYg09oYHApIG9MIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv
   1.263 +bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0
   1.264 +cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj
   1.265 +IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5
   1.266 +Ymxvb3AuY29tggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADgYEAwEEk
   1.267 +JXpVXVaFTuG2VJGIzPOxQ+X3V1Cl86y4gM1bDbqlilOUdByUEG4YfSb8ILIn+eXk
   1.268 +WzMAw63Ww5t0/jkO5JRs6i1SUt0Oy80DryNRJYLBVBi499WEduro8GCVD8HuSkDC
   1.269 +yL1Rdq8qlNhWPsggcbhuhvpbEz4pAfzPkrWMBn4=
   1.270 +-----END CERTIFICATE-----