Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Setting up the host

This section shows how the CM must set up the host for mass manufacturing Sidewalk devices. See Required toolkit and Pre-requisites.

Important
The steps in this section need to be performed only by the contract manufacturer (CM). You don’t have to take any action. This section describes the tools that the CM must set up on the host machines for mass manufacturing your Sidewalk devices using the Sidewalk device CLI and the Sidewalk signing tool.

The following steps show you how to set up your host and install the required tools.

Topics


Step 1: Choose mode of setup

Depending on how you want to manufacture your devices, you can use a local or a networked setup. A local setup has both the signing tool and the YubiHSM connector running on the same machine. A networked setup moves the connector component into a server PC that is accessible through the local area network. If an HSM attached to a the signing server can support multiple line PCs, we recommend using a networked setup. Using a local setup requires every line PC to be associated with an HSM.

sidewalk-operation-modes

This table shows more about the two modes of setup and the tools that must be installed on the hosts.

Local and networked setup
sidewalk-manufacturing-local-nw-setup


Step 2: Install YubiHSM SDK

YubiHSM is the supported hardware security module (HSM) vendor. Each Sidewalk product is provided a single HSM, or in some cases, multiple HSMs. A unique serial number is printed on each HSM, which can be used to help identify it.

The following steps show how to install the YubiHSM SDK:

  1. Install YubiHSM

    First install the YubiHSM from the YubiHSM product page. After you’ve installed the YubiHSM, you’ll receive a YubiHSM 2 Secure key.

  2. Install YubiHSM SDK

    To install the vendor-provided YubiHSM SDK, go to the YubiHSM2 releases page, and then download and install the SDK for Windows. To install the SDK, unzip the downloaded file and run the installer, yubihsm-connector-windows-amd64.msi.

This section showed how to install the required tools under a Windows environment. You can follow similar steps if you’re using Linux.


Step 3: Install OpenSSL

To use the line PC, you must have OpenSSL installed. On a UNIX machine, OpenSSL is available with the default installation. For more information, see OpenSSL. On a Windows machine, you can install OpenSSL from the OpenSSL binaries page.


Step 4: Install Sidewalk signing tool

The Sidewalk signing tool accepts and takes the CSR, and outputs the encoded signed Sidewalk certificate chain. To use the Sidewalk signing tool.

  1. First contact the Amazon Sidewalk team to get the latest version of the signing tool, sidewalk-signing-tool.py.

  2. After you receive the tool, install it by following the instructions in the README.md document.

  3. To install the required Python dependencies for using the signing tool, such as the Python interpreter, run the requirements file, requirements.txt contained in the signing tool. It will then install the required Python dependencies using pip.

    pip3 install -r requirements.txt
    

Step 5: Generate certificates for mutual authentication (networked setup)

This step is required only if you’re using the networked setup.

When using a networked setup, the HSM and the Sidewalk signing tool are located in different machines. To secure traffic over the network and use a secure connection between the two machines, we recommend that you use mutually authenticated TLS for the client and server to authenticate each other.

  1. Generate a local signing authority

    Generate a local signing authority that will be used to endorse both the client and server certificates. When you run this command, you’ll be prompted to enter a passphrase, and any phrase can be used.

    openssl req -new -x509 -subj "/CN=Sidewalk CA/" -keyout ca.key -out ca.pem -days 365
    

    You must securely store the key, ca.key. It must not be visible to the line PC or the signing server.

  2. Generate server certificate

    Generate the server certificate that the server will present to the Sidewalk signing tool when setting up a connection. The certificate is signed by the Local Signing Authority. To generate the server certificate.

    1. First create a V3 extension file, v3_server.ext.

      authorityKeyIdentifier=keyid,issuer
      basicConstraints=CA:FALSE
      keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
      extendedKeyUsage = serverAuth
      
    2. Then create the server certificate.

      # Create the Certificate Signing Request
      openssl req -new -newkey rsa:2048 -sha256 -nodes \ 
          -keyout server.key -out server.csr
            
      # Generate the certificate signed by the CA
      openssl x509 -req -days 365 -CA ca.pem -CAkey ca.key -CAcreateserial \ 
           -in server.csr -sha256 -out server.pem -extfile v3_server.ext
            
      # Enter the passphase provided when generating the local signing authority
      # Enter the IP/domain address of the server when asked for the CN
      
  3. Generate client certificate

    Generate the client certificate for the signing tool that will be presented to the server during authentication. You create the client certificate similar to how you created the server certificate.

    1. First create a V3 extension file, v3_client.ext

      authorityKeyIdentifier=keyid,issuer
      basicConstraints=CA:FALSE
      keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
      extendedKeyUsage = clientAuth
      
    2. Then create the client certificate.

      # create a certificate signing request
      openssl req -new -newkey rsa:2048 -sha256 -nodes -keyout client.key -out client.csr
            
      # create the client certificates signed with the Certificate Authority
      openssl x509 -req -days 365 -CA ca.pem -CAkey ca.key \
           -CAcreateserial -in client.csr -sha256 -out client.pem -extfile v3_client.ext
      

