Tuesday, 22 July 2014

Running Crypt Server on a Mac via Server.app

(Revised for new Django 1.5 version of Crypt Server)
Crypt is software written by Graham Gilbert of pebble.it to provide a FileVault2 escrow solution. That is to provide a secure centralised store for FileVault2 recovery passwords. With this (or similar FileVault2 Escrow solution) the user or authorised administrator can generate the recovery key to get back into a FileVault2 protected machine should the user forget their original code or leave the company. See http://grahamgilbert.com/blog/2013/01/18/crypt-a-filevault-2-escrow-solution/

Crypt consists of two parts, a client part which firstly enforces the use of FileVault2 encryption on the computer and secondly stores the details for the recovery key in the matching Crypt Server. There are other similar solutions available but Crypt has the advantages of being free and not using any external hosted systems.

Whilst (obviously) the client part of Crypt is native Mac software designed to run on Macs, currently the only official documentation for the Crypt Server is aimed at running Crypt Server on a Ubuntu Linux Server. It is certainly possible to run the Crypt Server on an Ubuntu Server with Mac clients by following those instructions and you can even host the Ubuntu Server in a Virtual Machine running on a Mac, e.g. in VirtualBox. However some people might prefer to run Crypt Server natively on an existing OS X Server and this article therefore describes how to achieve this.

Firstly we need to look at the requirements for running Crypt Server -
Of these Apache is included on all Macs as is Python, Django can be easily installed but mod_wsgi is only included if you have Server.app installed on top of Lion or Mountain Lion. This article is only aimed at how to get Crypt Server working with Server.app. As Server.app is very cheap if your unwilling to pay even that modest sum then your on your own and perhaps should stick to using the free Ubuntu Server approach. So in terms of this article the full requirements will be -

OS X Lion or OS X Mountain Lion

I will be differing from the normal Crypt Server install instructions so as to be able to integrate with Apple's Server.app approach. I will be including download links for the configuration files I had to create to achieve this.

Step 1.
Ensure you have Server.app installed and have run it at least once so it can configure itself. As is best practice your server should have a static IP address. The only service in Server.app we will require is the webserver service. We will configure this later. You can if you wish run other services and even other websites on the server you will be using. In order to be able to run multiple websites on the standard port 80, you need to have at least one extra DNS name pointing to this server. So if its main DNS name (A record) is server.example.com you would add an alias (CNAME) and pick a new name for that for example cryptserver.example.com this will allow using a website name of cryptserver.example.com for the website we will be using.

Note: I see no benefit to running Crypt Server on a (web) server accessible from the Internet. In fact I would suggest from a security point of view you should only run it on an internal private server. This does mean client machines will need to be setup either on the internal private network or via a VPN connection to the private internal network.

Step 2.
We will be installing various Django and other python modules. The standard Ubuntu instructions describe using apt-get and pip to install these modules. Neither of these commands is as standard part of OS X however we can install pip very easily by using the built-in 'easy_install' command. So the first command will be

sudo easy_install pip

We now have the pip command installed so we can now use it to install the other modules as follows. First we will install VirtualEnv which allocates the modules to an environment private for the use of Crypt to prevent conflicts with any other python based software which might use different versions of these modules.
(You can check to see if virtualenv is already installed by typing the command virtualenv -–version if it is already installed then you can skip this step.)
sudo pip install virtualenv
We will then create the environment for Crypt.
cd /usr/local
(virtualenv prefers using the bash shell rather than the standard sh shell)
sudo virtualenv crypt_env
cd crypt_env
sudo source bin/activate
sudo pip install django==1.5.3
(The current version of Crypt Server is now written specifically for Django 1.5 and has not been tested with Django 1.6, the above command ensures that Django 1.5.3 is used.)
sudo pip install south
sudo pip install django-bootstrap_toolkit
Step 3.
We will now download the Crypt Server software. This is available here https://github.com/grahamgilbert/Crypt-Server this can in theory be downloaded using a GIT client however I chose to download the ZIP archive listed on the right-hand side and save having to install GIT on my server.

In order to have file paths matching (as much as possible) the original Ubuntu instructions and also to match the settings files I am providing you then need to expand the zip file and move/copy the resulting folder of files as follows. The zip file contains at the top a single folder called crypt-server-master and in that various subfolders. The folder crypt-server-master needs to be renamed crypt and moved into /usr/local/crypt_env/ therefore the path to crypt will become /usr/local/crypt_env/crypt/ I did this in Terminal.app.
Step 4.
We now need to create a wsgi file, the author provides an example one but strangely does not include it in the zip file, so here is one I prepared earlier crypt.wsgi :)

Note: Oops! Just discovered on 22nd July 2014 that the link above to the example crypt.wsgi was pointing to an old incorrect version, I have updated the link to point to a corrected version.

