Table of Contents Table of contents: Radiator® AAA Server <AuthBy WIMAX> 3.86 - <AuthBy WIMAX> <AuthBy YUBIKEYVALIDATIONSERVER> 3.88 - <AuthBy YUBIKEYVALIDATIONSERVER>

3.87. <AuthBy SQLYUBIKEY>

Yubikeys are small USB tokens for one-time password authentication. They are produced by Yubico and are relatively inexpensive. Much of the surrounding technology and sample code is open source. They can support one factor or 2 factor authentication, but not challenge-response. For more information, see Yubico website Opens in new window
A Yubikey produces a unique one-time password each time the little button on it is pressed. The interesting thing is that the Yubikey acts like a USB keyboard, so the onetime- password is automatically typed into wherever the keyboard cursor is placed. This means that the user does not have to type in their token code by hand, as with many other tokens. It also means that it can work easily with many existing wired and wireless authentication methods, supplicants, web pages, Radius clients and other applications. The keys work on Windows, Linux, macOS and other platforms.
Each Yubikey has a secret AES key programmed into it in the factory. This secret key can be used to authenticate the key against any of the public services provided by Yubico. In order to use a Yubikey in a 3rd party authentication service such as Radiator, it is necessary to reprogram each token with a new (known) AES secret key, and to record that same key in the Radiator database. See goodies/yubikey.txt for more information about that process.
Yubico provide a number of sample open source programs for managing and authenticating Yubikeys. A typical one is the Yubico Java Server, a YubiKey OTP validation server in Java. This is a Tomcat application which provides an HTTP based web service API for authenticating Yubikeys. It looks up the secret key in a MySQL database and checks whether a Yubikey one-time password is correct.
Radiator now ships with the <AuthBy SQLYUBIKEY> module and a sample configuration file in goodies/yubikey.cfg. It supports RADIUS PAP, EAP-One-Time-Password and EAP-Generic-Token-Card protocols.
RAdmin from Radiator Software also supports Yubikeys, and provides an easy-to-use web-based tool for administering users and Yubikey tokens, including importing, allocating and deallocating tokens to users. 2 factor authentication is also supported in RAdmin. For more information, see RAdmin website Opens in new window.
The design of the <AuthBy SQLYUBIKEY> module allows it to be configured to work with a wide range of database schemas, but by default it works with the same schema that comes with the Yubico Java Server mentioned above. This means that you can provide web services API based authentication and Radius authentication for Yubikeys from the one token database.
<AuthBy SQLYUBIKEY> can be optionally configured to support or require 2 factor authentication if the token database also contains a static password for each user. In this case, the user types their static password first, followed by a colon (‘:’), followed by the output from the one-time password token. The user is only authenticated if both the static password and the one-time password are correct. <AuthBy SQLYUBIKEY> supports replay attack detection: any attempt to use the same one-time password twice in a row will fail. For example, if the user's static password was ‘fred’, the resulting password would be something like:
fred:ccccccccefeiujbfhkhfurbitjcvuvnedivhbeighuvf
Radiator does not come with any tools for managing the Yubikey token database. Use RAdmin (for more information, see RAdmin Opens in new window) or use one of the tools provided by Yubico. It is relatively easy to integrate this with almost any existing user database.
The example configuration file goodies/yubikey.cfg in the Radiator distribution shows the main configuration options. It will work by default with the database schema provided with Yubico Java Server, but can be customised for many other SQL database schemas. It assumes the token ID and secret are in the database in Hex (no spaces) format, and that there is a one-to-one mapping between Yubikeys and users. Other formats and multiple key or multiple user mappings can be supported with custom SQL query parameters.
Tip
Radiator can also authenticate Yubikeys against the Yubikey Validation Server. For more information, see Section 3.88. <AuthBy YUBIKEYVALIDATIONSERVER>. Another possibility is to use the Yubikey PAM module and AuthBy PAM.
<AuthBy SQLYUBIKEY> supports EAP-OTP and EAP_GTC for use with various EAP compatible devices.
<AuthBy SQLYUBIKEY> requires the Auth::Yubikey_Decrypter module version 0.05 or later from CPAN website Opens in new window and the Crypt::Rijndael module, also available from CPAN.
<AuthBy SQLYUBIKEY> supports the same parameters as <AuthBy xxxxxx>. For more information, see Section 3.32. <AuthBy xxxxxx>. It supports also all the common SQL configuration parameters. For more information about the SQL configuration parameters, see Section 3.8. SQL configuration.

3.87.1. AuthSelect

Specifies an SQL query that will be used to fetch Yubikey data from the database. Special characters are permitted, and %0 is replaced with the quoted user name, the Token ID in Base64 format in %1, the Token ID in hex format in %2 and the Token ID in modhex format in %3. The result field 0 (secret) is the base64 encoded AES secret for the key. It must be present for the authentication to succeed. All others fields are optional. If field 1 (active) is defined is must be 1 else the authentication is rejected. Field 2 (userId) is not currently used. Field 3 (counter) is the key use counter. If defined, it will be used to detect replay attacks, and must be updated by UpdateQuery. Field 4 (session_use) is the session_use counter. Field 5 is currently ignored. The static password field (field 6) contains the users correct static password in any of the formats supported by Radiator including plaintext, {SHA}, {crypt}, {MD5}, {rcrypt}, {mysql}, {mssql}, {nthash}, {dechpwd}, {NS-MTA-MD5}, {clear} etc. TranslatePasswordHook is also supported.
The default works with the sample Yubikey database created by db_schema.sql from the YubiKey Validation Server. The default is:
AuthSelect select secret, active, userId, counter, low,
high,NULL from yubikeys where userId=%0
which assumes that there is a one-to-one mapping between Yubikeys and users. It also assumes the Token ID and AES secret are in Hex (no spaces). You could support multiple tokens per user or multiple user per token with a custom AuthSelect like:
AuthSelect select secret, active, userId, counter, low,
high,NULL from yubikeys where tokenId=%1 and userId=%0

3.87.2. UpdateQuery

Specifies SQL query that will be used to store Yubikey token data back to the database after authentication. Special characters are permitted, and %0 is replaced with the new session counter, %1 with the new session_use counter, %2 with 0 (this column not currently used), %3 with the quoted user name, %4 with the quoted token ID in Base64, %5 with the current time (seconds in the unix epoch), %6 with the token ID in Hex and %7 with the token ID in modhex. The default works with the sample Yubikey database created by db_schema.sql from the YubiKey Validation Server. The default is:
UpdateQuery update yubikeys set accessed=current_timestamp(),
counter=%0, low=%1, high=%2 where userId=%3
which assumes that there is a one-to-one mapping between Yubikeys and users. You could support multiple tokens per user or multiple user per token with a custom Update- Query like:
UpdateQuery update yubikeys set accessed=current_timestamp(),
counter=%0, low=%1, high=%2 where tokenId=%4 and userId=%3

3.87.3. Require2Factor

Forces all authentications to require 2 factor authentication. In 2 factor authentication, the user is required to enter (as their password) both their static password (also called their PIN) followed by the one-time-password from the Yubikey.

3.87.4. CheckSecretId

If CheckSecretId is set, then check that the secretId fetched from the database matches the secretId encoded in the submitted Yubikey OTP. This increases the security of the Yubikey OTP and is recommended best practice.
Table of Contents Table of contents: Radiator® AAA Server <AuthBy WIMAX> 3.86 - <AuthBy WIMAX> <AuthBy YUBIKEYVALIDATIONSERVER> 3.88 - <AuthBy YUBIKEYVALIDATIONSERVER>