Your Setup Console

Provisionee Manufacturing

This guide describes the provisioning of Device Hardware Authentication (DHA) material during the manufacturing of devices. You must use DHA for Frustration-Free Setup (FSS) to create secure communications between FSS-enabled devices and the Amazon Simple Setup cloud services. FSS cloud services securely associate devices to owners, enable broader Alexa services, and enable Alexa skills developed by non-Amazon developers. FSS uses DHA material to authenticate with the Amazon cloud and services. Amazon requires that you use DHA for all products that incorporate FFS.

Overview and Definitions

DHA is an extension of the X.509 authentication standard.

DHA Process

  1. Where available, each X.509 client generates a public key and private key and stores the private key is in protected storage.

  2. The X.509 client includes the public key in a Certificate Signing Request (CSR) and sends this CSR to Amazon.

  3. The certificate authority (CA) signs the CSR resulting in an X.509 certificate. The X.509 client then stores the certificate.

  4. The X.509 client presents its X.509 certificate during authentication.

  5. The X.509 client uses its private key to generate a signature as part of its response during the “challenge-response authentication” process.

  6. The X.509 server considers the X.509 client authenticated when it can verify the signature using the public key included within the X.509 certificate.

  7. The X.509 server considers the X.509 client authorized if:

  • The authenticating party trusts the CA that signs the X.509.
  • Information about the X.509 certificate provides the necessary authorization information.

This document uses the following terms to describe security architecture. Many of these terms are similar to the X.509 authentication scheme:

DHA key: Your device stores a DHA key. This key contains parts: an X.509-based DHA certificate, and a Private key. The X.509-based DHA certificate contains a public key that identifies the certificate, a signature signed by an external Certificate Authority (CA), and additional metadata such as the Product ID. Your device should store the X.509-based DHA certificate in non-volatile storage. The private key and the public key pair together as one component of the DHA certificate. Your device should store the private key in protected storage if protected storage is available on your device. Your device should persist both the X.509-based DHA certificate and the private key across reboots, factory resets, and firmware updates.

Device Attestation Key (DAK): A Device Attestation Key acts as the Certificate Authority for each specific device. Each of your products should have 1 or more DAKs to indicate test or production devices. Amazon provides DAKs for you.

Device Type and Advertised Product ID: Device Type and Advertised Product ID (APID) combine to identify a product line uniquely. Amazon issues a unique Device Type / Advertised Product ID pair for each of your products you onboard with Simple Setup.
Amazon then uniquely associates a DAK to a specific Device Type / Advertised Product ID pair. You must use each Device Type / Advertised Product ID pair only with a single product.
When you onboard a new product with Amazon Simple Setup, Amazon issues a new Device Type / Advertised Product ID pair and provides a new DAK.


High-Level Flowchart

The following steps show the manufacturing flow:

  1. The manufacturing process generates a private key on the device. The process combines the private key, the public key, and other device parameters into a Certificate Signing Request (CSR).
  2. The manufacturing process extracts the newly generated CSR from the device, and an internal Amazon generated CA signs the CSR into a DHA certificate.
  3. The manufacturing process stores the DHA private key and full certificate chain on the device in persistent storage.
  4. The manufacturing process generates a 2D barcode specific to each device.

Amazon provides the DAK via a YubiKey. The use of a YubiKey ensures that the DAK is not exposed to the manufacturing line station itself and remains secure. The DHA software on the device is part of the Amazon Simple Setup SDK.

Creating a DHA Certificate in the Proper Format

The following steps describe the process for creating the certificate chain in the proper format. The example below is a sample only.


DHA PIN

Frustration-Free Setup supports PIN-based set up using the product barcode, as an alternative to Zero-Touch Setup for customers who did not purchase their device on Amazon.com. To support this, manufacturers must include a PIN on the device and expose it within the product barcode. When the customer scans the product barcode, the Alexa app sends the barcode data (including the PIN) to the Amazon cloud. The Amazon cloud uses this barcode data (including the PIN) to assert ownership of the device. When the device connects to the WiFi Simple Setup cloud, the services verify the device's PIN against the PIN from the product barcode. The PIN must be a random secret alphanumeric ([a-zA-Z0-9]) 9-character string generated at the time of device manufacturing. To ensure randomness, it must not use any other barcode information (e.g., Public key) as a seed. The manufacturing process should generate the PIN and store the PIN on the device. Once the manufacturing process has stored the PIN, the PIN should only be accessible to the WiFi Simple Setup SDK.

The DHA certificate must conform to the RFC5280 along with the following additional requirements.

a. Distinguish Name (DN) format

To help both machine and human to parse the DHA certificate, Amazon proposes extra fields inside the DN field of the certificate to represent a device:

OID Type Description
.1.3.6.1.4.1.4843.1.1 PrintableString Reserved
.1.3.6.1.4.1.4843.1.2 PrintableString Reserved
.1.3.6.1.4.1.4843.1.3 PrintableString Device Type ID generated by Amazon and provided to you during onboarding.

b. The standard signature identifier for the Elliptic Curve Digital Signature Algorithm (EC):

ecdsa-with-SHA256

c. The Elliptic Curve used:

prime256v1

Getting a DAK from Amazon

Amazon creates a DAK for each Device Type during onboarding. Amazon provides you with a YubiKey that includes the DAK.
Amazon also provides software that accesses the DAK on the YubiKey to sign your CSR. This software is called the "CSR Signing Application" and runs on your manufacturing line workstation. You must first generate a DHA private key and CSR, and then use the CSR Signing Application to sign the CSR.

Manufacturing Line Workstation Requirements

