Provisionee Manufacturing Guide
- Overview and Definitions
- High-Level Flowchart
- Creating a DHA Certificate in the Proper Format
- DHA PIN
- DHA Material on the Device
- DHA Material in the 2D Barcode
- 2D Barcode and Device Hardware Authentication
This guide describes the provisioning of Device Hardware Authentication (DHA) material during the manufacturing of devices. You must use DHA for Frustration-Free Setup (FFS) to create secure communications between FFS-enabled devices and the Amazon Simple Setup cloud services. FFS cloud services securely associate devices to owners, enable broader Alexa services, and enable Alexa skills developed by non-Amazon developers. FFS 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.
Where available, each X.509 client generates a public key and private key and stores the private key is in protected storage.
The X.509 client includes the public key in a Certificate Signing Request (CSR) and sends this CSR to Amazon.
The certificate authority (CA) signs the CSR resulting in an X.509 certificate. The X.509 client then stores the certificate.
The X.509 client presents its X.509 certificate during authentication.
The X.509 client uses its private key to generate a signature as part of its response during the “challenge-response authentication” process.
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.
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.
The following steps show the manufacturing flow:
- 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).
- The manufacturing process extracts the newly generated CSR from the device, and an internal Amazon generated CA signs the CSR into a DHA certificate.
- The manufacturing process stores the DHA private key and full certificate chain on the device in persistent storage.
- 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.
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:
|.220.127.116.11.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):
c. The Elliptic Curve used:
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:
- bcpkix-jdk15on-164.jar - download from www.bouncycastle.org
- bcprov-jdk15on-164.jar - download from www.bouncycastle.org
- 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
- 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
- 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.
oid_section = OIDs [ req ] default_bits = 256 prompt = no encrypt_key = no default_md = sha256 distinguished_name = dn [ OIDs ] DeviceTypeId=18.104.22.168.4.1.4843.1.3 [ dn ] DeviceTypeId=A1234567890DT
[ v3_req ] authorityKeyIdentifier=keyid keyUsage=digitalSignature,keyEncipherment
- 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
- Use the Amazon provided CSR Signing Application to sign the CSR.
Amazon sends the PIN for each YubiKey to you. Each YubiKey has a unique serial number printed on the side.
Entering an incorrect PIN three (3) times in a row disables a YubiKey. The only way to re-enable a YubiKey is to send the YubiKey back to Amazon. Amazon is not able to remotely re-enable YubiKeys. Amazon may also send you a new Yubikey. It takes about 7 business days to issue a new Yubikey.
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
<PIN> is the PIN provided by Amazon for your YubiKey.
This step is optional. You can verify the device pem against the Amazon Root CA.
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.
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:
- DHA Private Key i.e., device.key
- 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.
|1.0||Sept 25, 2019.||Amazon.||General Availability|
|1.1||Apr 20, 2020.||Amazon.||Guidance around YubiKey usage and instructions on CSR Signer app.|