HOWTO: Installing Apache-SSL on MacOS X Server Revision 6 November 16, 2000 Ben Srour Table of Contents ============ Introduction Assumptions/rants Requirements Installation Configuration Starting the Server Disabling Your Old Server Things NOT to do Comments on egd Troubleshooting Links Introduction The purpose of this document is to give you a simple (or not) explanation of how to install apache-ssl on your MacOS X Server. You probably would not be reading this if you didn't know what SSL is but for those who are clueless: SSL (Secure Sockets Layer) is a protocol developed for full strength general cryptography. This protocol is used on the web as a protocol for having a secure connection between the client (Netscape et al.) and server (apache-ssl). Once you have apache-ssl installed correctly on your system you will be able to use your MacOS X Server as a secure online solution. There is no substitute for experimenting on your own and reading documentation from the authors of all the peices of software needed to get everything working the way you want. I provide this simply to give you my experience in installing apache-ssl on my OSX Server. Assumptions/rants The average MacOS administrator that has migrated to MacOSX Server is not necessarily familiar with Unix system administration. Although this is not a prerequistite it woulld be a good idea to become familiar with the system configuration from the commandline rather than through the gui. I mention this because you are obviously concerned about security (or else you would not be reading this) so I ask you to please be conscientous administrators concerned with system security! All too often administrators place too much trust in OS vendors. Although the MacOS has had an amazing track record regarding security, the MacOS is now Unix and this means that its now more of a target by crackers than ever before. To install Apache-SSL you need to be able to unpack a tarball (*.tar.gz) files. You do this by typing in at the commandline: gzip -d filename.tar.gz tar -xvf filename.tar I recommend that as a MacOS X admin you spend some time at some Unix security websites and keep tabs on the latest security issues. Just because you have SSL does not mean that your box is secure. Requirements G3 or G4 with at least 64mb ram MacOS X Server (1.0 -> 1.2) 25mb available disk space root access OpenSSL (0.9.5a as of this writing, available from www.openss.org) Apache-SSL patches (www.apache-ssl.org, the latest is 1.41) Apache source (1.3.12, available from www.apache.org) Entropy Gathering Daemon (http://www.lothar.com/tech/crypto/) egd patches for OSX (http://www.macsecurity.org/resources/gpg/egd-0.6.osxpatch.tar.gz) SSL certificate (www.verisign.com among others; check www.apache-ssl.org for a complete list) Installation The first item that needs to be installed is OpenSSL which will serve as the library (similar to the libraries found in the Extensions folder on the MacOS) that will generate the encryption needed by apache-ssl for a secure connection. OpenSSL- Installation of OpenSSL is very simple and compiles right out of the box. Once you unpack the distribution read the README and INSTALL files in the openssl-0.9.5a directory. Once you have successfully installed OpenSSL (after the 'make install' command) move the openssl-0.9.5a directory to the directory where you installed SSL (most probably /usr/local/ssl). You need to get an SSL certificate from a certificate authority like Verisign before apache-ssl will be fully functional. You could use a test certificate (instructions at www.apache-ssl.org) but eventually you should get a real one. Remove the PEM-encoded password from the private key file so that you wont have to enter a password everytime the apache-ssl daemon starts up. Instructions on this are available at www.apache-ssl.org. Apache- Unpack the apache_1.3.12.tar.gz file as you did with the openssl tarball. Move the apache_1.3.12+ssl_1.41.tar.gz file into the apache_1.3.12 directory and unpack it. Read the README.SSL and follow the directions. When you are finished glance over the README file and _read_ the INSTALL file. Often people like to keep their new apache distribution in /usr/local/apache. There is a new way to compile apache-ssl for support with egd in 1.41. Read the documentation in the apache-ssl distribution on information on how to apply the egd patches to OpenSSL. Essentially, you need the OpenSSL source available to apply the egd patch. Once ytou have applied the patch you have to compile OpenSSL. Compilation of apache with the apache-ssl patches is seamless. I had no errors while compiling and installing the distributions. Do not start httpsd yet (i.e dont start the webserver yet), you have more things left to install and configure! egd- The Entropy Gathering Daemon (cool name eh?) is designed to be a substitute for systems which lack a /dev/random device. MacOS X Server is missing (among many other things) a /dev/random device and without this OpenSSL cannot function because it will not be able to get random data from the computer to generate a seed for the secure connection for the client-server. egd is the solution to this. egd collects statistics from your computer and stirs them up in a pool of entropy which is dispersed every time you establish an SSL connection. The patch you downloaded to make egd compatible with OSX Server was written for egd-0.6 however it will work with egd-0.8, the latest version of egd with more randomeness :) Unpack egd-0.8.tar.gz and unpack the egd-0.6.osxpatch.tar.gz in the new egd-0.8 directory. Become root (su or through another login) and run the ./build.sh script. This will patch egd to compile on OSX and build the distribution. Once egd is installed (probably to /usr/bin/egd.pl) run the program by typing: 'egd.pl /tmp/entropy' egd will now be in the background collecting entropy for use with apache-ssl. Configuration Now that you have come this far you need to start configuring apache-ssl. Read the SSLconf file in the source directory of apache (apache_1.3.12). This will give you some idea of the correct syntax to use in your apache configuration. The best place to find information on real configuration is www.apache-ssl.org and the SSLconf file. The SSLconf has been updated to show the correct syntax for using egd with apache-ssl. If you kept your documents in /Local/Library/WebServer/Documents you should move the contents of that directory (or whichever directory you use) to the new Documents directory in /usr/local/apache/Documents. You don't have to do this, you can just refer to your old documents directory in your new apache-ssl configuration as: DocumentRoot "/Local/Library/WebServer/Documents". It would be a good idea to copy the apache configuration that came with OSX Server into your new configuration so that your old settings will be installed on your new server. The standard apache configuration file is stored in /Local/Library/WebServer/Configuration/apache.conf and your new apache configuration location is in /usr/local/apache/Configuration/httpd.conf. The only thing to append to this file is the SSL directives found in SSLconf, my config and the example configurations available at www.apache-ssl.org. Essentially the main directives you want are: #Logs the version of ssl and the cypher used CustomLog Logs/ssl_access "%t %{version}c %{cipher}c %{clientcert}c" #Where are all the errors go, this is great for debugging your server #to figure out problems. ErrorLog Logs/ssl_error #Enables SSL (read www.apache-ssl.org for more information on usage) SSLEnable #New directive that allows egd to be used instead of /dev/random SSLRandomFilePerConnection egd /tmp/entropy 1024 SSLCacheServerPath /usr/local/sbin/gcache SSLCacheServerPort Logs/gcache_port SSLCacheServerRunDir /tmp SSLSessionCacheTimeout 15 #Certificate you recieved from the certificate authority SSLCertificateFile /usr/local/ssl/certs/secure.cert #Keyfile you generated. Follow instructions at www.apache-ssl.org or #at the certs help page. SSLCertificateKeyFile /usr/local/ssl/private/nopass.key SSLVerifyClient 0 SSLVerifyDepth 10 Starting the New Server Before you start the new apache-ssl server you need to stop your old apache server. Run the command: /usr/sbin/apachectl stop It should report back that apache has been stopped. You need to be root to do this. Now that you have everything configured the way you want it you can start your server now. To do this type: '/usr/local/sbin/httpsdctl configtest' and make sure that your syntax in your config is good. Once you have a "Syntax OK" message start the server by typing: '/usr/local/sbin/httpsdctl start' Hopefully it will say something like this: [macosx:/usr/local/sbin] root# ./httpsdctl start Reading key for server secure.westminster-school.org:443 Launching... /usr/local/sbin/gcache pid=1510 ./httpsdctl start: httpsd started Test out your new server in a web browser by accessing http://yourdomain and https://yourdomain. If it fails read your SSL ErrorLog file then your apache error log is in the Logs directory. Disabling Your Old Server Now that you have accomplished the hardest task of all you probably want to make sure that apache-ssl runs at system boot up rather than having it start the old version of apache. Edit the file /etc/startup/2000_WebServer and change the line that reads: "/usr/sbin/apachectl start" to "/usr/local/sbin/httpdsdctl start" Under this line enter the following line to start egd. "/usr/bin/egd.pl /tmp/entropy" Now whenever you restart your OSX box your new version of apache-ssl will start. The one problem with this is that if your private keyfile is PEM encoded with a password you will have to enter this password each time you start apache-ssl. What you can do to fix this is remove the password from the keyfile. The instructions are listed on www.apache-ssl.org. Here is an excerpt: In the /usr/local/ssl/private directory type: /usr/local/ssl/openssl rsa -in privkey.pem -out nopasskey Once you remove the password you should edit the location of the keyfile in the httpd.conf file to reflect the new private key location. This would be at the SSLCertificateKeyFile directive. Things _NOT_ to do Do not turn your server on and off from the GUI. There is the possibility that it will change your startup settings to the old server. You should be familiar with the commandline by this point and if you need to turn off the server use /usr/local/sbin/httpsdctl application. Comments on egd You will notice that on occasion while accessing your store you will get a "I/O Intialization error" in the web browser and an error that looks like this in your SSL error logfile: [Fri Apr 28 16:24:08 2000] [error] SSL_accept failed [Fri Apr 28 16:24:08 2000] [error] error:24064064:random number generator:SSLEAY_RAND_BYTES:prng not seeded [Fri Apr 28 16:24:08 2000] [error] error:04069003:rsa routines:RSA_generate_key:BN lib [Fri Apr 28 16:24:08 2000] [error] error:1409B444:SSL routines:SSL3_SEND_SERVER_KEY_EXCHANGE:error generating tmp rsa key Usually a reload in the webbrowser will do the trick to get it working however you can aleviate this problem in two ways if it really bothers you but there are some conditions. You can run egd with the --bottomless option. The problem originally is that the apache-ssl server times out while waiting for egd to generate and collect entropy. The --bottomless option stops this by keeping the same entropy in the pool at all times. With this there is no need to generate new entropy and thus gets rid of your little I/O problem. However, this makes the server _considerably_ less secure because you are using the same randomness for each connection. A way around this, if you are going to take this route is to add the --quit-after=30 option with --bottomless to make it quit egd every 30 minutes. Throw egd with these options into a crontab and make it rerun every 30minutes. With this you won't have too much of a stale and static entropy pool. Troubleshooting Now that I have SSL am I secure? No. Just because you have SSL installed on your webserver does not make you invulnerable to crackers. Your OSX box should be air tight at the least (i.e using SSH, limiting inetd services, firewalling etc). You are only as secure as your weakest link. Why do I get permission denied errors when I try and install x? You need to be root to do all of the installations, editing, and moving of files. Try adding yourself to the 'wheel' group in the User editor. This will allow you to 'su root' and have root priviledges from the command line without having to login as root. Do I need my old version of apache? No, the apache-ssl you compiled supports both SSL and non-SSL connections. I am running Linux on Intel, do I need to read this HOWTO? No. This HOWTO is designed for machines that have distributions that do not support /dev/random or urandom. However, the configuration discussion I talk about could be useful to anyone; just ignore the parts about egd. Links http://www.apache-ssl.org http://www.macsecurity.org/resources/gpg/ http://www.openssl.org http://www.apache.org http://www.lothar.com/tech/crypto/