On this page you will find instructions on how to set up a Trust Router APC on Debian 7 (Wheezy) using FreeRADIUS. It also installs and configures the Trust Router client.

Contents

Complexity of Installation

Many of the steps outlined below are currently necessary, but we realise the install should be simpler. As the software matures and the packaging improves, we will to make this process easier with fewer manual steps required.

1. System Preparation

1.1. Install Debian 7

The first thing that is required is a Debian 7 machine - this can be physical or virtual.

Install Debian 7 (Wheezy) via usual mechanism (e.g netboot CD, ISO in VMware/VirtualBox or the DVD image.
Choose the following server install options: "Debian desktop, SSH server, Standard system utilities”.
Create/choose a secure root password and an initial system user account.
Once installed, make sure you run an apt-get update and apt-get upgrade to ensure your system is fully up to date.

Tip

We would recommend using LVM when disk partitioning to allow easier partition/disk expansion on a live system.

Warning

After install, you will want to secure/lockdown the server as best practice dictates - for both the server and any extra software installed. This is beyond the remit of this guide but there are many guides available, e.g. for securing Debian, and SSH servers.

1.2. Configure Debian 7

Next, there are a few Debian configuration options that need to be set in advance.

1.2.1. Networking configuration

For production deployments, it is recommended that the Moonshot APC be assigned a static IP address.

For Debian networking information please refer to the Debian documentation: https://wiki.debian.org/NetworkConfiguration

1.2.2. Firewall configuration

The following ports are required to be accessible from the outside world, both in local firewall and in any external firewalls:

2083/tcp (for RadSec connections to other Moonshot entities)
12309/tcp (for Trust Router client connections - if using the Trust Router to broker trust relationships between entities)

1.3. Add the Moonshot Repository

Add the Moonshot Debian Wheezy repository to your system. To do this, run the following command (as root, or using sudo):
```
$ echo "deb http://repository.project-moonshot.org/debian-moonshot wheezy main" > /etc/apt/sources.list.d/moonshot.list
```

Install the Moonshot GPG key:

$ wget -O - http://repository.project-moonshot.org/key.gpg | apt-key add -

Update the apt cache with the new repository information:
```
$ apt-get update
```

2. Install the Software

We’re now ready to install the Moonshot software and its required dependencies. Install the software by running the following command:

$ apt-get install freeradius-abfab freeradius moonshot-gss-eap moonshot-ui moonshot-trust-router dbus-x11

If you try to start FreeRADIUS at this point, it will not currently start successfully as the certificates it requires have not been generated - they are created in step 3.1 below.

3. Configure the Moonshot APC

Next, we need to configure the Moonshot APC.

3.1. Configure FreeRADIUS

3.1.1. Certificates

We need to get FreeRADIUS to create some private and public keys to use for its RadSec connections. Create and install the certificates by doing the following (as root).

Change into the /etc/freeradius/certs directory
```
$ cd /etc/freeradius/certs
```
Edit the certificate generation properties in client.cnf, server.cnf, and ca.cnf as following:
1. In the ca.cnf file:
  1. In the [ req ] section, add encrypt_key = no
  2. In the [CA_default] section, change the default_days from 60 to a higher number (this is how long the certificates you create will be valid for). When the certificates expire, you will have to recreate them.
  3. in the [ certificate_authority ] section, change all of the parameters to match those of your organisation. e.g.
    [certificate_authority] countryName = GB stateOrProvinceName = England localityName = Camford organizationName = Camford University emailAddress = support@camford.ac.uk commonName = "Camford University FR Certificate Authority"
2. In the server.cnf file:
  1. In the [ req ] section, add encrypt_key = no
  2. In the [CA_default] section, change the default_days from 60 to a higher number (this is how long the certificates you create will be valid for). When the certificates expire, you will have to recreate them.
  3. in the [ server ] section, change all of the parameters to match those of your organisation. e.g.
    [server] countryName = GB stateOrProvinceName = England localityName = Camford organizationName = Camford University emailAddress = support@camford.ac.uk commonName = "Camford University FR Server Certificate"
3. In the client.cnf file:
  1. In the [ req ] section, add encrypt_key = no
  2. In the [CA_default] section, change the default_days from 60 to a higher number (this is how long the certificates you create will be valid for). When the certificates expire, you will have to recreate them.
  3. in the [ client ] section, change all of the parameters to match those of your organisation. e.g.
    [client] countryName = GB stateOrProvinceName = England localityName = Camford organizationName = Camford University emailAddress = support@camford.ac.uk commonName = "Camford University FR Client Certificate"
    All of the organisation parameters (countryName, localityName, etc) need to match in the three .cnf files but the commonName must be unique in each file)
