Nordic Edge™ One Time Password Server

Yubico integration

Version:              1.0.0
Date:                  2010-03-26

Copyright Nordic Edge AB, 2010
www.nordicedge.net

About Nordic Edge

Nordic Edge is a software provider of Trusted Identity and Access Management (IAM) solutions enabling organizations to secure and manage their digital identities. With Nordic Edge’s solutions, organizations can improve business processes and meet regulatory compliance requirements. The offering includes two-factor authentication, role based delegated user administration, synchronization and provisioning. Nordic Edge was founded 2001 in Sweden and has customers in more than 25 countries. All products are available as a service (Saas/IaaS) or deployed as a product. For more information, www.nordicedge.se.

Trademarks

Nordic Edge is a registered trademark of Nordic Edge AB in Sweden.

Yubico and YubiKey are registered trademark of Yubico in Sweden.

All third-party trademarks are the property of their respective owners.

1 Prerequisites

1. Document purpose

This document describes the integration of the Yubico system with the Nordic Edge One Time Password Server (OTPServer) version 3 and above.

2. Overview

Yubico is the innovation company behind the YubiKey, a revolutionary authentication key for simple and secure access to networks and services.
From version 3 of the OTPServer, Yubico support is included.

The OTPServer Yubico integration includes support for YubiKey using both the Yubico's AES algorithm as well as the OATH based HOTP algorithm.
When using the AES format the OTPServer can validate one-time passwords, generated by the YubiKey, when it is storing the AES keys together with the user object or via Yubicos own validation server using webservices calls across the Internet.
Support for auto enrollment using the token-identifier and key storing in a database is also included.

Components overview:

3. Requirements

The following are the requirements for the OTPServer and Yubico integration:

• Nordic Edge One Time Password Server version 3.0.8802 or higher
• Yubico YubiKey version 1.0 or 2.0
• If using the Yubico Validation service through a webservice, the token-id must be stored in a user object attribute from the user database available to the OTPServer.
  HTTP request on port 80 to api.yubico.com is also required.
• Write access to an attribute of the user object that will contain the key and counters if validating the AES key at the OTPServer.

• Write access to an attribute of the user object if using auto enrollment (HOTP or AES).

4. Configuration

Yubico using HOTP algorithm

When using the YubiKey with HOTP algorithm, no Yubico configuration is required.
All configuration will be done from the database configuration and the OATH Configuration dialogs.

Configuration steps

1. Create a user database that is configured for HOTP by selecting the "Uses HOTP (OATH)" checkbox at the top of the database configuration dialog
   Make sure the admin account has write access to the OATH Key attribute.
   
2. Select the attribute that contains the HOTP (OATH) key and counter.
3. Assign the database to the client
   

4. At the OATH Configuration dialog, make sure that the OTP length is set to either 6 or "Use variable OTP length" is activated and multiple OTP length is specified where one of the values must be 6

   

   If the YubiKey will append the token identifier to the one-time password, make sure the "Accept OATH Token identifier" is selected

5. Make sure the key and the counter is stored in the selected attribute, from the user object in the database, in the following format:
   key:counter example:
   5B6D588D268FD4C7AA3C9D1E172166AE099BDD7A:4
   
   

   The value will be encrypted by the OTPServer during next login if the checkbox
   "Encrypt key and counter" is selected at the OATH Configuration.

6. Save the configuration.

Yubico using AES algorithm

When using the YubiKey with the Yubico AES algorithm, the Yubico configuration dialog should be used for configuration.
The AES algorithm is supported in two ways, either by using the Yubico online validation server through webservices or by storing the AES key at the user object in a database accessible by the OTPServer, similar to the OATH HOTP configuration.

Configuring with the Yubico online validation server

If using the Yubico online validation server, the YubiKey token identifier must be stored at the user object in a readable attribute. The OTPServer assigns a specific YubiKey to a specific user but will make a webservices call to the online validation server to verify the one-time password.
For example:
When generating a one-time password, the first 12 characters are the token identifier:
cccccccbdufnbdcvhucniefjerneibliuidhldvbbuen
This value (cccccccbdufn) must be stored in an attribute at the assigned user.
Note, the value must be modhex encoded.

                                        

The OTPServer must be able to do a http request on port 80 to api.yubico.com.
Any firewall between the OTPServer and the internet must allow this request initiated from the OTPServer.

Configuration steps

1. Create a database with OTP Attribute field assigned to the attribute that will contain the token identifier.
                                  
                       Note, do not select the HOTP checkbox.

2. The client must be configured to use the database and use the external OTP API
   

