Introduction

First you should download and install the latest YK-VAL release:

Depending on your distribution, the group of Apache (or the HTTP server) might be different from www-data, used in Debian and Ubuntu. On Red Hat, Fedora or CentOS the group is apache and in SUSE it is www.

The rest of this documentation will assume you have YK-VAL available in the default installation targets. You can override the paths, see the Makefile.

You also need to install a web server with PHP5, php5-curl and php-pear.

Any web server with PHP support should work.

Any SQL database with PHP support should work. We give examples for MySQL and PostgreSQL here. Note that you need to chose between either PostgreSQL or MySQL here.

The interface to verify OTPs is implemented using a PHP script. You can place the script under any URL, but we recommend serving it as http://ykval.example.org/wsapi/verify. The simplest way to setup the symlinks is to invoke make symlink in your YK-VAL source tree. Like this:

If you want to do it manually, you can invoke the above commands manually.

Set the include path for the queue daemon by creating a file /etc/default/ykval-queue with the following content:

You also need to set the include path for the PHP scripts running via Apache, using a .htaccess file:

The .htaccess file also sets up rewriting from the non-.PHP suffix URL name to the right script.

The paths are the default, if you installed the YK-VAL in some other place you need to modify the paths.

You also need to create a ykval-config.php script. An example file is included in YK-VAL package as ykval-config.php

A template is typically installed in /etc/yubico/val/ykval-config.php-template.

Be careful about the user permissions and ownership so that unrelated users on the system cannot read the database password.

You will typically need to modify the DSN (__YKVAL_DB_DSN__), database passwords (__YKVAL_DB_PW__), the sync pool lists (__YKVAL_SYNC_POOL__ and __YKVAL_ALLOWED_SYNC_POOL__), and the YK-KSM URLs inside the otp2ksmurls function.

An example DSN for a MySQL setup:

An example DSN for a PostgreSQL setup:

We recommend to add the hosts in YKVAL_SYNC_POOL as entries in /etc/hosts to avoid network delays caused by DNS-lookups. For example:

To improve database performance you can use persistent database connection so that each request doesn’t require a new connection to be setup. To enable this modify __YKVAL_DB_OPTIONS__ as follows:

Create an apache web configuration file for the normal HTTP interface like this:

HTTPS is strictly speaking not required, but we strongly recommend it.

You need to install a TLS stack for Apache, there are two popular options here: mod_gnutls and mod_ssl. We’ll explain how to install both, but you will need to decide which one to use.

You will need to create a key/certificate for your server using normal tools like GnuTLS "certtool". A small howto for !GoDaddy is available from http://permalink.gmane.org/gmane.comp.encryption.gpg.gnutls.devel/4062.

The PHP interface uses syslog for logging of incoming requests. The facility is LOG_LOCAL0. To place these messages in a separate file, you can add the following to /etc/syslog.conf, or if you use rsyslog, create a file /etc/rsyslog.d/ykval.conf with this content:

The - before the filename avoids syncing the file after each write, which is recommended for performance.

The log file can grow large quickly, so it is a good idea to setup rotation of log files. Here is an example that rotates the log file weekly. Create a file /etc/logrotate.d/ykval like this:

You may want to modify the default /etc/logrotate.d/apache2, useful things to add are dateext and compress and change rotate to something large if you want to retain logs.

Unfortunately, most default syslog configuration, including the syslog.conf configuration file on Debian, will also log all entries to /var/log/syslog and/or /var/log/messages.

I am not aware of any way to avoid this without modifying these other rules. To avoid YK-VAL log entries in these other files, you must modify the default rules. For example, edit the following lines of /etc/rsyslog.conf (or /etc/syslog.conf if you don’t use rsyslog):

Change them into:

Idempotent commands to speed this up:

When using yubikey-val in a sync pool, you need to have the ykval-queue daemon running to ensure that data is synchronized between the servers in the pool. The easiest way of running this is to simply invoke ykval-queue in a shell:

However, the recommended approach is to automate running this process in the background, by use of an init script or similar. Instructions on doing so vary depending on your operating system.

If you’re adding a new server to an existing pool, you can synchronize all YubiKey counter data from one of the existing servers. To do so, the server you want to sync from needs to be configured to allow it. Do this by editing /etc/yubico/val/ykval-config.php on the existing server, adding the new servers IP address to the __YKRESYNC_IPS__ setting. You’ll most likely want to add the IP to the __YKVAL_ALLOWED_SYNC_POOL__ setting as well. You also need to edit this file on the new server, adding the existing server(s) IP address(es) to __YKVAL_ALLOWED_SYNC_POOL__.

Once these permissions have been configured, you can initiate the full sync by running the following command from the new server:

You can test the service by requesting a URL. Using wget, for example:

Naturally, you will need to import client keys into the database for the verify function to work properly.

You now have a YK-VAL up and running. See https://developers.yubico.com/yubikey-ksm/Server_Hardening.html on how to improve security of your system.