Program a Self-Managed YubiKey
This guide provides steps for commercial manufacturers to program a self-managed YubiKey Hardware Security Module (HSM).
You must program your self-managed YubiKeys before you can use them to provision your Alexa Connect Kit (ACK) modules.
- For more details about how module provisioning works, see Module Provisioning.
- For details about YubiKeys, see YubiKey Overview.
Self-managed YubiKey provisioning flow
Your self-managed YubiKeys contain an Amazon signed device attestation certificate that facilitates the device provisioning process.
The following diagram outlines the basic YubiKey programming flow that you should follow to prepare self-managed YubiKeys for your manufacturing run. After you program your YubiKeys, you can provision your ACK modules on your manufacturing line.
You can only associate a single YubiKey with a single virtual product. If you're manufacturing multiple products, program a unique YubiKey for each of your ACK virtual products.
Before you can program a self-managed YubiKey, complete the following prerequisites:
- Meet device requirements
- Download your product configuration file
- Apply for access to program your YubiKeys
Meet device requirements
- YubiKeys – Only use YubiKey 4 NFC or YubiKey 5 NFC. Other YubiKey models aren't supported. For more details about YubiKey models, see YubiCo.
- Computer with a USB port – USB A port.
- Operating system – Use Windows or Ubuntu Linux 16.0.4.
Module Utility – Download and set up the ACK Module Utility to provision your YubiKeys. Before you start this tutorial, complete the Module Utility CLI Quick Start Guide.Important: Self-managed YubiKeys are only supported if you use the ACK Module Utility 22.214.171.124 or higher.
Download your product configuration file
Before you can program your YubiKeys, you must retrieve your device information from your product configuration file. You need this information to apply for YubiKey provisioning in the next step.
To download your product configuration file
- Sign-in to your Amazon developer account.
- In a new tab, navigate to the ACK console products page.
- Click the name of product that you want to provision a module for.
- Click Download Provisioning File and then unzip the file to a convenient location.
Open the ProvisioningInfo_[devicetypeid].conf file in a text editor.
Don't modify any of the values in this file.
deviceTypeID in the file and copy the value.
You need this ID to apply for YubiKey provisioning in the next step.
- Close the ProvisioningInfo_[devicetypeid].conf file.
Apply for access to program your YubiKeys
Before you can program your own YubiKeys, you must apply for approval. To submit an approval request, contact your ACK representative with the following details:
- Your Device Code Name. If you don't remember this, contact your ACK representative.
deviceTypeID. This is the value you copied from your product configuration file in the previous step.
- The number of YubiKeys you're going to program.
- The date you need your YubiKeys programmed by.
An Amazon representative will contact you to process your request. If your application is approved, your account is typically provided programming access within three business days (Pacific Standard Time).
Step 1: Program your self-managed YubiKeys
Step 1.1: Set up your environment
To get started, install both OpenSC and YubiKey Manager on your computer. These programs are necessary to facilitate the YubiKey programming process.
To install OpenSC
For OpenSC download instructions, select the tab that corresponds to your operating system.
To install YubiKey Manager
For YubiKey Manager download instructions, select the tab that corresponds to your operating system.
In a terminal, run the following commands after downloading the source code distribution.
sudo apt-add-repository ppa:yubico/stable sudo apt update sudo apt install yubikey-manager
Follow these steps:
- Download and install YubiKey Manager for Windows.
- Set up a Windows environment PATH variable that points to your YubiKey Manager installation directory.
Step 1.2: Program YubiKeys with the Module Utility
To program your YubiKey
- Plug your YubiKey into one of the USB ports on your computer.
- Open a terminal window and run the ACK Module Utility
programYubiKeycommand with the following values:
- <virtual_product> – The
devicetypeID you retrieved from download your configuration file.
- <organization> – The name of your organization.
- <state/province code> – A 2-letter state or province code that represents the location of your main office.
- <country> – A 2-letter country code in the ISO-3166 format that represents the location of your main office.
- <pin folder> – The absolute path of a folder on your computer to store the YubiKey PIN file created by this process.
java –jar ackmoduleutility.jar programYubiKey –d <virtual_product> -o <organization> -s <state/province code> -c <country> --pinoutput <pin folder>
java –jar ackmoduleutility.jar programYubiKey –d A123456ZZ -o ACK -s WA -c US --pinoutput C:\Temp
- <virtual_product> – The
In your terminal, a prompt appears asking if your want to overwrite your YubiKey. Confirm this is OK by entering
A browser opens to an Amazon log-in page.
Enter your Amazon developer account credentials to complete the log-in process.Note: Your developer account must have administrator privileges to program a YubiKey. This is typically the developer account that you used to create and set up your ACK product. For more details on account roles, see Add Users to Your Organization's Developer Account.
When you log-in, the ACK Module Utility generates a Personal Unlock Key (PUK) and a PIN file for your product.
In your terminal, find the message that shows your Personal Unlock Key (PUK). Copy this value to a secure location.Important: You use your PUK to unlock a locked YubiKey. Don't distribute your PUK to anyone outside your organization, including your manufacturing facilities.
In your terminal, find the message that shows the folder location of your PIN code. Navigate to this folder and copy the .txt file to a secure location.
Double check that the name of the text file name matches the serial number of the YubiKey you're programming. Your YubiKey can lock if you use the incorrect PIN code during programming.Important: Always keep your PIN file secure, even when sharing it with your manufacturing facilities.
Your YubiKey is now programmed. Close your terminal or program another YubiKey by repeating the instructions in this section.
Make sure you test and validate your YubiKeys before you use them in your manufacturing line. To test your YubiKeys, provision your ACK modules with your self-managed YubiKey, as shown in the next step.
Step 2: Provision ACK modules with your self-managed YubiKey
After you program your YubiKeys, test them by provisioning an ACK module and then registering the device with the Alexa app.
To provision your modules, follow the steps in Program your self-managed YubiKey. Note that you might have already completed some of the prerequisite steps in the next tutorial by completing this tutorial.
For details on troubleshooting common issues, see Troubleshooting YubiKeys.
Contact ACK support
If you can't resolve your errors, there might be an issue with your YubiKeys. If this occurs, don't use the YubiKeys in your manufacturing process. Instead, keep them in a secure place and contact your ACK representative with the details of the following:
- The name of your product or company.
- The serial number of the YubiKeys that you're having problems with.
- The version of the YubiKeys that you're having problems with. For example, YubiKey 4 or YubiKey 5.
deviceTypeID of your product that you retrieved from your configuration file.
- The approximate time you programmed the YubiKeys that you're having problems with.
- How many YubiKeys you programmed around the same time, when you first noticed the problem.
- Any error messages you received in the ACK Module Utility or the Alexa app when you programmed the YubiKeys.