Provisioning with CSR and Sidewalk Signing tool

Each device being manufactured needs to have a unique device certificate. The Sidewalk Signing Tool running on the Line PC will take PEM key files to generate a Sidewalk certificate and signs it using the Device Attestation Key (DAK) securely stored in the provided Hardware Security Module (HSM). The following steps are involved in provisioning for the manufacturing workflow.

Topics

Step 1: Generate CSRs for Sidewalk signing tool
Step 2: Run the YubiHSM connector in the background
Step 3: Run the Sidewalk signing tool

Step 1: Generate CSRs for Sidewalk signing tool

Before your Sidewalk signing tool can sign the certificates, generate the required CSRs for the tool as described in the following steps.

Sidewalk-Signing-Tool

Generate the NIST-P256 and ED25519 device keys by using the following commands:

Create the P256R1 device private key.

 # Create the private key
 openssl ecparam -name prime256v1 -genkey -out p256.priv

Create ED25519 device private key.
```
# Create the private key
openssl genpkey -algorithm ed25519 -out ed25519.priv
```
Step 2: Run the YubiHSM connector in the background

If you’re using a Windows machine, the YubiHSM connector runs automatically as a service in the background. You don’t have to manually start the connector.

On the machine that the HSM is attached to, run the YubiHSM connector in the background. If you’re using the networked setup, the HSM is on the signing server. If you’re using the local setup, run the connector on the line PC. For more information, see Step 1: Choose mode of setup.

On a Linux or Ubuntu machine, you run the connector using the yubihsm-connector command without any outputs.

# yubihsm-connector is running without any outputs here.
yubihsm-connector

Step 3: Run the Sidewalk signing tool

The following shows the parameters that the Sidewalk signing tool can accept, some usage examples, and the output of running the tool.

Sidewalk signing tool parameters

The following table shows the parameters that the Sidewalk signing tool can accept and their description. For more information about the signing tool parameters, run the following command.

sidewalk-signing-tool --help

Signing tool parameters

Parameter	Description
--product	The product tag identifying which DAK in HSM is used for the signing operation. This tag will be provided by Amazon for some specific product and usually starts with prefix ‘PREPROD_DAK’ or ‘RNET_DAK’.
--pin	The PIN code to access the HSM. Provided by Amazon along with the product tag.
--ed25519_private_key_file and --p256r1_private_key_file	The paths to PEM files for device private keys. The Sidewalk Signing Tool will extract the private/public keys from these files and generate CSRs for signing automatically.
--device_profile_json (AWS Flow only)	The JSON file downloaded from AWS for the device profile, from which the Sidewalk Signing Tool get the app server key and put it to the output file so provision.py can take use of it. This is only for AWS flow; The main reason of having this input is to pass the application server public key from the device profile to provision.py. In ACS flow the public key will be provided explicitly with the command line argument of provision.py.
-o	The filename of the output from the Sidewalk Signing Tool, which contains the device certificate and Sidewalk certificate chains that will be used as input of provision.py
--connector	The URL for the singing server, including the information for protocol (http or https), IP\/domain name, and the port number. If you are using local installation, it should be the URL to the local yubihsm-connector, which is normally “http://localhost:12345”
--generate_smsn	Ask the Signing Tools to generate the SMSN based on the information provided with --device_type\/--dsn\/\–apid. Please always use this argument.
--ca_cert, --client_cert and --client_key	These 3 arguments are mandatory for establishing HTTPS channel with the signing server.

General usage example

The following command shows an example of how you run the tool. In this example:

The arguments ca_cert, client_cert, and client_key are only required when you use the networked installation since it requires authentication between the line PCs and the signing server.
The argument --generate_smsn automatically generates and includes the Sidewalk manufacturing serial number (SMSN).

# Usage Example
python3 sidewalk_signing_tool.py --product=<model label> --pin=<hsm pin> \
    --ed25519_private_key_file=<ed25519_private_key_file> --p256r1_private_key_file=<p256r1_key_file> \
    --connector=<connector url> --generate_smsn --device_type=<device_type> --dsn=<device serial number> \
    --apid=<advertised product id> --device_profile_json=<device_profile.json> \
    -o out.json [--ca_cert=<CA for signing server> --client_cert=<client certificate> --client_key=<client key>]

