Set Up Client-Server Machines for Production

To add Alexa Connect Kit (ACK) specific steps to your manufacturing line, prepare your server and client machines to provision modules for production.

Client-server configuration

Amazon recommends that you set up a private network with one server and one or more distributed client machines at your factory. You should properly safeguard the server from unauthorized physical access and have proper user access control in place.

You secure a Certificate Authority certificate (CA) certificate and hardware security module (HSM) key on the server. In the provisioning flow, the client reads the module over a serial connection and sends an HTTPS request containing the extracted Certificate Signing Request (CSR). The server then signs the certificate and returns it to the client. In addition, the server maintains a secure data store of information about devices provisioned for production.

Prerequisites

Before you start, make sure that you have the following items:

• A Windows 10 server machine with a USB port to connect the HSM key and a secure data store to store information about provisioned devices.
• Windows 10 client machines with a USB port to connect to the serial port on the module.
• Set the system time to the current real time on both the server and the client machines.
• Access to the ACK SDK tools package provided by your ACK support engineer.
  For more details, see Contact Amazon about your project.
• Client-Server network with multiple clients and a secured server connected to the same local Wi-Fi or wired network. Configure the network firewall to reject HTTPS requests from outside the network, and don't expose your server machine to the public network.
• (Recommended) Within your local network, to increase security, set up a virtual local area network (VLAN) that contains only your server and client machines. A VLAN prevents devices in the same network from making HTTPS requests to your server.

Steps to configure server and client machines

Complete the following steps to download and install required tooling packages to manufacture your product for production.

1. Install ACK SDK tools.
2. Install Python cryptographic token interface.
3. Install HSM software.
4. Set up the server.
5. Set up client machines.
6. Start the server.

Step 1: Install ACK SDK tools

In this step, you install the ACK SDK tools package on your server and client machines. Before you start, make sure that you have Python 3.10 and the Python package manager.

Verify Python version  

pip --version

To install the ACK SDK tools

1. To download the ACK SDK tools package, navigate to the tools folder in the AWS S3 bucket, and then download the ACK_SDK_Tools-matter zip file.
2. To extract the files into a destination folder, enter the following command in a Windows terminal.

unzip ACK_SDK_Tools-matter.zip -d <destination folder>

3. To install the acksdktools package, navigate to the destination folder, and then, enter the following command.

pip install .

4. To verify the ACK SDK tools installed correctly, enter the following command.

pip list

5. Verify that you see the acksdktools package in the list.

Step 2: Install Python cryptographic token interface

If you have a YubiHSM or SmartCare-HSM hardware security module, install python-pkcs11 library from source on your server.

To install the python cryptographic token interface package

1. Open Microsoft C++ Build Tools, and then, to download the Visual Studio Installer, click Download Build Tools.
2. Open the Visual Studio Installer, and then, under the Workloads tab, check the Desktop development with C++ installation option. Don't select any additional options.
3. Click Install.
4. Clone the python-pkcs11 source code to any location.
5. In a terminal window, navigate to the new python-pkcs11 folder, and then enter the following commands at the command prompt.

python setup.py build
python setup.py install

6. To verify a successful installation, enter the following command.

pip install python-pkcs11

7. Verify that you see the following result.
   Requirement already satisfied: python-pkcs11 in ...

8. In a convenient place, such as Notepad on Windows, paste the directory path where you installed the package.
   The default directory is C:\Program Files\OpenSC Project\OpenSC\pkcs11\onepin-opensc-pkcs11.dll.

Step 3: Install HSM software

ACK-specific steps in manufacturing use HSM to create cryptographic keys that secure your product. ACK supports two HSM types: SmartCard-HSM or YubiHSM. In this step, install the software required for your HSM type on your server.

To install HSM software

• SmartCard-HSM
• YubiHSM 2 FIPS

C:\\Program Files\\OpenSC Project\\OpenSC\\tools

Step 4: Set up the server

In this step, you generate the CA certificate for HTTPS requests to the server and create the data folder to store issued device serial numbers (DSNs), control logs, and audit logs.

To set up the server machine

1. Set the time on the computer hosting the server to the current real time.
   Tip: Device certificates require time accuracy to the minute.
