The purpose of this document is to describe the process of programming YubiKeys for use with Duo. This document will guide you through the setup and configuration process of the YubiKey Personalization Tool, programming of the YubiKeys, and output / extraction of the OTP secrets which need to be uploaded to the Duo admin portal.
Yubico Custom Programming
Please note: For order quantities of 500 YubiKeys or more, Yubico offers a custom programming service where you may have your entire order pre-programmed, and you will be provided an encrypted file that can be updated to Duo, avoiding the need to program the YubiKeys for Duo. This information and process is described in another document which may be provided upon request.
Table of Contents
- Download and configuration of the YubiKey Personalization Tool
- Configure log output and export
- Yubico OTP Programming - Configuration for Duo
- Programming multiple YubiKeys
- Yubico CSV format for secrets file
- Required fields
Download and configuration of the YubiKey Personalization Tool
First, download and install the YubiKey Personalization Tool. This guide uses version 3.1.25 of the YubiKey Personalization Tool. If you have an older version, it is advised that you upgrade to the latest version.
Operating systems supported:
Configure log output and export configuration
Next, configure the settings to allow for logging and output of the configuration, as well as the ability to export the .ycfg (YubiKey configuration) file.
- Select Settings from the top navigation bar. In the Logging Settings, check Log configuration output and select Yubico format from the dropdown.
- Under Application Settings, select Enable configuration export and import
Please see image below for settings.
Yubico OTP Programming - Configuration for Duo
Select Yubico OTP from the top navigation bar, and configure as follows:
- Select Advanced
- Select Configuration Slot
- NOTE: Factory programmed YubiKeys come pre-programmed with Yubico OTP in Slot 1, which is synchronized with YubiCloud for some services which natively support Yubico OTP via the cloud validation servers. If you are planning on using YubiCloud with other services, be sure to select Configuration Slot 2 when configuring for Duo. If this is done, however, users will need to long press (tap and hold for 3+ seconds) the YubiKey's capacitive touch sensor in order to generate the OTP for Duo.
- Set Yubico OTP Parameters as shown in the image below
- Click Generate in all three (3) sections
- Click Write Configuration
You should now receive a prompt to save the file output. Save this to a safe location!
Programming for multiple YubiKeys
If you have more than one YubiKey to program, prior to selecting Write Configuration, select Program Multiple YubiKeys as shown in the image above, and also select Automatically program YubiKeys when inserted. This will allow you to simply insert one key, remove it, then insert the next YubiKey, repeatedly until all YubiKeys are programmed.
Note: For YubiKeys with serial numbers greater than 16777215, make sure to change the Parameter Generation Scheme to Increment Identity; Randomize Secrets - this will ensure all public identities are unique.
Yubico CSV format for secrets file
You should now have a CSV that was saved during the programming process. Each YubiKey programmed will be added to the next row in the list for the entirety of the programming session. The following information will be present in the file:
- Column A: <serial_number>
- Column B: <public_identity>
- Column C: <private_identity>
- Column D: <AES_key>
- Column E: <access_code>
- Column F: <programming_timestamp>
Example output below: (please note these are examples, not real seed files)
Required fields for Duo upload
The next step is to make a copy of the original CSV file, as it will need to be modified slightly in preparation for upload to the Duo admin portal.
Once a copy has been made, delete Column B <public_identity>, Column E <access_code>, and Column F <programming_timestamp>.
The file should now read as columns A,C,D in that order (when compared to the original), which will contain: <serial_number>,<private_identity>,<AES_key>
The file should be re-saved as a CSV. Now the file is ready to be uploaded to Duo.
Example of modified file:
Once the configuration has been verified and the YubiKey is tested successfully with Duo, click the Export button on the bottom right of the YubiKey Personalization Tool. This will allow the export of the configuration to a .ycfg file, which can be re-imported for programming of additional YubiKeys in the future.