Module Provisioning: Module Utility CLI and YubiKey

---

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

Prerequisites

1. A printed circuit board assembly (PCBA) with an integrated ACK module.

   You can only use an ACK development kit with YubiKey-based provisioning if you're testing the process.

2. Complete the Module Utility CLI Quick Start guide.
3. Windows or Ubuntu Linux 16.0.4. At this time, macOS isn't supported for YubiKey-based provisioning.
4. A YubiKey HSM. You can use one of the following:
   • YubiKey provided by Amazon – Preprogrammed by Amazon for you.
   • Self-managed YubiKey – Make sure you program them first before following this tutorial.
5. A YubiKey PIN. You can use one of the following, depending on the type of YubiKey you're using:
   • YubiKey provided by Amazon – An Amazon-provided PIN.
   • Self-managed YubiKey – A PIN you generated when you programmed your self-managed YubiKey.

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

• Linux
• Windows

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 saves a zip file to your computer's default download location. After unzipping, find the ProvisioningInfo_[devicetypeid].conf file, which has three values that shouldn't 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 Wi-fi Simple Setup ID used to register the product with Alexa via Amazon's Wi-Fi Simple Setup service. For more information about Wi-Fi Simple Setup, see Wi-Fi Simple Setup.
   • ztsKey – The Zero-Touch Setup key used to register the product with Alexa via Amazon's Wi-Fi 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're 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 might 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. Use this slot number in the next step.

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

To provision the module via YubiKey, 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 YubiKeyPin.txt file.
• --yubikeyslot <slot> – The YubiKey smart card slot number. Accepted values: integer. For Windows, specify the slot 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

Step 4: Register your device with Alexa

Now that you provisioned your device with a YubiKey, verify that you can register your device with Alexa.

To register your device with Alexa

1. Generate a barcode with the Module Utility CLI barcode command.

   java -jar <path>/ackmoduleutility.jar barcode -p <port> --upc <upc>
   

   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.

   Tip: If your device successfully registers with Alexa, your YubiKeys are working.

Troubleshoot issues

For details on troubleshooting common issues, see Troubleshooting YubiKeys.

---

---

Last updated: Nov 27, 2023