confusa

Getting Confusa

Debian package

A Debian package (Lenny) of the latest version is usually available in the download section of Confusa's assembla space. Since Confusa is entirely composed of PHP and shell scripts, it should work on both 32-bit and 64-bit architectures. Make sure to additionally install the simplesamlphp package, which can also be found in the files section, since Confusa requires simplesamlphp for AuthN.

VirtualBox image

For quickly testing the functionality of Confusa, an image for the virtual machine VirtualBox is provided at the Confusa Beta downloads site. The instance in the image bypasses authentication and can be regarded as a demo of Confusa.

Sourcecode checkout

We use Git as a SCM. You can checkout the current master by executing

git clone git://git.assembla.com/confusa.git

The second thing you'll need is simplesamlphp, for authentication. You can get it from Google Code or check it out from its subversion repository by executing

svn checkout http://simplesamlphp.googlecode.com/svn/trunk/ simplesamlphp

Follow these instructions on how to install simplesamlphp.

Configuring Confusa's environment

Requirements

Confusa runs on top of LAMP (Linux Apache MySQL PHP), so you need to have that software installed on your server. Particularly, you'll need

• Apache2
• MySQL 5
• openssl ( >= 0.9.8g )
• PHP ( >= 5.2.0 )
• Smarty (the PHP template engine)
• PHP PEAR with MDB2:MySQL
• The following PHP modules: mhash, mcrypt, xml-parser, curl

Configuration steps

Steps that are handled by the installer appear in italic (Installer) before the entry

1. Install the Apache Webserver
2. Install the database
mysql-server-5.0
mysql-client-5.0 (you need this for bootstrapping the tables)
3a. Install PHP
libapache2-php5
php5-mysql
PEAR::MDB2_mysql_driver
3b. For online mode, also install the following two libraries:
php5-mcrypt
php5-curl
3c. When in standalone, you will need to configure the CA aspect slightly.
One thing is to generate the key and certificate for the CA operation.
One alternative is to just use the apache SSL-keys, generating this
is really left as an exercise for the reader.
The ca_* elements in the config/confusa_config.php must be set.
4. Configure Apache to use SSL, use the following lines in your apache2/sites-enabled/appropriate.config.file and php5-openssl


# Redirect http to https
<VirtualHost your.host.org:80>
        Servername your.server.org
        Redirect permanent / https://your.host.org
</VirtualHost>

<VirtualHost your.host.org:443>
        Servername your.server.org
        SSLEngine On
        SSLProtocol All
        SSLCipherSuite ALL:!ADH:!EXPORT56:!EXPORT40:RC4+RSA:!SSLv2:+HIGH:+MEDIUM:+LOW:+EXP
        SSLVerifyClient optional_no_ca
        SSLVerifyDepth 10
        SSLOptions +StdEnvVars +ExportCertData
        SSLCertificateFile /etc/apache2/ssl/slcstest.crt
        SSLCertificateKeyFile /etc/apache2/ssl/slcstest.key

	...
</VirtualHost>




Note that ServerName can be the same as the host-name in VirtualHost. Make sure you create the folder /etc/apache2/ssl/ as the create-ca.sh will put hostkeys there for you (a self-signed certificate, you should get a properly signed certificate for any production-grade instances of Confusa!).

Alternatively, if you don't want to use this script, put the key/certificate in the folder of your choice and configure the 2 lines in the given config-file.

Finally, this is a sample configuration. If you know your way around an Apache configuration, this should be more of a guideline than anything else.

5. confusa uses simpleSAMLphp to handle AuthN, and thus, you should configure simpleSAMLphp before venturing on.

Note: A minimal configuration of simplesamlphp can also be done by the Installer (init/install.sh)

In saml20-sp-hosted.php, let the __DYNAMIC:1-entry from template stay, but add the custom Authentication Processing Filters for Confusa:

   'authproc' => array(
        60 => 'core:CountryMap',
	61 => 'core:NRENMap',
    ),
    'ForceAuthn'	 => true
    

Note: Symlinking the authproc filters will be done by the installer in init/install.sh if you want to use it

You will have to either copy or symlink these into simplesamlphp/modules/core/lib/Auth/ like this:




	ln -s /var/www/confusa/include/ConfusaAttributeMap.php /var/www/simplesamlphp/modules/core/lib/Auth/Process/CountryMap.php
	ln -s /var/www/confusa/include/NRENMap.php /var/www/simplesamlphp/modules/core/lib/Auth/Process/NRENMap.php

6a. If you did not use the Debian package, put Confusa in a directory like /var/www/confusa

6b. Configure Apache with something along the following line:

   Alias /confusa "/var/www/confusa/www/"
	     Alias /simplesaml "/var/www/simplesamlphp/www/"
             <Directory /var/www/confusa/www>
                        Options Indexes MultiViews
                        AllowOverride None
                        Order allow,deny
                        Allow from all
             </Directory>
      

