imap/docs/SSLBUILD

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