The Yubikey is a nice little device. It’s quite simple in design and operation. 
The key actually emulating a USB keyboard, which makes it instantly usable on any modern OS. You just press the button on the key to generate a one-time-password (OTP) to validate you. The method works by typing in your password, but before hitting the return key, you press the Yubikey button to finish it off. At the end of the OTP generation, it sends a carriage return itself.
The OTP is then sent to a validation server, either hosted by Yubico themselves, or you can host your own.
I’m going to walk through how you can set the infrastructre for doing two-factor authentication on Debian. In my specific case, the requirement was two-factor with an Active Directory username/password combination and the Yubikey as the second factor.
Unfortunately, the documentation from Yubico is quite average. To top it off, they insist on using multiple Google Code project sites for hosting their software.
This would normally be fine, but in this case, they have a Google Code project for every single little piece of code. Much of the documentation I found relates to older projects which are not supported by Yubico. This makes working out exactly what you need difficult. Within the Google Code project sites, documentation often runs in circles between projects.
In this document, I’ll look at using PAM to auth again the Yubico auth servers first. Once that’s working, I’ll move onto flashing the Yubikey with a new key and using our own Validation System.
NOTE: This is just some rough notes I put together. You should definitely read the Yubico documentation for this to really make sense.
Authenticating with the Yubikey with PAM
Get some dependencies
apt-get install libpam-dev libcurl4-openssl-dev libpam-radius-auth
Make ourselves a source directory
mkdir ~/yubikey; cd ~/yubikey
Get the current tarball of libyubikey, and install it
wget http://yubico-c.googlecode.com/files/libyubikey-1.5.tar.gz
tar xf libyubikey-1.5.tar.gz
cd libyubikey-1.5
./configure
make check install
Get the current tarball of the Yubico C client, and install it
wget http://yubico-c-client.googlecode.com/files/ykclient-2.3.tar.gz
tar -xf ykclient-2.3.tar.gz
cd ykclient-2.3
./configure
make
make install
Get the current tarball of the Yubico PAM module, and install it
wget http://yubico-pam.googlecode.com/files/pam_yubico-2.3.tar.gz
tar -xf pam_yubico-2.3.tar.gz
cd pam_yubico-2.3
./configure
make
make install
You should end up with your Yubico PAM module ‘/usr/local/lib/security/pam_yubico.so’
We’ll refer to this in our PAM config /etc/pam.d/openvpn
#
# /etc/pam.d/openvpn - OpenVPN pam configuiration
#
# We fall back to the system default in /etc/pam.d/common-*
#
auth required /usr/local/lib/security/pam_yubico.so id=1 debug authfile=/etc/yubikeyid
auth required pam_radius_auth.so no_warn try_first_pass
@include common-account
@include common-password
@include common-session
This configuration will tell PAM to hit the Yubico module first. This splits apart your password field into your password and OTP. The OTP is validated against the Validation Servers, and the password is then passed onto the next module. This configuration will use the Yubico auth servers to check your token.
Once you have a working config, we’ll move to setting up our own Validation Servers. We’ll need to specify the URL for that in this config later on.
In that case, we’re also using RADIUS. This could be LDAP if you had an LDAP server available. You should be able to use the standard UNIX credentials (/etc/password, /etc/shadow) also.
The other important piece to note here is the authfile, /etc/yubikeyid
This file lists the mapping between username and the fixed part of your Yubikey. This is the first 12 chars of the Yubikey OTP (e.g. when you press the button)
abotting:vvcnrdkvevtj
FreeRADIUS authenticating against Active Directory 2008.
I banged my head against a wall for a while on this one. The trick is that you need at least FreeRADIUS 2.1.6 for AD authentication to work properly.
Add Debian backports to your /etc/apt/sources.list
deb http://www.backports.org/debian lenny-backports main contrib non-free
Import the backports key
wget -O - http://backports.org/debian/archive.key | apt-key add -
Update and install the new freeradius
apt-get update
apt-get -t lenny-backports install freeradius freeradius-ldap
In your radiusd.conf
ldap {
# Define the LDAP server and the base domain name
server = "ad.yourcompany.com"
basedn = "dc=ad, dc=yourcompany, dc=com"
# Active Directory doesn't allow for Anonymous Binding
identity = "ldap_bind_user@ad.yourcompany.com"
password = password
password_attribute = "userPassword"
filter = "(&(sAMAccountname=%{Stripped-User-Name:-%{User-Name}})(memberOf=CN=Users,DC=ad,DC=yourcompany,DC=com))"
# This fixes Active Directory 2008 access
chase_referrals = yes
rebind = yes
# The following are RADIUS defaults
start_tls = no
dictionary_mapping = ${raddbdir}/ldap.attrmap
ldap_connections_number = 5
timeout = 4
timelimit = 3
net_timeout = 1
}
In our FreeRADIUS client file /etc/freeradius/clients.conf:
client localhost {
ipaddr = 127.0.0.1
secret = testing123
nastype = other
}
Use radtest to test our RADIUS is authenticating properly
radtest <username> <password> localhost 1 testing123
Should return Accept.
Set the address and shared secret of the radius server in /etc/pam_radius_auth.conf. The password of testing123 was defined in our RADIUS client config.
# server[:port] shared_secret timeout (s)
127.0.0.1 testing123 1
OpenVPN has an issue with PAM loading the Yubikey module, so we have to LD_PRELOAD the pam module before starting OpenVPN.
export LD_PRELOAD=/lib/libpam.so.0.81.12; openvpn --config openvpn.conf
For a permanent fix, at the end of the start_vpn function in /etc/init.d/openvpn, just before the $DAEMON line:
export LD_PRELOAD=/lib/libpam.so.0.81.12
$DAEMON $OPTARGS --writepid /var/run/openvpn.$NAME.pid \
$DAEMONARG $STATUSARG --cd $CONFIG_DIR \
--config $CONFIG_DIR/$NAME.conf || STATUS=1
Change the path of /lib/libpam.so.0.81.12 to suit your own system.
I won’t go into the OpenVPN configuration, except that for PAM authentication you need these options in your server config:
plugin /usr/lib/openvpn/openvpn-auth-pam.so openvpn
username-as-common-name
ns-cert-type server
client-cert-not-required
Personalising your Yubikey
To host your own Yubikey validation system, you require the secret AES key of your Yubikey. In the past, Yubico could provide this to you. Now, you’re required to flash your Yubikey yourself which will generate a new AES key.
Yubico provide a personalisation tool for Linux, Mac and Windows. If you’re on Windows, you get a nice little GUI. For Linux and Mac, you have a CLI based tool. It’s worth having a look at the ‘Personalization Tool’ page at: http://www.yubico.com/developers/personalization/
Installing the Personalisation Tool
Install some dependencies:
apt-get install libusb-1.0.0-dev
Grab the latest Pesonalisation Tool tarball from: http://code.google.com/p/yubikey-personalization/
cd ~/yubikey
wget http://yubico-c.googlecode.com/files/libyubikey-1.5.tar.gz
Extract, build and install libyubikey
tar xf libyubikey-1.5.tar.gz
cd libyubikey-1.5
./configure
make
make install
You’ll need to provide a UID value for flashing your Yubikey. It needs to be 6 characters, and in hexadecimal. You can use this command to generate one for you.
dd if=/dev/urandom of=/dev/stdout count=100 2>/dev/null | xargs -0 modhex | cut -c 1-10 | awk '{print "vv" $1}'
74657374696e
You must provide the public name (fixed) parameter in modhex format. The modhex format is a special encoding used to ensure characters sent by the key are always correctly interpreted whatever keyboard layout you use.
You also need to generate yourself a public name for your key. This is known as the ‘fixed’ part, and it’ll be the first 16 chars when you generate your OTP. This will identify your key from anybody else’s.
dd if=/dev/urandom of=/dev/stdout count=100 2>/dev/null | xargs -0 modhex | cut -c 1-10 | awk '{print "vv" $1}'
vvcnrdkvevtj
This comamnd generate some random text, does a modhex operation, grabs the first 10 chars, then adds ‘vv’ to the front to make it up to 12.
You’ll be prompted for a passphrase on your AES key. I leave mine blank, but if you do set one, don’t ever lose it. I believe it’ll stop you from re-personalising your Yubikey.
ykpersonalize -ouid=74657374696e -ofixed=vvcnrdkvevtj
Firmware version 2.1.2 Touch level 1793 Program sequence 1
Passphrase to create AES key:
Configuration data to be written to key configuration 1:
fixed: m:vvcnrdkvevtj
uid: h:74657374696e
key: h:fcaad309a20ne1809c2db2f7f0e8d6ea
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags:
Commit? (y/n) [n]: y
Save this information, as we’ll need it later.
Setting up yor own YubiKey OTP Validation Server
You need to install two things: The Key Storage Module and the Yubico Validation Server. The Key Storage Module (KSM) holds the secret AES key of your Yubikey token, while the Validation Server does the OTP check against the KSM.
In their 2.0 architecture, you can have multiple KSM’s and Validation servers with work together for reduncancy.
KSM Installation
Make a working directory, and get the KSM package
mkdir ~/yubikey && cd ~/yubikey
wget http://yubikey-ksm.googlecode.com/files/yubikey-ksm-1.3.tgz
tar xfz yubikey-ksm-1.3.tgz
Install the KSM files
cd yubikey-ksm-1.3
make install
Install Apache2 and PHP
Install Apache2, PHP and MySQL
apt-get install apache2 php5 php5-mcrypt php5-curl mysql-server php5-mysql libdbd-mysql-perl
Create the ykksm table
echo "CREATE DATABASE ykksm;" | mysql -u root -p
Import the DB schema
mysql -u root -p ykksm < /usr/share/doc/ykksm/ykksm-db.sql
Set up some MySQL permissions
CREATE USER 'ykksmreader';
GRANT SELECT ON ykksm.yubikeys TO 'ykksmreader'@'localhost';
SET PASSWORD FOR 'ykksmreader'@'localhost' = PASSWORD('hYea3Inb');
CREATE USER 'ykksmimporter';
GRANT INSERT ON ykksm.yubikeys TO 'ykksmimporter'@'localhost';
SET PASSWORD FOR 'ykksmimporter'@'localhost' = PASSWORD('ikSab29');
FLUSH PRIVILEGES;
Include path configuration
Set the include path by creating a file /etc/php5/conf.d/ykksm.ini
cat > /etc/php5/conf.d/ykksm.ini << EOF
include_path = "/etc/ykksm:/usr/share/ykksm"
EOF
Make a web server symlink
make -f /usr/share/doc/ykksm/ykksm.mk symlink
Set your configuration settings in /etc/ykksm/ykksm-config.php
<?php
$db_dsn = "mysql:dbname=ykksm;host=127.0.0.1";
$db_username = "ykksmreader";
$db_password = "hYe63Inb";
$db_options = array();
$logfacility = LOG_LOCAL0;
?>
Restart Apache2
/etc/init.d/apache2 restart
Test the KSM Server
Try this URL:
curl 'http://localhost/wsapi/decrypt?otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh'
ERR Unknown yubikey
It should return ‘Unknown Key’ until we have imported our Yubikey into the database.
Install the Yubico Validation Server
The latest version, and documentation can be found at: http://code.google.com/p/yubikey-val-server-php/
Installation
Go to our working source directory, and grab the package
cd ~/yubikey
wget http://yubikey-val-server-php.googlecode.com/files/yubikey-val-2.4.tgz
Extract, build and install the server
tar -zxf yubikey-val-2.4.tgz
cd yubikey-val-2.4
make install
Create the ykval database and import the schema
echo 'create database ykval' | mysql -u root -p
mysql -u root -p ykval < /usr/share/doc/ykval/ykval-db.sql
Install the symlink
make symlink
Include path configuration
cat > /etc/default/ykval-queue << EOF
DAEMON_ARGS="/etc/ykval:/usr/share/ykval
EOF
Create a htaccess file: /var/www/wsapi/2.0/.htaccess
RewriteEngine on
RewriteRule ^([^/\.\?]+)(\?.*)?$ $1.php$2 [L]
php_value include_path ".:/etc/ykval:/usr/share/ykval"
Symlink the htaccess file
cd /var/www/wsapi; ln -s 2.0/.htaccess /var/www/wsapi/.htaccess
Copy the template config file for the Validation Server
cp /etc/ykval/ykval-config.php-template /etc/ykval/ykval-config.php
Edit the file and configure settings in /etc/ykval/ykval-config.php
<?php
# For the validation interface.
$baseParams = array ();
$baseParams['__YKVAL_DB_DSN__'] = "mysql:dbname=ykval;host=127.0.0.1";
$baseParams['__YKVAL_DB_USER__'] = 'ykvalverifier';
$baseParams['__YKVAL_DB_PW__'] = 'password';
$baseParams['__YKVAL_DB_OPTIONS__'] = array();
# For the validation server sync
$baseParams['__YKVAL_SYNC_POOL__'] = array("http://localhost/wsapi/2.0/sync");
# An array of IP addresses allowed to issue sync requests
# NOTE: You must use IP addresses here.
$baseParams['__YKVAL_ALLOWED_SYNC_POOL__'] = array("127.0.0.1");
# Specify how often the sync daemon awakens
$baseParams['__YKVAL_SYNC_INTERVAL__'] = 10;
# Specify how long the sync daemon will wait for response
$baseParams['__YKVAL_SYNC_RESYNC_TIMEOUT__'] = 30;
# Specify how old entries in the database should be considered aborted attempts
$baseParams['__YKVAL_SYNC_OLD_LIMIT__'] = 10;
# These are settings for the validation server.
$baseParams['__YKVAL_SYNC_FAST_LEVEL__'] = 1;
$baseParams['__YKVAL_SYNC_SECURE_LEVEL__'] = 40;
$baseParams['__YKVAL_SYNC_DEFAULT_LEVEL__'] = 60;
$baseParams['__YKVAL_SYNC_DEFAULT_TIMEOUT__'] = 1;
// otp2ksmurls: Return array of YK-KSM URLs for decrypting OTP for
// CLIENT. The URLs must be fully qualified, i.e., contain the OTP
// itself.
function otp2ksmurls ($otp, $client) {
return array("http://localhost/wsapi/decrypt?otp=$otp",);
}
?>
In the above configuration, we’re only expecting to use one Validation Server and one KSM. If you’re planning on having multiple Validation servers and KSM’s, then you’ll be including the other Validation Servers in the SYNC_POOL, and your KSM’s in the URLs at the bottom, returned by the otp2ksmurls function.
Enable the mod_rewrite
a2enmod rewrite
Create the ykval database user
CREATE USER 'ykvalverifier'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON `ykval`. * TO 'ykvalverifier'@'localhost';
Fix some privileges on our config file
chgrp www-data /etc/ykval/ykval-config.php
The Sync Daemon uses the PEAR module System_Daemon so you need to install it:
apt-get install php-pear
pear install System_Daemon-0.9.2
Install the init.d script
ykval-queue install
update-rc.d -f ykval-queue defaults
Start the daemon
/etc/init.d/ykval-queue start
Testing
Use CURL to test our server is working
curl 'http://localhost/wsapi/verify?id=1&otp=vvcnrdkvevtefjbrjnlnldnhcujvddbikngjrtgh'
It should return something like this:
h=aPCQ4kWJilDgriyEii3j8J8lfuY=
t=2009-04-27T19:08:51Z0100
status=NO_SUCH_CLIENT
Once we import our Yubikey into the database, we should get a nice ‘status=OK’ message.
Importing your keys into the KSM server
Refer back to the output from personalising your Yubikey. You’ll need the fixed part (referred to as publicname in the DB), internal name (UID) and our AES key.
This is an entry for our newly personalised Yubikey.
USE ykksm;
INSERT INTO `yubikeys` (`serialnr`, `publicname`, `created`, `internalname`, `aeskey`, `lockcode`, `creator`, `active`, `hardware`)
VALUES (101209, 'vvcnrdkvevtj', '2010-05-07 15:18:40', '74657374696e', 'fcaad309a20ne1809c2db2f7f0e8d6ea', '000000000000', '', 1, 1);
This entry is required for our systems to authenticate against the Validation server. I’m not exactly sure about this, as the documentation is somewhat bare. I think you need an administrator-type person’s key details in here. The imporant part is the ID. This values corresponds the the ‘id=’ value in our CURL requests and in our PAM config.
USE ykval;
INSERT INTO `clients`
(`id`, `active`, `created`, `secret`, `email`, `notes`, `otp`)
VALUES
(1, 1, 1, 'fcaad309a20ne1809c2db2f7f0e8d6ea', 'your@email.addr', 'Any text your want', 'vvcnrdkvevterfbtelvnvkkueenecrlfnlhdjetrhgnk');
We’ll hit our new Validation Server to make sure it’s working
curl "http://localhost/wsapi/2.0/verify?id=1&nonce=askjdnvajsndjkasndvjsnad&otp=vvcnrdkvevtjkreuvvlhtubjecbrticjneckgrigkck"
h=KLEb3gOJ4KqQaCVbh8cEvXjH50U=
It should return something like this:
t=2010-05-20T11:24:53Z0051
otp=vvvcnrdkvevtjkreuvvlhtubjecbrticjneckgrigkck
nonce=askjdnvajsndjkasndvjsnad
sl=100
status=OK
In this URL, we’ve added the ‘nonce’ parameter. This just a test to make sure the v2.0 API is working. ‘status=OK’ means it’s all good! If you get ‘NOT_ENOUGH_ANSWERS’, it means it has trouble trying to sync with other Validation Servers.
We’ll get PAM using our new Validation Servers for auth
/etc/pam.d/openvpn
auth required /usr/local/lib/security/pam_yubico.so id=1 authfile=/etc/yubikeyid url=http://10.68.130.198/wsapi/verify?id=%d&otp=%s debug
If you watch /var/log/auth.log, you should see the PAM module spitting out some debugging information which may be useful. It also spits out your plain text password too, while you have the debug option on. Make sure you remove this later.
Problems
If you see an error like this:
PAM unable to dlopen(/lib/security/pam_yubico.so): /lib/security/pam_yubico.so: undefined symbol: pam_set_data
you’ll need the LD_PRELOAD trick from above. Something to do with dlopening the PAM module I believe.