There are specific requirements for the manufacturing line workstation. These requirements ensure that the manufacturing line workstation can run the CSR Signing Application and sign your CSRs. These requirements include:

  • A Linux OS
  • A valid Java 8 Runtime Environment (JRE)
    • OpenJDK 1.8 or Java SE 8
  • Bouncy Castle Crypto APIs for Java
  • The Amazon CSR Signing Application

Installing the Java 8 Runtime*

To install OpenJDK 8 on Debian, Ubuntu, or other similar Linux distributions, type the following on the Linux command line:

$ sudo apt-get install openjdk-8-jre

To install OpenJDK 8 on Fedora, Oracle Linux, Red Hat Enterprise Linux, or other similar Linux distributions, type the following on the Linux command line:

su -c "yum install java-1.8.0-openjdk"

To install Java SE 8 on Linux, download the appropriate installation package for your Linux OS from Java SE Runtime Environment 8 Downloads and follow the instructions on the Oracle website.

Installing the Bouncy Castle Crypto APIs for Java

To install the Bouncy Castle Crypto APIs for Java, download the following JAR files:

  1. Create a directory named 'DHA' and a directory within that named 'jars' by running the following from the Linux command line. $ mkdir -p DHA/jars
  2. Place the two (2) downloaded JAR files into the DHA/jars directory.

Installing the Amazon CSR Signing Application

Amazon provides the CSR Signing Application as a ZIP file containing a readme.txt file and the DHAv2CSRSigner-1.2.jar file. Unzip the ZIP and place the DHAv2CSRSigner-1.2.jar file into the same DHA/jars directory as above.

Generating DHA Keys and Certificates for each Manufactured Device

  1. Create a device.conf and dak.ext file in the same folder DHA directory from above. Your directory structure should look like the following:
$ ls DHA
dak.ext device.conf jars/
$ ls DHA/jars/
bcpkix-jdk15on-164.jar bcprov-jdk15on-164.jar DHAv2CSRSigner-1.2.jar

The examples below show the format of these two (2) files. The values shown are examples only, and the values for your application are different. Specifically, Amazon provides a unique value for DeviceTypeId.

device.conf

oid_section = OIDs

[ req ]
default_bits = 256
prompt = no
encrypt_key = no
default_md = sha256
distinguished_name = dn
req_extensions = req_ext

[ OIDs ]
DeviceTypeId=1.3.6.1.4.1.4843.1.3

[ dn ]
DeviceTypeId=A1234567890DT

[ req_ext ]

dak.ext

[ v3_req ]
authorityKeyIdentifier=keyid
keyUsage=digitalSignature,keyEncipherment
  1. Generate a DHA private key and CSR
$ openssl req -new -nodes -config device.conf -newkey ec:<(openssl ecparam -name prime256v1) -keyout device.key -out device.csr
  1. Use the Amazon provided CSR Signing Application to sign the CSR.

Insert the YubiKey in a USB slot on your Linux system and then run the following command:

cat device.csr | \
CLASSPATH="./jars/bcprov-jdk15on-159.jar:\
./jars/bcpkix-jdk15on-159.jar:./jars/DHAv2CSRSigner-1.2.jar" java\
com.amazon.corebsp.dhav2.csr_signer.App -pin=<PIN> > device-cert-chain.pem

Where <PIN> is the PIN provided by Amazon for your YubiKey.

  1. This step is optional. You can verify the device pem against the Amazon Root CA.

  2. Include the device-cert-chain.pem on the device (along with the private key). The FFS SDK uses this cert-chain when making calls to Amazon Cloud and is validated using Mutual TLS.

  3. Compress the Public Key so that you can include it in the 2D barcode

$ openssl x509 -pubkey -noout -in device.key  > device.pub
$ openssl ec -in device.pub -pubin -conv_form compressed -out device-compressed.pub

DHA Material on the Device

You need to store the following two items on the device:

  1. DHA Private Key i.e., device.key
  2. DHA Full Certificate Chain i.e., device-cert-with-chain.pem

The DHA private key should be hidden/encrypted on flash as best you can by doing the following

Access the key by reading it directly from flash- do not store the key in a file.

Encrypt the DHA Private Key with a key derived from device-specific values that are not readily available (e.g., MAC + DSN + Randomized values from EFUSE).

DHA Material in the 2D Barcode

The 2D barcode needs to include the compressed public key. You can use the contents of the device-compressed.pub file with the following modifications:

  • Remove the ‘begin-public-key’ and ‘end-public-keys’ lines
  • Remove all newlines

2D Barcode and Device Hardware Authentication

Fulfilling the Barcode and Device Hardware Authentication prerequisites in your specific manufacturing process.

Please review the Provisionee 2D Barcode Specification.

General Guidance for Barcode Generation

The following list shows the common settings that products should use to guide the printing of the Amazon Simple Setup barcodes. You should test the printed barcode to validate that they are scannable.

  "Product" barcode "Package" barcode
Dimensions 10 mm x 10 mm (minimum) 15 mm x 15 mm (minimum), Typically 20 mm x 20 mm white label
Cell Size 36 x 36 36 x 36
Grade Level Grade B or Higher Grade B or Higher
Power Level Depends on print method Depends on print method
Print Method Laser Etching on Device, Print on Label on Device, Print on Quick Start Guide Print on Package

Frustration-Free Setup Icon Image Guidance Next to Barcode

A Frustration-Free Setup icon key image helps customers find the right barcode associated with Frustration-Free Setup. Please add the following image to the left of the barcode with the specifications based on your implementation.

Version Date Author Description
1.0 Sept 25, 2019. Amazon. General Availability
1.1 Apr 20, 2020. Amazon. Guidance around YubiKey usage and instructions on CSR Signer app.