Clear out any old certificates in the directory
```
$ make destroycerts
```
Run the bootstrap script to generate the certificates
```
$ ./bootstrap
```
Create a file that is the concatenation of the certificate and private key of the client.
1. Create the file
```
$ openssl x509 -in client.crt > client.pem ; cat client.key >> client.pem
```
2. Cerify that the client.pem file starts with "-----BEGIN CERTIFICATE-----".

3.1.2. Moonshot UI credential store

We need to enable the freeradius user to use the Moonshot UI flatstore:

$ echo "freerad" >> /etc/moonshot/flatstore-users

3.1.3. RadSec

Next we need to configure RadSec. We do this by creating a file at /etc/radsec.conf with the following:

realm gss-eap {
	type = "TLS"
	cacertfile = "/etc/freeradius/certs/ca.pem"
	certfile = "/etc/freeradius/certs/client.pem"
	certkeyfile = "/etc/freeradius/certs/client.key"
	disable_hostname_check = yes
	server {
		hostname = "127.0.0.1"
		service = "2083"
		secret = "radsec"
	}
}

3.1.4. Realm

We next need to configure your realm in the FreeRADIUS server so that it knows not to send any requests for your own users off to another server.

Configure your realm in /etc/freeradius/proxy.conf
1. Open the file for editing and fine the line “realm example.com {“
2. Above this, add the following, where YOUR_REALM should be substituted for the realm you intend to use for your APC:
```
realm YOUR_REALM {
	# Intentionally left blank
}
```

3.1.5. EAP Type

Set the EAP type in use by moonshot (EAP-TTLS) by editing /etc/freeradius/mods-enabled/eap. Find the first instance of default_eap_type = md5 and change it to TTLS, i.e.:

default_eap_type = ttls

Other EAP types should be supported (PEAP and MD5 have been tested).

3.1.6. Channel Bindings

Turn on channel bindings in freeradius by symlinking the chbind module:

$ ln -s /etc/freeradius/sites-available/chbind /etc/freeradius/sites-enabled/chbind

4. Testing

4.1. Testing the Trust Router connection

To test the connection to Trust Router, we need to make sure the Temporary Identity Server (TIDS) software is running, then use the Temporary Identity Client (TIDC) software to simulate a connection to the Trust Router.

4.1.1. Testing using the Temporary Identity Client (TIDC)

In window 2, (as the freerad user) run the tidc command:
```
$ su --shell /bin/bash freerad
$ unset DISPLAY
$ tidc tr1.moonshot.ja.net [your rp-realm] apc.moonshot.ja.net apc.moonshot.ja.net
```
This uses the "tidc" binary which is used in the following way - tidc [hostname-of-trust-router] [rp-realm] [hostname-of-apc-server] [apc-name]

If the Trust Router connection was successful, you should see something like the following:

In window 2 - TIDC output

TIDC Client:
Server = tr1.moonshot.ja.net, rp_realm = moonshot-idp.camford.ac.uk, target_realm = apc.moonshot.ja.net, community = apc.moonshot.ja.net
connecting to host 'tr1.moonshot.ja.net' on port 12309
CTRL-EVENT-EAP-STARTED EAP authentication started
CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
CTRL-EVENT-EAP-PEER-CERT [...]
CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
tidc_fwd_request: Sending TID request:

[...]

tr_msg_decode_tidresp(): Success! result = success.
tr_msg_decode_servers(): Number of servers = 1.
Response received! Realm = apc.moonshot.ja.net, Community = apc.moonshot.ja.net.
Client Key Generated (len = 256):

[...]

4.1.2. Starting the Temporary Identity Server (TIDS)

In window 3 (window 1 should still be still running the FreeRADIUS server and window 2 the TIDC command), run the TIDS software:
```
$ tids [your server IP] trustrouter@apc.moonshot.ja.net [your server hostname] /var/lib/trust_router/keys
```
trustrouter@apc.moonshot.ja.net is the identity that the trust router will use when provisioning keys - this makes it easy to spot in your own log files.
Specifying your server's IP and hostname may seem redundant (and for single server deployments, it is!). You'll need to set the hostname and IP arguments a little differently if you want to enable some more advanced configurations (such as load balancing and key sharing).

This uses the "tids" binary which is used in the following way - tids [your-ip-address] trustrouter-gss-name] [your-hostname] [path-to-key-database]

When using Network Address Translation (NAT) or a firewall, you must specify your external IP address.

5. Next Steps

At this point, you now have a Moonshot APC that is working. Now for the next steps:

5.1. Automatically start the software

5.1.1. FreeRADIUS

To automatically start FreeRADIUS, issue the following command (as root):

$ sudo update-rc.d freeradius defaults

5.1.2. TIDS

We currently don't have an initscript for the TIDS, you have to run it manually.

5.2. Configure a real source of Authentication

Your FreeRADIUS server can currently only authenticate a single user - "testuser". At this point, you will want to connect to your management database. The FreeRADIUS site has information and instructions for how to do this.

Install an APC on Debian 7