3. Select the created database.
4. Select the checkbox "Uses external OTP API" and in the field that appears type:
   ext.Yubico
   Note: This is case sensitive, the Y in Yubico is uppercase, the rest is lowercase.
5. Select the Yubico dialog located under the Misc category and enable the Yubico
   Select "Use Yubico OTP Validation Server (api.yubico.com)" and select "Use static Client ID"

   
6. Save the configuration.

Test AES online validation configuration with the TestTool

1. Start the OTPTestTool
2. Connect to the OTPServer
3. First, select "Request OTP with Username and Password" from the command menu
   Enter the username and password and click Submit to initiate the authentication:
   

4. Second, select the "Verify OTP" from the command menu
   The magic number and the username will be copied from the previous request.
   Select the OneTimePassword field and press the YubiKey button to generate a one-time password into to the field.
   Then click the Submit button.
   

5. The request is now made to the Yubico online validation server and if correct, the success dialog will appear.
   If the OTP fails, go back to step 3 and make a "Request OTP with Username and Password" before a new "Verify OTP" request

   Log example:
   2010-04-05 21:18:10,612: INFO: OTPConnection [localhost] –>"AUTH-OTP" Request
   2010-04-05 21:18:10,612: DEBUG: OTPConnection [localhost] [AUTH_OTP] Database for "127.0.0.1" is "OpenDS – Yubico online validation"
   2010-04-05 21:18:10,614: INFO: DBHandler [getDNSingle] Executing Searchfilter: (&(cn=jdoe)(objectclass=inetOrgPerson))
   2010-04-05 21:18:10,615: INFO: DBHandler [getDNSingle] Found user: "cn=jdoe,ou=People,o=Nordicedge"
   2010-04-05 21:18:10,617: DEBUG: OTPConnection [localhost] [AUTH_OTP] UserDN: "cn=jdoe,ou=People,o=Nordicedge" Attr: "employeeNumber" Value: "cccccccbdufn"
   2010-04-05 21:18:10,618: DEBUG: ext.Yubico CreateOTP Request for user: jdoe
   2010-04-05 21:18:10,618: DEBUG: OTPBridge [createOTPExternally] Created OTP with API: ext.Yubico
   2010-04-05 21:20:42,003: INFO: OTPConnection [localhost] –>"Verify OTP" Request
   2010-04-05 21:20:42,003: DEBUG: OTPConnection [localhost] Checking OTP MagicNr: O0H23w for user: jdoe
   2010-04-05 21:20:42,003: DEBUG: OTPBridge [validateChallenge] Will verify by external API: ext.Yubico
   2010-04-05 21:20:43,511: INFO: ext.YubicoOTP for user: "jdoe" verified successfully
   2010-04-05 21:20:43,511: INFO: OTPConnection [localhost] OTP is Valid

Configuring with AES key stored at the user

In the configuration with the AES key stored in an attribute at the user object, the OTPServer will verify the one-time password and keep track of the counters to avoid re-using any one-time passwords.
The AES key must be stored in modhex format, example:

                

To convert hex to modhex fomat, a tool at Yubicos website can be use:
http://radius.yubico.com/demo/Modhex_Calculator.php

After the first authentication the OTPServer will append counter information to the AES key to avoid re-using one-time passwords. The OTPServer must have write access to the attribute where the AES key was stored.

Configuration steps

1. Create a database with OTP Attribute field assigned to the attribute that will contain the AES key

   

      Note, do not select the HOTP checkbox.

2. The client must be configured to use the database and use the external OTP API
   

3. Select the created database.
4. Select the checkbox "Uses external OTP API" and in the field that appears type:
   ext.Yubico
   Note, this is casesensetiv, the Y in Yubico is uppercase, the rest is lowercase.
5. Select the Yubico dialog located under the Misc category and enable the Yubico
   Select "Validate AES key at the OTPServer".

   
6. Save the configuration.

Test AES stored at the user configuration with the TestTool

1. Start the OTPTestTool
2. Connect to the OTPServer
3. First, select "Request OTP with Username and Password" from the command menu
   Enter the username and password and click Submit to initiate the authentication:
   

4. Second, select the "Verify OTP" from the command menu
   The magic number and the username will be copied from the previous request.
   Select the OneTimePassword field and press the YubiKey button to generate a one-time password into to the field.
   Then click the Submit button.
   

5. The OTPServer will read the AES key from the user object in the database and verify the OTP. If successfull, the OTPServer will update the key with the YubiKeys counter information and re-using the OTP is not possible.
   If the OTP fails, go back to step 3 and make a "Request OTP with Username and Password" before a new "Verify OTP" request.