Local installation example

The following command shows an example of how you run the tool when using local installation. In this example, the tool runs on the line PC.

# Example for local installation:
python3 sidewalk_signing_tool.py --product=RNET_DAK_PROJNAME --pin=password \
    --ed25519_private_key_file=ed25519.pem --p256r1_private_key_file=p256r1.pem \
    --connector=http://localhost:12345 --generate_smsn --device_type=Test --dsn=test --apid=Test \
    --device_profile_json=device_profile.json

Networked installation example

The following command shows an example of how you run the tool when using local installation. In this example, the tool runs on the line PC and the YubiHSM connector runs on the signing server so a secure connection is required between the two machines.

# Example for networked installation where the signing server is at 192.168.10.100.
# In the signing tool, the ca_cert, client_cert and client_key options
# can be used to set the certificate and specify the expected certificate authority.
python3 sidewalk_signing_tool.py --product=RNET_DAK_PROJNAME --pin=password \
    --ed25519_private_key_file=ed25519.pem --p256r1_private_key_file=p256r1.pem \
    --connector=https://192.168.10.100:8081 --generate_smsn --device_type=TEST --dsn=test --apid=TEST \
    --ca_cert ca.pem --client_cert client.pem --client_key client.key --device_profile_json=device_profile.json

Sidewalk signing tool output

After you run the signing tool using the commands listed below, if the tool runs successfully, the Sidewalk certificate chains will be returned as output. The following code shows a sample output.

{
    "p256R1": "JNTwXmILBd2ODPSSedYVApPAGe3L106QZ0O1h7wfHTUS2bl5RhLFmNv2wONst3AJrP4EeFZzxgp/9CDLmKqQ3oaWjpKj7kzTEN7cHGXMEjfaSkCrZYapniZU69cCEdx95rqUTpOznRoU+UUoWfQH87miQTb7eZ2Z9aoU2tfhYEpCt+wECVe4yG6AeyDqUwAu5NXENHpDINqKvmQ4Unvo2QEbAPoa3S1vRP76DRFMPgxiAZQf0f6MPmHYDk36jZf15X/27zItrOY5ncq8Nvvd7+QYnBxuzvm81S0EC75SDBMiIQuJp76fqSp9nD8sc7e9q77z9sNH3VRgr1yMlUvPL23q9KpReX74lzgsR4PQcb4adveZtNgRdg7WQSaJmXO7+/a3ADkAHhkBxxYiFTYJrTtKkl76uiYzOVwtP6iOiLuRelB+duOs7pv78lAePrMJiIRSNde7xVqMbZdZh1LvtkfbehV1Bdaci9ycUsUMcPM6Yz+4Kv6Q7XJnsmb7y0jzVUoNOytE0rUa3DPJIp2GiNWwlXaekip2QYqMpljSIzI2yQG3BSI4ADXAHz7LWq1q9ZMJPxHAvrQdZ9OM+7G7nOI1Yh82xuBLpUs3O6RPrBt7hcnGMUqwu3NpVStN/s0UlNNkF+nyNTmL+qMl8xSwDkVt9I11sJxwc3SirF97ESgkkP/cceVD3pIR1TTnUWZLYrK6iNNquQt93AyqJeV2aRe3EtOWCrs4HJTkHUAAALPsP34BS6EzJO5AsS5pC7QTpjBtAbLN9SdXOT9w4H1x8Nkp0ujLxWRN37IEy0V9DrPK2w1g74uqWPfUPnSBjtvM55JnQpmm23WQNvHa1Vr6zmWDjzjHpcNirPbzXyBlKEhkX4xylaSMnm4UrVXtAMaAJ/csC4HPTKr3dazdvEkhwGAAAIFByCjSp/5WHc4AhsyjMvKCsZQiKgiI8ECwjfXBaSZdY4zYsRlO3FC428H1atrFChFCZT0Bqt5LPXD38bMSB+vAUJiP8XqiEdXeqf2mYMJ5ykoDpwkve/cUQfPpjzFQlQfvwjBwiJDANKkOKoNT3bUGz+/f/pyTE+xMRdIUBZ1Bw==",
    "eD25519": "JNTwXmILBd2ODPSSedYVApPAGe3L106QZ0O1h7wfHTUKYxUkbsfdzOECzOBCSTKyCoqF2+mTIX99lXVbETobCtc37/DMHFP2AWgGH0OHegrTd4AyjVB9xhhFqUeJNsQhUM2bbxtwh7nQKKJOjuDbw2T0BoUQaupg6SuQo2cRmgwBHAD6Fc/FAIWYJ7yFKcbwLE4gdihuA1QvGzcxqbqHTJDSI/Yabdz0pQKIJuz0mrHA5qAHogcPz2lvqERJqXuTKxavUR6Cqnt4G4AVxUAaZbKwJypUzGbOkXvuABm+/Nu1GHQAAOUAeOvZnM7+/x5b6xDnknjdjeHgLtMFbKcqjri59LDbhZM2LCUd0Z9Yce2wahqYja+4hdEqq61aAYGWDZjzs5Jf9KPuUQakAvNA8qNJTOKAcYL/rh+7G63iCR9KW5t0gt+1AQDYAHzSO0Dw/C+YOxINIP2tbWOjE3SP4W/aO9sVphTD0IuEWzgiXASwC3a3AGKZWIo2vgP4ASDRTTwT0P8AgVxc2kAbSlw4y/QxIA1zDZvO8dx+DgjC1/xchftBOaO8YpwvxwJ1AAADGz+gFBeX/ZNN8VJwnsNfgzj4me1HgVJdUo4W9kvx9cr2jHWkC3Oj/bdBTh1+yBjOC53yHlQK/l1GHrEWiWPPnE434LRxnWkwr8EHD4oieJxC8fkIxkQfj+gHhU79Z+oAAYAAAzsnf9SDIZPoDXF0TdC9POqTgld0oXDl2XPaVD4CvvLearrOSlFv+lsNbC4rgZn23MtIBM/7YQmJwmQ+FXRup6Tkubg1hpz04J/09dxg8UiZmntHiUr1GfkTOFMYqRB+Aw==",
    "metadata": {
        "smsn" : "24D4F05E620B05DD8E0CF49279D6150293C019EDCBD74E906743B587BC1F1D35",
        "apid" : "CfnC"
    }
}

