Module Provisioning: Module Utility CLI and YubiKey

​

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.

​

Step 1: Download your product’s configuration file

1. Sign in to your developer account 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

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.

  Nr.	Card	Features	Name
  0	Yes Yubico	Yubico	YubiKey OTP+FIDO+CCID
  1	Yes SmartCard	SmartCard	SmartCardManufacturer XXXXX

​

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

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

  Device Provisioning Beginning...
  Setting device information
  Connecting to YubiKey
  Setting certificates
  Device Provisioning Successful

​

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

​

Troubleshoot issues