Auto enrollment setup

The OTPServer version 3 supports auto enrollment of YubiKeys configured using either HOTP or AES keys.
If using HOTP, the YubiKey must be configured to send the token identifier with the one-time password.

The available token information (both HOTP and AES) can be stored in either a SQL database or an LDAP database.
The database must be created as a database in the OTPServer but does not have to be assigned to a client.
The OTPServer must have write access to the database.
For LDAP databases the OTPServer must have write access to the object's attribute containing the tokens. The attribute must be a multivalue string attribute and must be able to store approximately 100 or more characters. No schema modifications is required.

For SQL databases the OTPServer must have write access to the TOKENDB database and the Tokens table. The OTPServer can create the database and the table or it can be done using the following SQL commands:

CREATE DATABASE TOKENDB;
USE TOKENDB;

CREATE TABLE TOKENDB.Tokens
(
tokenid varchar(50),
keyvalue varchar(200),
counter varchar(30),
assigneddate DATETIME,
userid varchar(50)
);

Create a database for key storage (HOTP or AES)

Create either a SQL database or an LDAP database in the OTPServer
The important information is the connection information. The other information will not be used by the auto enrollment process.
LDAP example:

    

SQL example (MySQL):

    

Using HOTP auto enrollment

At the OATH Configuration dialog select the checkboxes "Accept OATH Token identifier" and "Enable Automatic Enrollment (Class A – OATH Token Identifier)"

Using SQL database

If using a SQL database for key storage, the OTPServer can create the database and the table by selecting the "Check SQL Database" button.

    

         

Using LDAP database

If using an LDAP database, select an object (can be any type of objectclass) and the attribute that will contain the token information. The attribute must be a multivalue string attribute.
Note, the attribute description will not work if using Active Directory since it is not a multivalue attribute

    

Importing tokens to the database

The import format currently supported are three types, PSKC, semicolon separated textfile and comma separated textfile.

Support for PSKC format is available with OTPServer version 3.0.13779 and above.

Semicolon separated textfile

The file format is:
Token identifier;HOTP key (hex); counter (decimal)
Example:
ub0000011113;7442333331133331121031232334123123322323;0

Comma separated textfile

The file format is:
Number id, Token identifier, countervalue, HOTP key (hex), Config Password (not used), Timestamp
Example:
125,ub9020000125,0,7e4baa15979ee53e2695bed18a10259f4bd6ebd5,000000000000,2010- 04-19T01:48:51,
126,ub9020000126,0,56f5ef6185bbdcebf89e166182692c041e8d2f5e,000000000000,2010- 04-19T01:48:51,


Any line starting with the character # is ignored.

To import tokens, the "Upload keyfile to database" button can be used
The first token in the file will be displayed

    

Accepting the import will insert the token information into the database.

User enrollment

When a user uses a HOTP one-time password with a token identifier at the beginning of the OTP, the OTPServer will do the following:

1. Check if the user has an HOTP key in the attribute configured in the user database.
2. If not, check if the token identifier is available in the auto enrollment key storage database
3. Copy the HOTP key and counter to the user object
4. Flag the HOTP key in the auto enrollment key storage database as "in use" by the user

This can be tested with the TestTool by using the "Verify OATH HOTP" command
Log example for a user auto enrollment:
2010-04-05 23:38:00,608: INFO: OTPConnection [localhost] –>"VERIFY_OATH_OTP:" Request
2010-04-05 23:38:00,608: DEBUG: OTPConnection [localhost] Database for "127.0.0.1" is "HOTP OpenDS"
2010-04-05 23:38:00,609: INFO: DBHandler [setupDBConnections] Establishing LDAP Connection to "HOTP OpenDS"
2010-04-05 23:38:00,629: INFO: DBHandler [getDNSingle] Executing Searchfilter: (&(cn=jdoe)(objectclass=inetOrgPerson))
2010-04-05 23:38:00,630: INFO: DBHandler [getDNSingle] Found user: "cn=jdoe,ou=People,o=Nordicedge"
2010-04-05 23:38:00,632: INFO: DBHandler [getMobileKey] ERROR Unable to get the OATH Key value for user: "cn=jdoe,ou=People,o=Nordicedge" Attribute/Query: "carLicense"
2010-04-05 23:38:00,632: INFO: DBHandler [setupDBConnections] Establishing LDAP Connection to "Auto enrollment database (LDAP)"
2010-04-05 23:38:00,656: INFO: DBHandler [saveOATHKey] OATH Key has been updated for user: "cn=jdoe,ou=People,o=Nordicedge"
2010-04-05 23:38:00,656: WARN: MobileHandler [doAutoEnrollment] User: "jdoe" has autoenrolled with token: "ub0000067607"
2010-04-05 23:38:00,657: INFO: MobileHandler [verifyOATH] Success for user: "cn=jdoe,ou=People,o=Nordicedge"

