Step-by-step Guide: Customizing YubiKey OATH-HOTP using YubiKey Personalization Tool
Matthew Stein
37 steps
2 minutes
1
Find, download, and install the Yubico Personalization Tool.
2
3
Use "OATH-HOTP Mode"
4
Use "Advanced"
5
Use "Configuration Slot 2"
Use Configuration Slot 2 if you are currently using or may want to use the Yubico OTP function in the future. This slot is pre-configured by Yubico so don't overwrite if there is any chance you may also want to use the key with the Yubico OTP function. The use of the second slot means the user can use a short press on the device for slot 1 and a long press to use slot 2 with our SurePassID Authentication Server (SPAS).
6
Click "Configuration Protection". This example presumes the device already has protection turned on and the code matches the serial number of the device, which is printed on the device for easy reference.
7
If the device is already protected, choose the option shown.
8
Click "Use Serial Number" if the device was previously protected using the serial number as is the case in this example. We recommend you use this method to be sure you can trap the serial number along with the secret value in the CSV file that will be generated later.
9
Unselect "OATH Token Identifier" as it is not needed for use with SurePassID SPAS.
10
Click "Generate"
You should plug in the device you want to program and check to see that it shows in the right pane of the configuration tool.
11
Click "Write Configuration" (you should have the token you are programming inserted into the PC's USB port before you write the config)
12
When you click on write configuration, a window will pop up to allow you to save the configuration to a .CSV file.
13
Close the Personalization Tool.
14
Open the file with the information exported from the tool to prepare the file for import.
15
Delete any of the lines that don't contain the token information, like this "logging" line that shows when the info was logged to the file.
Tip! Note that if you had chosen to program multiple keys and had gone through a batch, you would see more than one line with the token information relevant to the import process.
16
Select the columns that don't contain the secret (F) or the Serial Number (G or H as shown) and delete them, in this case, the first 5 columns have information we do not need or want in the file, at least not as the first two columns.
17
Insert a new line above the first data line if you want to add a header line for easy reference when you import the tokens.
18
In this example, the first column is the secret key and the second is the printed serial number of the token associated with the secret.
The header line is optional. The key is that the first two columns should contain the secret and serial number info. The rest of the columns don't matter for the import into SurePass.
19
Save the file and close Excel.
20
Optional, as a quick check to be sure you have a good import file to use, open the new file with Excel again and confirm you have a header line (optional) and the relevant secret(s) and printed serial number(s) in the first two columns and no extraneous lines.
21
Close the file once the format and content look good, saving it as needed.
22
Sign into your portal and go to the Tokens tab, then select the Import Hard Tokens link.
23
Click on "Choose file".
24
Select the new file with the tokens you want to import.
25
Click "Next".
26
If you have a header line in your file, check the checkbox to ignore it.
27
In the Column 1 and Column 2 fields, pick Secret Key Hex and Printed Serial Number respectively if your file is set up as shown in the example. You are telling our import process which column is the secret and which is the serial number.
28
29
30
31
Once mapped, click on Next.
32
This screen shows the correct setup for importing HOTP Yubikeys set up with 6 digit OTPs. If you programmed the device for 8 digit OTPs then change the OTP length to match.
33
Click on import and you should then see a summary like this:
34
Assuming all is as it should be, click on close.
35
Find the token in the list by the serial number and check the radio button as shown.
36
Put your cursor in the One Time Passcode field, then press and hold the button on the Yubikey. This should send the OTP to the checkbox and confirm the token is programmed correctly and the system recognizes it properly.
37
That should complete the import process. You can then edit the tokens and assign them to the users as you distribute them.