Step 6: Install Nginx on signing server (networked setup)

This step is required only if you’re using the networked setup.

Nginx is a web server that you install on the signing server for mutual authentication between the signing server and line PC. To install and configure Nginx, perform the following steps.

  1. Install Nginx

    Go to the Nginx website and install the tool by following the platform-specific instructions as described in the Installing Nginx open source documentation.

    [ Windows ]

    On a Windows machine, you can download the prebuilt Nginx binary from the Nginx for Windows web page. Unzip the binary file into the C:\nginx folder and then run it to install Nginx.

    [ Linux ]

    On a Linux or Ubuntu machine, you can install Nginx using apt.

    sudo apt install -y nginx
    
  2. Configure Nginx

    Configure Nginx depending on the platform that you’re running it from.

    [ Windows ]

    On a Windows machine, edit the configuration file at c:\nginx\conf\nginx.conf directly and replace the section server with the following configuration similar to the Linux section. In this example:

    • log_path is the path where the Nginx log is stored, such as C:/nginx.
    • cert_path is the path where the certificate is stored.
    server
    {
       listen 8081 ssl;
       listen [::]:8081 ssl;
       
       access_log C:/nginx/reverse-access.log;
       error_log C:/nginx/reverse-error.log;
       
       ssl_certificate <path>/server.pem;
       ssl_certificate_key <path>/server.key;
       
       ssl_client_certificate <path>/ca.pem;
       ssl_verify_client on;
       ssl_verify_depth 1;
       
       location / {
          if ($ssl_client_verify != SUCCESS) {
             return 403;
          }
          proxy_pass http://127.0.0.1:12345;
       }
    }
    

    [ Linux ]

    On a Linux or Ubuntu machine, perform the following steps to configure and enable Nginx.

    1. Create a configuration file, /etc/nginx/sites-available/reverse-proxy.conf, with these contents for the server configuration. In this example:
      • log_path is the path where the Nginx log is stored, such as /var/log/nginx.
      • cert_path is the path where the certificate is stored.
      server
      {
         listen 8081 ssl;
         listen [::]:8081 ssl;
            
         access_log /var/log/nginx/reverse-access.log;
         error_log /var/log/nginx/reverse-error.log;
            
         ssl_certificate <path>/server.pem;
         ssl_certificate_key <path>/server.key;
            
         ssl_client_certificate <path>/ca.pem;
         ssl_verify_client on;
         ssl_verify_depth 1;
            
         location / {
            if ($ssl_client_verify != SUCCESS) {
               return 403;
            }
            proxy_pass http://127.0.0.1:12345;
         }
      }
      
    2. Enable the config by running the following command.

      sudo ln -s /etc/nginx/sites-available/reverse-proxy.conf /etc/nginx/sites-enabled/reverse-proxy.conf
      
  3. Enable Nginx

    Run the following platform-specific commands to enable Nginx.

    [ Windows ]

    On a Windows machine, run this command to enable Nginx.

    C:\nginx>start nginx
    

    [ Linux ]

    On a Linux or Ubuntu machine, run this command to restart and run Nginx.

    sudo systemctl restart nginx
    

Next Step: Provisioning with CSR and Sidewalk Signing tool


Back to top

©2023 Amazon.com, Inc. or its affiliates (collectively, “Amazon”). All Rights Reserved.