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.

Prerequisites

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 5.0.67.0 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

1. Sign-in to your Amazon developer account.
2. In a new tab, navigate to the ACK console products page.
3. Click the name of product that you want to provision a module for.
4. Click Download Provisioning File and then unzip the file to a convenient location.

5. Open the ProvisioningInfo_[devicetypeid].conf file in a text editor.

   Don't modify any of the values in this file.

6. Find the deviceType ID in the file and copy the value.

   You need this ID to apply for YubiKey provisioning in the next step.

7. 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.
• Your deviceType ID. 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.

• Linux
• Windows

To install YubiKey Manager

For YubiKey Manager download instructions, select the tab that corresponds to your operating system.

• Linux
• Windows

sudo apt-add-repository ppa:yubico/stable
sudo apt update
sudo apt install yubikey-manager

Step 1.2: Program YubiKeys with the Module Utility

To program your YubiKey

1. Plug your YubiKey into one of the USB ports on your computer.
2. Open a terminal window and run the ACK Module Utility programYubiKey command with the following values:
   • <virtual_product> – The devicetype ID 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.

   Syntax example

   java –jar ackmoduleutility.jar programYubiKey –d <virtual_product> -o <organization> -s <state/province code> -c <country> --pinoutput <pin folder>
   

   Example

   java –jar ackmoduleutility.jar programYubiKey –d A123456ZZ -o ACK -s WA -c US --pinoutput C:\Temp
   

3. In your terminal, a prompt appears asking if your want to overwrite your YubiKey. Confirm this is OK by entering y.

   A browser opens to an Amazon log-in page.

4. 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.

5. 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.

6. 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.

7. 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.

Troubleshoot issues

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.
• The deviceType ID 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.

Last updated: Nov 27, 2023