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.

About YubiKeys

For more details about using YubiKeys in your ACK manufacturing process, see Provision Your Module with a YubiKey.

Tutorial prerequisites

Before you can create a self-serve YubiKey, you must complete the following prerequisites:

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. Find and 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 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 ack-support@amazon.com with the following details:

  • Your Device Code Name. If you don't remember this, contact ack-support@amazon.com.
  • Your deviceType ID. 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.

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
  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 2: Program your YubiKey

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 are 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 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:

  1. Use the YubiKey to provision an ACK module on a device.
  2. Register the provisioned device with Alexa.

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

  1. 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.
  2. To provision the module, you must specify the serial port that corresponds to the module. Use the Module Utility listports command 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

  1. Connect the YubiKey to your computer through your computer's USB port.
  2. Open a new terminal window or start a new terminal session.
  3. 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.
  4. Run the $ opensc-tool --list-readers command 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 1.
  1. Open a terminal window, or start a new terminal session.
  2. 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

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

  2. Register the device with the Alexa app and your barcode by following the instructions in Step 5: Register Your ACK Module.

    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 ack-support@amazon.com 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.
    • The deviceType ID 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.

Troubleshoot issues

The following tables contain common error messages and possible resolutions.

Error messages

Error Resolution

Failure in provisioning device

Try to provision the device again. If it still fails, contact ack-support@amazon.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 ack-support@amazon.com 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 ack-support@amazon.com with the specific error message and error details.

Error codes

Error Code Error Resolution

15

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.

17

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.

21

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 ack-support@amazon.com.

21

Your virtual product isn't enabled to program YubiKeys.

You don't have the correct permissions to program YubiKey for this virtual product. Contact ack-support@amazon.com to enable YubiKey programming for your virtual product.

98

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.

98

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 ack-support@amazon.com 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 ack-support@amazon.com for assistance.
How do I contact ACK support for questions?
You can contact ACK support at ack-support@amazon.com.