Provision Your Module with a self-serve YubiKey
This guide provides steps for commercial manufacturers to provision an ACK module using a self-serve YubiKey Hardware Security Module (HSM). Use YubiKey-based provisioning when you mass manufacture a product, where high uptime and low latency internet connections might be unavailable.
If you aren't ready to mass manufacture your product, you can use the Command Line Interface (CLI) to provision your module. For more details about CLI provisioning, see Provision Your Module.
For more details about using YubiKeys in your ACK manufacturing process, see Provision Your Module with a YubiKey.
Before you can create a self-serve YubiKey, you must complete the following prerequisites:
- Download your product configuration file
- Apply for access to YubiKey Programming
- Set up the ACK Module Utility
- Meet device requirements
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.
- Find and 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 YubiKey Programming
Before you can program your own YubiKeys, you must apply to the ACK team for approval. To submit an approval request, send an email to firstname.lastname@example.org with the following details:
- Your Device Code Name. If you don't remember this, contact email@example.com.
deviceTypeID. This is the value you copied from your product configuration file in the previous step.
- The number of YubiKeys you are 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).
Set up the ACK Module Utility
You must 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.
Meet device requirements
You must meet the following device requirements to program your YubiKeys.
- Create a Virtual Product – You must have a working virtual product in the ACK console. If you don't have one yet, follow the Prototype a product tutorial.
- Obtain an ACK development kit – You use a ACK development kit to test your YubiKeys after your program them. If you don't have one yet, see Obtain the ACK Development Kit.
- Purchase YubiKeys – You must use a YubiKey 4 NFC or YubiKey 5 NFC. Other YubiKey models aren't supported. For more details about YubiKey models, see YubiCo.
- Use a computer with a USB drive – Supported operating systems include Windows or Ubuntu Linux 16.0.4.
Step 1: Set up your provisioning environment
To get started, you must install both OpenSC and YubiKey Manager on your computer. These programs are necessary to facilitate the YubiKey provisioning 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
- Download and install YubiKey Manager for Windows.
- Set up a Windows environment PATH variable that points to your YubiKey Manager installation directory.
Step 2: Program your YubiKey
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 are 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 manufacturing, as shown in the next step.
Step 3: Test and validate your YubiKeys
Test your YubiKeys before you use them in your manufacturing process. You can test your keys by completing the following steps:
Use the YubiKey to provision an ACK module on a device
After you program your YubiKeys, wait at least five minutes before testing them. You can provision multiple YubiKeys and then test them all of them at the same time.
Determine the serial port that corresponds to the module
- First, connect the ACK hardware development board debug port to your computer. If you are using a Development Kit to test YubiKey-based provisioning, refer to the guide to connect the development board to your computer.
- To provision the module, you must specify the serial port that corresponds to the module. Use the Module Utility
listportscommand to list the serial ports and their connection status.
Identify the YubiKey slot number
When you provision the module with the Module Utility CLI, you might must specify the
--yubikeyslot parameter in your
provision command. The
--yubikeyslot corresponds to the smart card slot that corresponds to the YubiKey. To find this slot number, you can use a tool called OpenSC. For more information about this parameter, see the
provision command reference.
To identify the YubiKey slot number
- Connect the YubiKey to your computer through your computer's USB port.
- Open a new terminal window or start a new terminal session.
- Change directories to the opensc-tool directory.
- For Linux, the default location is /usr/bin/.
- For Windows, the default location is C:\Program Files\OpenSC Project\OpenSC\tools.
$ opensc-tool --list-readerscommand to list the smart cards. For an example, see the Test OpenSC documentation.
You should see something like the following output:
Nr. Card Features Name 0 Yes Yubico Yubico YubiKey OTP+FIDO+CCID 1 Yes SmartCard SmartCard SmartCardManufacturer XXXXX
Look for a row where the Card and Features columns equals
Yubico, and the Name equals YubiKey. The slot number is the integer in the Nr. column. In the example output above, the slot number for the YubiKey is
0. You use the slot number in the next step.
Use the Module Utility CLI to provision the ACK module
To provision the module with a YubiKey, you use the Module Utility CLI
provision command and these parameters:
--provisionconfigfile <path to>– The path to your product's provisioning file that you downloaded from the ACK console.
--yubikeypinfile <path-to>– The path to your Amazon-provided YubiKeyPin.txt file.
--yubikeyslot <slot>– The YubiKey smart card slot number. Accepted values: integer. For Windows, you must specify the slow number if your YubiKey slot is different that your platform's default. The default for Windows is
0. For Ubuntu 18.04 and later, the parameter must always be specified. For earlier versions, the default is
- Open a terminal window, or start a new terminal session.
Enter the following code into the terminal:
$ java -jar <path-to>ackmoduleutility.jar provision -p <port> --provisionconfigfile <path-to>/ProvisioningInfo.conf --yubikeypinfile <path-to>/YubiKeyPin.txt --yubikeyslot <slot>
When the provisioning process is successful, the following output appears:
Device Provisioning Beginning... Setting device information Connecting to YubiKey Setting certificates Device Provisioning Successful
Register your device with Alexa
Now that you provisioned your device with your YubiKey, you must verify that you can register it with Alexa.
To register your device with Alexa
Generate a barcode.
java -jar <path>/ackmoduleutility.jar barcode -p <port> --upc 12345678
A message appears and tells you the location of the barcode files.
Register the device with the Alexa app and your barcode by following the instructions in Step 5: Register Your ACK Module.Tip: If your device successfully registered with Alexa, your YubiKeys are working correctly.
If you get an error message
You can try to resolve the most common errors by reading the troubleshooting section.
If you can't resolve the 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 firstname.lastname@example.org with the details of the following:
- The name of your product or company.
- The serial number of the YubiKeys that you are having problems with.
- The version of the YubiKeys that you are 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 are 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.
The following tables contain common error messages and possible resolutions.
Failure in provisioning device
Try to provision the device again. If it still fails, contact email@example.com with the specific error message and error details.
Error 1:x:x:x or 2:x:x:x when registering device
Bluetooth connection problem. Make sure your device has Bluetooth enabled. Restart your phone if necessary.
Error 3:x:x:x when registering device
Wi-Fi connection problem. Make sure that a Wi-Fi network is available and your device can connect to it. Make sure the password you are using for the Wi-Fi network is correct.
Error 4:x:x:x when registering device
Error with the ACK development kit. Try to register a different device. If it still fails, contact firstname.lastname@example.org with the specific error message and error details.
Error 5:x:x:x or 99:x:x:x
Try to register your device again. If it still fails, contact email@example.com with the specific error message and error details.
You don't have permission to program a YubiKey for this virtual product.
Check to make sure that the username you are using has the correct permissions to edit the virtual product.
Bluetooth connection problem. Make sure your device has Bluetooth enabled. Restart your phone if necessary.Restart your phone if necessary.
Virtual product doesn't exist.
You have reached the limit for the number of YubiKeys you can register for this virtual product.
There is a default limit of 20 YubiKeys that you can create for a single virtual product. To increase this limit, contact firstname.lastname@example.org.
Your virtual product isn't enabled to program YubiKeys.
You don't have the correct permissions to program YubiKey for this virtual product. Contact email@example.com to enable YubiKey programming for your virtual product.
Wait before attempting to program a new YubiKey for this virtual product.
You can only program one YubiKey every six minutes. Wait six minutes before creating a new one.
Another YubiKey registration process is running for this virtual product.
You can only run a single YubiKey process for a virtual product. Don't try to run the program YubiKey command on multiple machines.
Frequently Asked Questions (FAQ)
- Why should I test my YubiKeys before manufacturing with them?
- A misconfigured YubiKey can't provision devices which can cause problems during the manufacturing process. By testing your YubiKeys before you start manufacturing, you can prevent this from occurring.
- Why should I keep my PIN secure? What's the risk if a YubiKey PIN is compromised?
- If a YubiKey is lost or stolen – along with the PIN – an external party could produce devices that use your certificates.
- Should I share my PUK with my manufacturing facility?
- It's a security risk if someone has your PUK because you can use the PUK to unlock a locked YubiKey. Don't distribute your PUK to anyone outside your organization, including your manufacturing facilities.
- Is there a limit to the number of YubiKeys I can program?
- By default, you can program up to 20 device attestation certificates. Reprogramming an existing YubiKey adds one certificate count towards your total.
- Can I increase the number of YubiKeys I can program?
- Contact firstname.lastname@example.org ACK for more details on how to increase this limit.
- How do I know how many certificates I have created?
- To determine how many certificates you have created, log-in to the Frustration Free Setup (FFS) console with the developer account that you creadted your ACK product with.
- What happens if I try to reprogram an existing YubiKey?
- Any devices that you provisioned with YubiKey provisioned still function. However, existing certificates are deleted and you can't create new devices with them.
- What if I use an incorrect PIN file when programming a YubiKey?
- If you enter more than three incorrect PIN attempts, your YubiKey automatically blocks itself. You can unblock your YubiKey using the stored PUK that you generated when you programmed it. You can also use the YubiKey manager to unblock a YubiKey with the following command:
ykman piv unblock-pin –p <PUK>
- My YubiKey is blocked and I lost the associated PUK, how can I unlock it?
- You can reprogram the YubiKey with a new certificate. However, this counts towards your YubiKey limit.
- What should I do if I lose a YubiKey?
- Losing a YubiKey is a security issue because they contain certificates that securely identify your product. If you lost a YubiKey, contact email@example.com for assistance.
- How do I contact ACK support for questions?
- You can contact ACK support at firstname.lastname@example.org.