Using AES auto enrollment

In the Yubico configuration dialog (located below the Misc category), select validation mode "Validate AES key at the OTPServer", and the "Enable Automatic Enrollment (AES Keys)"

Using SQL database

If using a SQL database for key storage, the OTPServer can create the database and the table by selecting the "Check SQL Database" button.

    
           

Using LDAP database

If using an LDAP database, select an object (can be any type of objectclass) and the attribute that will contain the token information. The attribute must be a multivalue string attribute.

    

Importing tokens to the database

The import format currently supported is comma separated textfile.
The file format is:

Numeric serial number, Modhex public id (12 digits), Private id (12 hex digits), AES key (32 hex digits), Configuration password (12 hex digits), Time of configuration

The fields are:
•    Numeric serial number
•    Modhex public id (12 digits = 6 bytes)
•    Private id (12 hex digits = 6 bytes)
•    AES key (32 hex digits = 16 bytes)
•    Configuration password (12 hex digits = 6 bytes). All zeroes if not set.
•    Time of configuration timestamp

Example:
000888,djcctrccccij,f560c6f21a96,af620ec093747719584e917feee2f1db,000000000000,2010-04-19T01:47:45,
000889,djcctrccccik,c3282e1fe189,bc2737a312852ac69e071236280d436c,000000000000,2010-04-19T01:47:46,

Any line starting with the character # is ignored.

To import tokens, the "Upload keyfile to database" button can be used
The first token in the file will be displayed

    

Accepting the import will insert the token information into the database.

User enrollment

When a user uses an YubiKey with AES one-time password with a token identifier at the beginning of the OTP, the OTPServer will do the following:

1. Check if the user has an AES key in the attribute configured in the user database
2. If not, check if the token identifier is available in the auto enrollment key storage database
3. Copy the AES key to the user object
4. Flag the AES key in the auto enrollment key storage database as "in use" by the user

This can be tested with the TestTool by using the "Request OTP with Username and Password" and the "Verify OTP" commands

Log example for a user auto enrollment:
2010-04-05 23:59:33,184: INFO: OTPConnection [localhost] –>"Verify OTP" Request
2010-04-05 23:59:33,185: DEBUG: OTPConnection [localhost] Checking OTP MagicNr:C97cPj for user:jdoe
2010-04-05 23:59:33,185: DEBUG: OTPBridge [validateChallenge] Will verify by external API: ext.Yubico
2010-04-05 23:59:33,187: INFO: DBHandler [setupDBConnections] Establishing JDBC Connection to "Auto enrollment database (SQL)"
2010-04-05 23:59:33,198: DEBUG: DBHandler [getStringValueOfDNNew] SQL Query: SELECT keyvalue FROM TOKENDB.Tokens WHERE tokenid='ecececejejej'
2010-04-05 23:59:33,198: DEBUG: DBHandler [getStringValueOfDNNew] SQL Query: SELECT userid FROM TOKENDB.Tokens WHERE tokenid='ecececejejej'
2010-04-05 23:59:33,199: DEBUG: DBHandler [getStringValueOfDNNew] SQL Query: SELECT counter FROM TOKENDB.Tokens WHERE tokenid='ecececejejej'
2010-04-05 23:59:33,199: DEBUG: DBHandler [setDBConfig] SQL Query: UPDATE TOKENDB.Tokens SET userid='jdoe' WHERE tokenid='ecececejejej'
2010-04-05 23:59:33,200: INFO: DBHandler [setDBConfig] JDBC Rows affected: 1
2010-04-05 23:59:33,200: DEBUG: DBHandler [setDBConfig] SQL Query: UPDATE TOKENDB.Tokens SET assigneddate='2010-04-05 23:59:33' WHERE tokenid='ecececejejej'
2010-04-05 23:59:33,200: INFO: DBHandler [setDBConfig] JDBC Rows affected: 1
2010-04-05 23:59:33,203: WARN: ext.Yubico User: "jdoe" has autoenrolled with Yubikey: "ecececejejej"
2010-04-05 23:59:33,203: INFO: ext.Yubico Success for user: "cn=jdoe,ou=People,o=Nordicedge"
2010-04-05 23:59:33,203: INFO: OTPConnection [localhost] OTP is Valid