Hardware security integration

To initialize the hardware security module

• Initialize an PKCS#11 token in the HSM, and save the slot ID and user PIN that for the token. Check the documentation for your HSM to learn how to initialize a token. You use the slot ID and user PIN later when you deploy and configure the PKCS#11 provider component.

To update the configuration on the core device to use hardware security

1. Stop the AWS IoT Greengrass Core software. If you configured the AWS IoT Greengrass Core software as a system service with systemd, you can run the following command to stop the software.

   sudo systemctl stop greengrass.service

2. Find the core device's private key and certificate files.

   • If you installed the AWS IoT Greengrass Core software with automatic provisioning or fleet provisioning, the private key exists at /greengrass/v2/privKey.key, and the certificate exists at /greengrass/v2/thingCert.crt.

   • If you installed the AWS IoT Greengrass Core software with manual provisioning, the private key exists at /greengrass/v2/private.pem.key by default, and the certificate exists at /greengrass/v2/device.pem.crt by default.

   You can also check the system.privateKeyPath and system.certificateFilePath properties in /greengrass/v2/config/effectiveConfig.yaml to find the location of these files.

3. Import the private key and certificate into the HSM. Check the documentation for your HSM to learn how to import private keys and certificates into it. Import the private key and certificate using the slot ID and user PIN where you initialized the PKCS#11 token earlier. You must use the same object label and object ID for the private key and the certificate. Save the object label that you specify when you import each file. You use this label later when you update the AWS IoT Greengrass Core software configuration to use the private key and certificate in the HSM.

4. Update the AWS IoT Greengrass Core configuration to use the private key and certificate in the HSM. To update the configuration, you modify the AWS IoT Greengrass Core configuration file and run the AWS IoT Greengrass Core software with the updated configuration file to apply the new configuration.

   Do the following:

   1. Create a back up of the AWS IoT Greengrass Core configuration file. You can use this back up to restore the core device if you run into issues when you configure hardware security.

      sudo cp /greengrass/v2/config/effectiveConfig.yaml ~/ggc-config-backup.yaml

   2. Open the AWS IoT Greengrass Core configuration file in a text editor. For example, you can run the following command to use GNU nano to edit the file. Replace /greengrass/v2 with the path to the Greengrass root folder.

      sudo nano /greengrass/v2/config/effectiveConfig.yaml

   3. Replace the value of the system.privateKeyPath with the PKCS#11 URI for the private key in the HSM. Replace iotdevicekey with the object label where you imported the private key and certificate earlier.

      pkcs11:object=iotdevicekey;type=private

   4. Replace the value of the system.certificateFilePath with the PKCS#11 URI for the certificate in the HSM. Replace iotdevicekey with the object label where you imported the private key and certificate earlier.

      pkcs11:object=iotdevicekey;type=cert

   After you finish these steps, the system property in the AWS IoT Greengrass Core configuration file should look similar to the following example.

   system:
     certificateFilePath: "pkcs11:object=iotdevicekey;type=cert"
     privateKeyPath: "pkcs11:object=iotdevicekey;type=private"
     rootCaPath: "/greengrass/v2/rootCA.pem"
     rootpath: "/greengrass/v2"
     thingName: "MyGreengrassCore"

5. Apply the configuration in the updated effectiveConfig.yaml file. Run Greengrass.jar with the --init-config parameter to apply the configuration in effectiveConfig.yaml. Replace /greengrass/v2 with the path to the Greengrass root folder.

   sudo java -Droot="/greengrass/v2" \
     -jar /greengrass/v2/alts/current/distro/lib/Greengrass.jar \
     --start false \
     --init-config /greengrass/v2/config/effectiveConfig.yaml

6. Start the AWS IoT Greengrass Core software. If you configured the AWS IoT Greengrass Core software as a system service with systemd, you can run the following command to start the software.

   sudo systemctl start greengrass.service

   For more information, see Run the AWS IoT Greengrass Core software.

7. Check the AWS IoT Greengrass Core software logs to verify that the software starts and connects to the AWS Cloud. The AWS IoT Greengrass Core software uses the private key and certificate to connect to the AWS IoT and AWS IoT Greengrass services.

   sudo tail -f /greengrass/v2/logs/greengrass.log

   The following INFO-level log messages indicate that the AWS IoT Greengrass Core software successfully connects to the AWS IoT and AWS IoT Greengrass services.

   2021-12-06T22:47:53.702Z [INFO] (Thread-3) com.aws.greengrass.mqttclient.AwsIotMqttClient: Successfully connected to AWS IoT Core. {clientId=MyGreengrassCore5, sessionPresent=false}

8. (Optional) After you verify that the AWS IoT Greengrass Core software works with the private key and certificate in the HSM, delete the private key and certificate files from the device's file system. Run the following command, and replace the file paths with the paths to the private key and certificate files.

   sudo rm /greengrass/v2/privKey.key
   sudo rm /greengrass/v2/thingCert.crt