You need to download that file and copy it to /usr/local/crypt_env/crypt/crypt.wsgi
Note: Apple's Server.app will not process python webapps unless they use the file extension .wsgi if you try using the file extension .py they will not work.
Step 5.
We now need to create and configure the settings file for Crypt Server, first we copy the example file.
sudo cd /usr/local/crypt_env/crypt/fvserver/
sudo cp example_settings.py settings.py

We now need to edit settings.py pick your favourite commandline editor, e.g. nano, pico or vi.

You need to set the Administrator email details and the TimeZone for your server. This step is the same as the original Ubuntu instructions. You can therefore look at section 27 here http://derflounder.wordpress.com/2012/12/31/first-look-at-crypt/
Step 6.
We now need to generate the database that Crypt Server will use to store the accounts and FileVault2 recovery keys. To do this we use the following commands.
sudo cd /usr/local/crypt_env/crypt/
sudo python manage.py syncdb

These steps are again the same as the original Ubuntu instructions so you can look at section 28 here http://derflounder.wordpress.com/2012/12/31/first-look-at-crypt/

Note: The user account being created here is only used internally in the database it is not linked in anyway to Open Directory or any other OS X user account. It is used when you login to Crypt Server via a web-browser.

Then we do

sudo python manage.py migrate
sudo python manage.py collectstatic

Again this is the same as the standard Ubuntu instructions so see sections 29 and 30 here http://derflounder.wordpress.com/2012/12/31/first-look-at-crypt/

We have now in theory finished installing and setting up Crypt Server, the remaining steps will be integrating it into Apple's Server.app

Step 7.
Launch Server.app and go to the webserver service. Create a new website using the hostname you chose in step 1. Leave it using the standard port 80 and all IP addresses settings. Click on the Edit button next to Aliases and add a rule to map from a path of /static/ to a folder (any folder) we will be manually editing this later because Server.app does not let you browse to /usr/local where we need it to point to.

You should now quit Server.app for now, do not start the webservice yet. Next we want to manually edit the apache conf file corresponding to the website you have just created. This will be located in /Library/Server/Web/Config/apache2/sites/ it will have a name something like 0000_any_80_cryptserver.example.com.conf the exact name will depend on the host name you are using. You need to edit this in Terminal.app using your favourite editor. You want to set the line beginning with DocumentRoot (the fourth line typically) to the following

DocumentRoot "/usr/local/crypt_env/crypt"

You also want to set the line beginning with <Directory similarly as follows

<Directory "/usr/local/crypt_env/crypt">
Finally we want to edit the line beginning Alias /static/ it will be need the bottom of this file, change it to the following
Alias /static/ "/usr/local/crypt_env/crypt/static/"
We have to do this manually because the files for Crypt Server are not in the normal websites folder location, and because in Server.app you cannot browse and set the location to somewhere in /usr/local/ as this is 'hidden' from view.

Note: Fortunately my experience is that once this change is made manually, Server.app respects it and does not later overwrite it.

The standard Ubuntu instructions tell you to run the website with an additional user account setup specifically for it and that you need to add an additional command to the apache conf file you have just edited above. I could not get those instructions to work with Server.app but fortunately it is not necessary to do so. If you follow the instructions here the website will run successfully with the standard _www account. You do need however to set the ownership of the Crypt Server files to _www so that the standard account can access and modify the Crypt Server database. To do this issue the following command

sudo chown -R _www /usr/local/crypt_env

Step 8.
We now need to setup the extra config files to make the Crypt Server django webapp available as a webapp that will be listed in Server.app and this will allow us to have this webapp run when someone accesses this website. In this article I will merely tell you what to put where and how to then turn it on, but for more details on how you setup webapps in general with Server.app see my other article about this topic available here http://jelockwood.blogspot.co.uk/2013/06/running-django-webapps-with-os-x.html

You need to first place a file called com.crypt.webapp.wsgi.plist in /Library/Server/Web/Config/apache2/webapps/ here is a copy of com.crypt.webapp.wsgi.plist I have made for you. You also need to place a file called httpd_crypt.conf in /Library/Server/Web/Config/apache2/ here is a copy of httpd_crypt.conf for you to use.

You can now open Server.app again. Go to the webserver service and select the website you previously added in step 7 above. Edit the website by clicking on the pencil button, scroll down and click on the 'Edit Advanced Settings...' button. You should now see a list of available webapps, the one you want to enable (tick) is the 'FileVault Escrow Server'. This corresponds to the webapp that the two files you have just installed has defined and this will run the Crypt Server webapp when you access this website. Then click OK and then click Done. You can now start the websites service.

All being well you should now be able to access the Crypt Server in a web-browser at a URL like http://cryptserver.example.com/ depending on what hostname you are using.