2. To find the local IP address of the server, enter the following command in a Windows PowerShell terminal window.

(Test-Connection -ComputerName $env:ComputerName -Count 1).IPV4Address.IPAddressToString

3. Generate a CA certificate.
   You can find the generated certificate in <hostname>.pem.
   Tip: Use the same server IP address that clients use to make requests to the server.

servertools generate-ca -ip <ip address of server> --expiration <Number of days for cert to be valid>

4. Generate authentication tokens for the client machines to connect to the server.
   Tip: Create one token file for each client machine connected to the server.

servertools generate-token -d <device_type> --device-type-data-path <path/to/data/folder>

5. Create a folder to store the control logs, audit logs (for Matter), and the database of issued DSNs.
   Create one folder per device type. Example for device type ID ABCD1234: C:\Users\user1\Documents\ACKserver\ABCD1234
   Make sure that the HTTPS user has read and write access to the folder.
   Maintain the data folder
   
   Make sure that you maintain the data folder and back it up frequently.
   
   If you change the folder location during production, for example, due to a hard drive replacement, you must move the old data folder to the new location. Because the data folder holds records of issued DSNs, deleting old data can lead to duplicate DSNs or audit log upload failures.
6. To create SFTP upload and feedback endpoints for control logs, follow the instructions on the FFS > Control Logs console.
   Tip: To safeguard the generated private key, save the key in a folder on the server with access limited to the user who manages the control logs.
7. In a convenient place, such as Notepad on Windows, paste the upload and feedback endpoints and the control log passphrase. You use these to upload the control files to Amazon.

Step 5: Set up client machines

In this step, you copy the CA, token, and configuration files required for provisioning to the client machine.

To set up client machines

1. Set the time on the client machine to the current real time.
   Important: Set the time to the same time as the server. Otherwise, the validity period of the device certificate might cause issues during provisioning.
2. Connect the client machine to the module by using screen or PuTTY.
   For details, see Connect your host machine to the development kit.
3. Download the Provisioning configuration file that you generated for the prototype, ProvisioningInfo_<device_type>.conf.
4. Securely copy <hostname>.pem from the server to the client machine.
   You can find the generated certificate on the server.
5. Securely copy a token file from the server to the client machine. Don't add the same token file to more than one client.
   You can find the token files in path/to/data/folder on the server.
6. Repeat steps 1–5 for each client machine.

Step 6: Start the server

When you start the server, you start the ACK server and the YubiHSM server. Before you start the server in production mode, you can test the server in dry-run mode without an HSM to verify the network connection.

To start the ACK server, make sure you have the two passcodes from Amazon.

• Dry-run Mode
• Production Mode

ackserver --dry-run --host 0.0.0.0 -p 5000 -d <device_type> --device-type-data-path <path/to/data/folder> --ca-path <path to certificate> --ca-key-path <path to certificate key> -l DEBUG --hsm <smartcard|yubi>

python -c "import os, requests;os.environ['REQUESTS_CA_BUNDLE']=input('Path to hostname-cert.pem file: ').strip();print(requests.get(f'https://{input(\"Host name: \").strip()}:{input(\"Port: \").strip()}/generate_dsn', headers={'Authorization': f'Bearer {open(input(\"Path to token txt file: \").strip()).read().strip()}'}).text)"

yubihsm-connector -d

ackserver --dry-run --host 0.0.0.0 -p 5000 -d <device_type> --device-type-data-path <path/to/data/folder> --ca-path <path to certificate> --ca-key-path <path to certificate key> -l DEBUG --hsm <smartcard|yubi> <--opensc_module|--yubihsm-url>

Stop the ACK server

You might stop the ACK server for a variety of reasons, including uploading control logs, stopping the production run, and more.

To stop ACK server, on the terminal window where the ackserver process is running, enter Ctrl+C on Ubuntu or Ctrl+Break on Windows.

Related topics

• Building Matter
• Manufacture your ACK-based Matter Device
• Provision ACK Modules for Production
• Upload Production Logs
• Set Up Your Development Environment for Prototypes

Last updated: frontmatter-missing