Provision Your Module with a YubiKey

This guide provides the steps for commercial manufacturers to provision an ACK module via a YubiKey Hardware Security Module (HSM). This method is used when you are ready to mass manufacture your product. For more information, contact your Amazon business representative. For general information about module provisioning, see the Module Life Cycle.

Use YubiKey-based provisioning when you mass manufacture a product, where high uptime and low latency internet connections may be unavailable.

Prerequisites

  1. A printed circuit board assembly (PCBA) with an integrated ACK module. A Development Kit may be used with YubiKey-based provisioning only when testing YubiKey-based provisioning.
  2. Complete the Module Utility CLI Quick Start guide.
  3. Windows or Ubuntu Linux 16.0.4. At this time, macOS is not supported for YubiKey-based provisioning.
  4. A YubiKey HSM created specifically for your product by Amazon. Amazon can provide multiple YubiKey HSMs per product, if needed. Each YubiKey is identified by a unique serial number that is printed on the side that doesn’t have the USB contacts.
  5. An Amazon-provided pin for the YubiKey HSM. The pin should be stored in a file with no other characters, not even a new line character. This pin is specific to a given Yubikey. Even if a set of Yubikeys belong to the same virtual product deviceType, each of the pins can be different.
  6. A virtual product in the ACK console.
  7. OpenSC v0.17.0.

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

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

OpenSC-win32_0.19.0.msi for 32-bit programs OpenSC-win64_0.19.0.msi for 64-bit programs

Step 1: Download your product's configuration file

To download your product's configuration file:

  1. Log in to your developer.amazon.com account, if you aren't already logged in.
  2. Go to the ACK console products page.
  3. Click on the product that you would like to provision the module as.
  4. In the upper-right, click Download Provisioning File. This will save a zip file to your computer's default download location. After unzipping, you will find a ProvisioningInfo_[devicetypeid].conf file, which has three values that should not be modified:

    • deviceType– A unique identifier that represents your virtual product. When you create a virtual product in the ACK console, a unique device type is created.
    • simpleSetupId – The Wifi Simple Setup ID used to register the product with Alexa via Amazon's Wifi Simple Setup service. For more information about Wifi Simple Setup, see Wifi Simple Setup.
    • ztsKey – The Zero-Touch Setup key used to register the product with Alexa via Amazon's Wifi Simple Setup service.

Step 2: 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 need to specify the serial port that corresponds to the module. Use the Module Utility listports command to list the serial ports and their connection status.

Step 3: Identify the YubiKey slot number

When you provision the module with the Module Utility CLI, you may need to 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 information about this parameter, see the provision command reference.

To identify the YubiKey slot number, follow these steps.

  1. Connect the YubiKey to your computer via your computer’s 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 will use the slot number in the next step.

Step 4: Use the Module Utility CLI to provision the ACK module

To provision the module via YubiKey, you will 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, uou 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

If errors occur, see troubleshoot issues.

Troubleshoot issues

Module Utilty – YubiKey access error (200)

If you see an error 200 in the Module Utility, confirm that the YubiKey is physically connected to your workstation, and that you have specified the correct slot number. To determine the slot number, see identify the YubiKey slot number.

Module Utility – YubiKey pin error (201)

If you attempt to provision and use an incorrect pin value, you’ll get an error 201 from the Module Utility. Confirm that you are using the correct pin value from the YubiKeyPin.txt file provided to you by Amazon. Incorrect pin values can lead to the YubiKey being locked.

YubiKey is locked

If your YubiKey is locked, reach out to your Amazon business representative. To diagnose whether a YubiKey is locked or the number of tries remaining for a YubiKey, see Determine if your YubiKey is locked.

Determine if your YubiKey is locked

Your YubiKey will lock and become unusable after three consecutive attempts to provision a module with an incorrect YubiKey pin. This section provides the steps for you to determine guide if a YubiKey is locked, and how many tries are remaining before it is locked.

Step 1: Install the yubico-piv-tool

The Yubico PIV tool is used for interacting with the Privilege and Identification Card (PIV) application on a YubiKey, which you'll need to do to determine if your YubiKey is locked.

  1. Download the yubico-piv-tool. Versions 1.7.0 and 1.6.2 are currently validated to support the ACK diagnostic workflow.

  2. For Ubuntu 16.04 users, you also need to enable the Yubico personal package archive. For instructions, see Enabling the Yubico PPA on Ubuntu.

  3. Follow the building instructions to finish installation.

Step 2: Check the YubiKey status

To determine check the number of pin tries left for the YubiKey, you'll use the yubico-piv-tool --action status command. See the yubico-piv-tool manual for more information.

Open a terminal window and run this command:

yubico-piv-tool --action status

This will output something like:

The number of YubiKey pin tries left tells you how many tries you have left. If the value is 0, then it is locked.
The number of YubiKey pin tries left tells you how many tries you have left. If the value is 0, then it is locked.

If the value for PIN tries left: <x> is 0, this means that the YubiKey is locked. If the YubiKey is locked, please contact your Amazon business representative.