Provision AVS devices for FFS

For user security, you must have signed certificates for your Frustration Free Setup (FFS) enabled devices. Use Device Attestation Keys (DAK) to sign your device certificates. The following instructions describe how to use a software-based DAK to sign the certificates for an FFS device during the manufacturing process for development or production.

Process overview

The following steps give a high-level overview of the provisioning process for an FFS-enabled device:

To provision an FFS device with a SoftDAK key

  1. Register your product in the Alexa Voice Service (AVS) developer console and onboard your product to FFS.
  2. From the AVS developer console, create a DAK key for your device type.
  3. Generate Device Hardware Authentication (DHA) certificates for each individual device, and provision the devices during manufacturing.

Step 1: Register and onboard your product for FFS

To register and onboard your product with FFS

  1. If you haven't already done so, register your product in the AVS developer console. For instructions, see Register a Product with AVS.
  2. On the Product Details page for your product in the AVS developer console, choose the Alexa app using Frustration Free Setup option.
FFS Setup option

After creating or updating your product to use the Alexa app using Frustration Free Setup option, you should see a new Device Setup tab.

Step 2: Create DAK for the device type

To create a DAK for a device type

  1. Go to the Device Setup tab for your product.

  2. Under Device Provisioning, follow the prompts to create and download the new DAK certificate files:

    1. From the Manage Keys section, download the dak.conf file.
    2. Open a terminal window on your computer.
    3. On the command line enter the following command sequence to generate dak_private_key.pem and dak.csr files from the dak.conf file:

      $ openssl ecparam -name prime256v1 > dak-params.pem 
      $ openssl req -new -nodes -config dak.conf -newkey ec:dak-params.pem -keyout dak_private_key.pem -out dak.csr
      
    4. In your web browser, go back to the Manage Keys section, and upload the dak.csr file that you just generated.
    5. On the Manage Keys section, download the dak-certificate.pem and device.conf files.

Step 3: Generate Device Hardware Authentication (DHA) certificates and provision the devices

To generate a DHA certificate for a device to be provisioned

  1. On the command line, enter the following command sequence:

    $ openssl ecparam -name prime256v1 > dak-params.pem
    
    $ openssl req -new -nodes -config device.conf -newkey ec:dak-params.pem -keyout private_key.pem -out device.csr
    
  2. At the manufacturing line station, open a terminal window, and sign the private key using the DAK you downloaded from Amazon and generate the DHA certificate chain file.

    Using the device.csr, device.conf, dak-certificate.pem, and dak_private_key.pem files as inputs, enter the following command on the command line:

    $ openssl x509 -req -in device.csr -extfile device.conf -extensions req_ext -CA dak-certificate.pem -CAkey dak_private_key.pem -days 1825 -out device-certificate.pem -outform PEM -CAcreateserial -sha256
    
    $ cat device-certificate-XXXXXX.pem dak-certificate.pem > certificate.pem
    
  3. As part of the device manufacturing process, perform the following two steps:
    1. Enter the following command to extract a DHA public key from the DHA certificate for authentication:

      $ openssl x509 -in device-certificate-XXXXXX.pem -pubkey -noout | openssl enc -base64 -d | openssl enc -base64 > dha-control-log-public-key.txt

    2. Generate a device identification value for a 1D barcode on the device packaging to enable the Amazon fulfillment center to pre-register the device to a user account.

  4. As part of your manufacturing process, generate and upload the device control logs to Amazon. These logs contain the device DHA public key and device identification value.

Security best practices

You are responsible for the security of the generated private keys for your devices. Amazon recommends creating the DHA key in a secure area of for your device. For example, if you are implementing Amazon Common Software (ACS), you can replace the openssl with the following commnads:

  1. Generate the DHAv2 key:

    $ ace hal dha key_gen

  2. Generate the CSR file:

    $ ace hal dha get_field 0x201 > ${device_name}.csr

  3. Sign the CSR:

    $ openssl x509 -req -in ${device_name}.csr -extfile device.conf -extensions req_ext -CA dak-certificate.pem -CAkey dak-private-key.pem -days 1825 -out device-certificate.pem -outform PEM -CAcreateserial -sha256
       
    $ cat device-certificate.pem dak-certificate.pem > /data/${device_name}.pem
    
  4. Set the signed CSR file:

    $ ace hal dha set_cert /data/${device_name}.pem

  5. Read the certificate chain, and upload the control log:

    $ ace hal dha get_field 0x202