then reload the config: /etc/init.d/apache2 reload (or httpd (or other relevant name for apache - consult your distro's documentation) and reload.
This will enable your host to show the www directory of the confusa-folder.

6c.(Installer) Configure the confusa_config.php file. See the section on configuration for more information

6d.(Installer) Run the create_database.sh script in confusa/init folder This will create the database, the user and the tables. it will use the confusa_config.php file, so make sure that this is configured properly before you run this script.

6e.(Installer) Add a cron-job of the following type:

   */5 *   * * * /var/www/confusa/programs/clean_db.sh

This will run the clean_db script every 5 minutes and keep the database nice and tidy.

Add a cron-job that takes backup of the database. The most critical part is the certificate hash part. A sample script lies in confusa/programs. Note that this is a simple mysqldump script that dumps the database specified in confusa_config

7.(Installer) If you want NREN-admins to be able to customize the appearance of Confusa, you have to give the apache user write permissions to the "custom" folders in /var/lib/confusa. If the directory does not exist, you have to create it. The apache user is often called 'www-data', sometimes also 'apache' or something else.
If you are unsure about the user-name and have apache running, try to find it out by executing

ps aux | grep [a]pache | awk '{print $1}'


or


ps aux | grep [h]ttpd | awk '{print $1}'

If your apache username is www-data, execute

mkdir -p /var/lib/confusa/css_custom/
mkdir -p /var/lib/confusa/graphics_custom/
chown -R www-data /var/lib/confusa/css_custom/
chown -R www-data  /var/lib/confusa/graphics_custom/
chmod -R 0755 /var/lib/confusa/css_custom/
chmod -R 0755 /var/lib/confusa/graphics_custom/

8. If Confusa is going to be used by actual NRENs, bootstrap an initial NREN by calling

sh init/bootstrap_nren.sh mynren initial_admin_user@mynren.org contact_info@mynren.org

This will add mynren to the NRENs stored in Confusa, define the user with eduPersonPrincipalName initial_admin_user@mynren.org as an admin of that NREN and add contact_info@mynren.org as the NREN's contact information.

9.(standalone only, Installer) If you want Confusa to be be able to sign certificates with its own installed CA certificate, you have to create the CA working directory in folder /var/lib/confusa/cert and give it the right permissions. To be able to sign certificates in the first place, deploy the CA-cert, depending on the configuration in confusa_config.php, in Confusa's cert_handle/cert/ directory and the CA-key in cert_handle/priv. If you run the Installer, it will ask if you want to copy a key pair from some position on your hard-drive to the Confusa directory.

mkdir -p /var/lib/confusa/cert/
chown -R www-data.www-data /var/lib/confusa/cert/

Furthermore, the webserver must be able to read the private key of the CA, so it can actually sign certificates. It is also best if the permissions on the private key are as restricted as possible:

chown www-data.www-data /usr/share/confusa/cert_handle/priv/ca_key.pem
chmod 400 /usr/share/confusa/cert_handle/priv/ca_key.pem

Configuring Confusa

Using the installer

Confusa can be configured using the Installer shell script in it's init directory. It can be called by executing

sudo sh init/install.sh

Root permissions are required for full database access, so all the necessary tables can be created by the installer.

The installer will ask for the most important configuration options and set the permissions for the required directories right. Not all configuration options are covered by the installer, but only those needed for basic service of Confusa. All the options can still be fine-tuned by manually editing confusa_config.php after calling the installer.

The configuration file

All configuration options for Confusa can be set in confusa_config.php, in Confusa's config/ folder. In the beginning, only the template confusa_config_template.php exists and should be copied to confusa_config.php. This is done automatically by the installer. All important config-switches are preceeded by comments that roughly explain what they are doing.

The following three Config switches have the rather nasty property that Confusa will work without you changing them, but it is important to set them to the right value nevertheless.

ca_mode

This will influence the whole way in which Confusa signs certificates. It expects one of the following two values

• CA_STANDALONE: Use your own CA certificate/key, to be found in cert_handle, to sign certificate signing requests made to Confusa. This way, Confusa will be able to sign certificates autonomously, but you have to make sure yourself, that your CA is trusted by any relying parties that might be accessed with Confusa-issued certificates.

• CA_ONLINE: CSRs uploaded to Confusa will be forwarded to an Online-CA, which is currently Comodo and get signed there. Once the certificates have been processed by the Online-CA, the user can retrieve them from there via Confusa. To the user, the existence of an Online-CA is mostly transparent, as she will only use the Confusa interface to upload requests and download certificates.

capi_test (Online)

This flag is mostly for testing the Online-CA interface, without doing much harm by having a lot of valid and trusted certificates. Therefore, if capi_test is set to true, certificates will be

• Cluttered by TEST string (subjects like DC=TEST CERTIFICATE, DC=org, DC=terena, DC=tcs, C=NO, O=TEST UNIVERSITY openidp, CN=TEST PERSON John Doe john@doe.biz)

• Valid for only 14 days

• Revocation will only be simulated, not actually performed

capi_enc_pw (Online)

That password will be used to encrypt the credentials that the different NRENs use to connect to the Online-CA in the database. Try to set it to something fairly long and random, so the Comodo credentials of the NRENs may sleep safely in the database.

Setting up the robotic interface

Add the following configuration to your apache site configuration (the SSL virtual host):

Alias /confusa_robot "/var/www/confusa/robot_www/"
<Directory /var/www/confusa/robot_www/>
    SSLVerifyClient require
    SSLVerifyClient optional_no_ca
    Options Indexes FollowSymLinks Multiviews
    AllowOverride None
    Order deny,allow
    allow from all
</Directory>

You want to create a separate directory so you can enforce the certificate requirement and let apache fail if the client does not provide a certificate. Confusa will halt if no certificate is present, but you will save some extra cycles by setting Apache to handle this.