Include private keys in output
The output of the JSON files does not include the private keys, which are required for a device to join the Sidewalk network. To include this information into the JSON file, specify the arguments --p256r1_private_key and --ed25519_private_key when using the Sidewalk signing tool. The tool will then insert the fields devicePrivKeyEd25519 and devicePrivKeyP256R1 into the JSON file that contains this information. For more information about the parameters, see Sidewalk signing tool parameters.

The following code shows a sample signing tool output with the --ed25519_private_key 5041b68494e5ead77df088c245d2fa618f71e84a8f23494752e6547acf8bdd63, and --p256r1_private_key ec4df3bee946213636f3478ce334415c380f75c0a008afd5bbe001e09826a874.

{
    "p256R1": "JNTwXmILBd2ODPSSedYVApPAGe3L106QZ0O1h7wfHTUS2bl5RhLFmNv2wONst3AJrP4EeFZzxgp/9CDLmKqQ3oaWjpKj7kzTEN7cHGXMEjfaSkCrZYapniZU69cCEdx95rqUTpOznRoU+UUoWfQH87miQTb7eZ2Z9aoU2tfhYEpCt+wECVe4yG6AeyDqUwAu5NXENHpDINqKvmQ4Unvo2QEbAPoa3S1vRP76DRFMPgxiAZQf0f6MPmHYDk36jZf15X/27zItrOY5ncq8Nvvd7+QYnBxuzvm81S0EC75SDBMiIQuJp76fqSp9nD8sc7e9q77z9sNH3VRgr1yMlUvPL23q9KpReX74lzgsR4PQcb4adveZtNgRdg7WQSaJmXO7+/a3ADkAHhkBxxYiFTYJrTtKkl76uiYzOVwtP6iOiLuRelB+duOs7pv78lAePrMJiIRSNde7xVqMbZdZh1LvtkfbehV1Bdaci9ycUsUMcPM6Yz+4Kv6Q7XJnsmb7y0jzVUoNOytE0rUa3DPJIp2GiNWwlXaekip2QYqMpljSIzI2yQG3BSI4ADXAHz7LWq1q9ZMJPxHAvrQdZ9OM+7G7nOI1Yh82xuBLpUs3O6RPrBt7hcnGMUqwu3NpVStN/s0UlNNkF+nyNTmL+qMl8xSwDkVt9I11sJxwc3SirF97ESgkkP/cceVD3pIR1TTnUWZLYrK6iNNquQt93AyqJeV2aRe3EtOWCrs4HJTkHUAAALPsP34BS6EzJO5AsS5pC7QTpjBtAbLN9SdXOT9w4H1x8Nkp0ujLxWRN37IEy0V9DrPK2w1g74uqWPfUPnSBjtvM55JnQpmm23WQNvHa1Vr6zmWDjzjHpcNirPbzXyBlKEhkX4xylaSMnm4UrVXtAMaAJ/csC4HPTKr3dazdvEkhwGAAAIFByCjSp/5WHc4AhsyjMvKCsZQiKgiI8ECwjfXBaSZdY4zYsRlO3FC428H1atrFChFCZT0Bqt5LPXD38bMSB+vAUJiP8XqiEdXeqf2mYMJ5ykoDpwkve/cUQfPpjzFQlQfvwjBwiJDANKkOKoNT3bUGz+/f/pyTE+xMRdIUBZ1Bw==",
    "eD25519": "JNTwXmILBd2ODPSSedYVApPAGe3L106QZ0O1h7wfHTUKYxUkbsfdzOECzOBCSTKyCoqF2+mTIX99lXVbETobCtc37/DMHFP2AWgGH0OHegrTd4AyjVB9xhhFqUeJNsQhUM2bbxtwh7nQKKJOjuDbw2T0BoUQaupg6SuQo2cRmgwBHAD6Fc/FAIWYJ7yFKcbwLE4gdihuA1QvGzcxqbqHTJDSI/Yabdz0pQKIJuz0mrHA5qAHogcPz2lvqERJqXuTKxavUR6Cqnt4G4AVxUAaZbKwJypUzGbOkXvuABm+/Nu1GHQAAOUAeOvZnM7+/x5b6xDnknjdjeHgLtMFbKcqjri59LDbhZM2LCUd0Z9Yce2wahqYja+4hdEqq61aAYGWDZjzs5Jf9KPuUQakAvNA8qNJTOKAcYL/rh+7G63iCR9KW5t0gt+1AQDYAHzSO0Dw/C+YOxINIP2tbWOjE3SP4W/aO9sVphTD0IuEWzgiXASwC3a3AGKZWIo2vgP4ASDRTTwT0P8AgVxc2kAbSlw4y/QxIA1zDZvO8dx+DgjC1/xchftBOaO8YpwvxwJ1AAADGz+gFBeX/ZNN8VJwnsNfgzj4me1HgVJdUo4W9kvx9cr2jHWkC3Oj/bdBTh1+yBjOC53yHlQK/l1GHrEWiWPPnE434LRxnWkwr8EHD4oieJxC8fkIxkQfj+gHhU79Z+oAAYAAAzsnf9SDIZPoDXF0TdC9POqTgld0oXDl2XPaVD4CvvLearrOSlFv+lsNbC4rgZn23MtIBM/7YQmJwmQ+FXRup6Tkubg1hpz04J/09dxg8UiZmntHiUr1GfkTOFMYqRB+Aw==",
    "metadata": {
        "smsn" : "24D4F05E620B05DD8E0CF49279D6150293C019EDCBD74E906743B587BC1F1D35",
        "apid" : "GZBd",
        "devicePrivKeyEd25519": "5041b68494e5ead77df088c245d2fa618f71e84a8f23494752e6547acf8bdd63",
        "devicePrivKeyP256R1": "ec4df3bee946213636f3478ce334415c380f75c0a008afd5bbe001e09826a874"
    }
}

Next Step: Constructing and uploading Sidewalk control logs