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.

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.

Typical self-managed YubiKey manufacturing Flow and Use.

Prerequisites

Before you can program a self-managed YubiKey, complete the following prerequisites:

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.

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.

Download and install the opensc-0.17.0.tar.gz source code distribution. For Linux installation instructions, see compiling and installing on Unix flavors

For Windows, you must install both the 32-bit and 62-bit versions of OpenSC 0.17.0

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:

  1. Download and install YubiKey Manager for Windows.
  2. 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

  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.

    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.

  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.

  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.