Hardware security integration - Amazon IoT Greengrass
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Hardware security integration

Note

This feature is available for v2.5.3 and later of the Greengrass nucleus component. Amazon IoT Greengrass doesn't currently support this feature on Windows core devices.

You can configure the Amazon IoT Greengrass Core software to use a hardware security module (HSM) through the PKCS#11 interface. This feature enables you to securely store the device's private key and certificate so that they aren't exposed or duplicated in software. You can store the private key and certificate on a hardware module such as an HSM or a Trusted Platform Module (TPM).

The Amazon IoT Greengrass Core software uses a private key and X.509 certificate to authenticate connections to the Amazon IoT and Amazon IoT Greengrass services. The secret manager component uses this private key to securely encrypt and decrypt the secrets that you deploy to a Greengrass core device. When you configure a core device to use an HSM, these components use the private key and certificate that you store in the HSM.

The Moquette MQTT broker component also stores a private key for its local MQTT server certificate. This component store the private key on the device's file system in the component's work folder. Currently, Amazon IoT Greengrass doesn't support storing this private key or certificate in an HSM.

Tip

Search for devices that support this feature in the Amazon Partner Device Catalog.

Requirements

You must meet the following requirements to use an HSM on a Greengrass core device:

  • Greengrass nucleus v2.5.3 or later installed on the core device. You can choose a compatible version when you install the Amazon IoT Greengrass Core software on a core device.

  • The PKCS#11 provider component installed on the core device. You can download and install this component when you install the Amazon IoT Greengrass Core software on a core device.

  • A hardware security module that supports the PKCS#1 v1.5 signature scheme and RSA keys with an RSA-2048 key size (or larger) or ECC keys.

    Note

    To use a hardware security module with ECC keys, you must use Greengrass nucleus v2.5.6 or later.

    To use a hardware security module and secret manager, you must use a hardware security module with RSA keys.

  • A PKCS#11 provider library that the Amazon IoT Greengrass Core software can load at runtime (using libdl) to invoke PKCS#11 functions. The PKCS#11 provider library must implement the following PKCS#11 API operations:

    • C_Initialize

    • C_Finalize

    • C_GetSlotList

    • C_GetSlotInfo

    • C_GetTokenInfo

    • C_OpenSession

    • C_GetSessionInfo

    • C_CloseSession

    • C_Login

    • C_Logout

    • C_GetAttributeValue

    • C_FindObjectsInit

    • C_FindObjects

    • C_FindObjectsFinal

    • C_DecryptInit

    • C_Decrypt

    • C_DecryptUpdate

    • C_DecryptFinal

    • C_SignInit

    • C_Sign

    • C_SignUpdate

    • C_SignFinal

    • C_GetMechanismList

    • C_GetMechanismInfo

    • C_GetInfo

    • C_GetFunctionList

  • The hardware module must be resolvable by slot label, as defined in the PKCS#11 specification.

  • You must store the private key and certificate in the HSM in the same slot, and they must use the same object label and object ID, if the HSM supports object IDs.

  • The certificate and private key must be resolvable by object labels.

  • The private key must have the following permissions:

    • sign

    • decrypt

  • (Optional) To use the secret manager component, you must use version 2.1.0 or later, and the private key must have the following permissions:

    • unwrap

    • wrap

Hardware security best practices

Consider the following best practices when you configure hardware security on Greengrass core devices.

  • Generate private keys directly on the HSM by using the internal hardware random-number generator. This approach is more secure than importing a private key that you generate elsewhere, because the private key remains within the HSM.

  • Configure private keys to be immutable and prohibit export.

  • Use the provisioning tool that the HSM hardware vendor recommends to generate a certifacte signing request (CSR) using the hardware-protected private key, and then use the Amazon IoT console or API to generate a client certificate.

Note

The security best practice to rotate keys doesn't apply when you generate private keys on an HSM.

Install the Amazon IoT Greengrass Core software with hardware security

When you install the Amazon IoT Greengrass Core software, you can configure it to use a private key that you generate in an HSM. This approach follows the security best practice to generate the private key in the HSM, so the private key remains within the HSM.

To install the Amazon IoT Greengrass Core software with hardware security, you do the following:

  1. Generate a private key in the HSM.

  2. Create a certificate signing request (CSR) from the private key.

  3. Create a certificate from the CSR. You can create a certificate signed by Amazon IoT or by another root certificate authority (CA). For more information about how to use another root CA, see Create your own client certificates in the Amazon IoT Core Developer Guide.

  4. Download the Amazon IoT certificate and import it into the HSM.

  5. Install the Amazon IoT Greengrass Core software from a configuration file that specifies to use the PKCS#11 provider component and the private key and certificate in the HSM.

You can choose one of the following installation options to install the Amazon IoT Greengrass Core software with hardware security:

Currently, Amazon IoT Greengrass doesn't support installing the Amazon IoT Greengrass Core software with hardware security when you install with automatic resource provisioning or Amazon IoT fleet provisioning.

Configure hardware security on an existing core device

You can import a core device's private key and certificate to an HSM to configure hardware security.

Considerations
  • You must have root access to the core device's file system.

  • In this procedure, you shut down the Amazon IoT Greengrass Core software, so the core device is offline and unavailable while you configure hardware security.

To configure hardware security on an existing core device, you do the following:

  1. Initialize the HSM.

  2. Deploy the PKCS#11 provider component to the core device.

  3. Stop the Amazon IoT Greengrass Core software.

  4. Import the core device's private key and certificate to the HSM.

  5. Update the Amazon IoT Greengrass Core software's configuration file to use the private key and certificate in the HSM.

  6. Start the Amazon IoT Greengrass Core software.

Step 1: Initialize the hardware security module

Complete the following step to initialize the HSM on your core device.

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.

Step 2: Deploy the PKCS#11 provider component

Complete the following steps to deploy and configure the PKCS#11 provider component. You can deploy the component to one or more core devices.

  1. In the Amazon IoT Greengrass console navigation menu, choose Components.

  2. On the Components page, choose the Public components tab, and then choose aws.greengrass.crypto.Pkcs11Provider.

  3. On the aws.greengrass.crypto.Pkcs11Provider page, choose Deploy.

  4. From Add to deployment, choose an existing deployment to revise, or choose to create a new deployment, and then choose Next.

  5. If you chose to create a new deployment, choose the target core device or thing group for the deployment. On the Specify target page, under Deployment target, choose a core device or thing group, and then choose Next.

  6. On the Select components page, under Public components, select aws.greengrass.crypto.Pkcs11Provider, and then choose Next.

  7. On the Configure components page, select aws.greengrass.crypto.Pkcs11Provider, and then do the following:

    1. Choose Configure component.

    2. In the Configure aws.greengrass.crypto.Pkcs11Provider modal, under Configuration update, in Configuration to merge, enter the following configuration update. Update the following configuration parameters with values for the target core devices. Specify the slot ID and user PIN where you initialized the PKCS#11 token earlier. You import the private key and certificate into this slot in the HSM later.

      name

      A name for the PKCS#11 configuration.

      library

      The absolute file path to the PKCS#11 implementation's library that the Amazon IoT Greengrass Core software can load with libdl.

      slot

      The ID of the slot that contains the private key and device certificate. This value is different than the slot index or slot label.

      userPin

      The user PIN to use to access the slot.

      { "name": "softhsm_pkcs11", "library": "/usr/lib/softhsm/libsofthsm2.so", "slot": 1, "userPin": "1234" }
    3. Choose Confirm to close the modal, and then choose Next.

  8. On the Configure advanced settings page, keep the default configuration settings, and choose Next.

  9. On the Review page, choose Deploy.

    The deployment can take up to a minute to complete.

To deploy the PKCS#11 provider component, create a deployment document that includes aws.greengrass.crypto.Pkcs11Provider in the components object, and specify the configuration update for the component. Follow instructions in Create deployments to create a new deployment or revise an existing deployment.

The following example partial deployment document specifies to deploy and configure the PKCS#11 provider component. Update the following configuration parameters with values for the target core devices. Save the slot ID and user PIN to use later when you import the private key and certificate into the HSM.

name

A name for the PKCS#11 configuration.

library

The absolute file path to the PKCS#11 implementation's library that the Amazon IoT Greengrass Core software can load with libdl.

slot

The ID of the slot that contains the private key and device certificate. This value is different than the slot index or slot label.

userPin

The user PIN to use to access the slot.

{ "name": "softhsm_pkcs11", "library": "/usr/lib/softhsm/libsofthsm2.so", "slot": 1, "userPin": "1234" }
{ ..., "components": { ..., "aws.greengrass.crypto.Pkcs11Provider": { "componentVersion": "2.0.0", "configurationUpdate": { "merge": "{\"name\":\"softhsm_pkcs11\",\"library\":\"/usr/lib/softhsm/libsofthsm2.so\",\"slot\":1,\"userPin\":\"1234\"}" } } } }

The deployment can take several minutes to complete. You can use the Amazon IoT Greengrass service to check the status of the deployment. You can check the Amazon IoT Greengrass Core software logs to verify that the PKCS#11 provider component deploys successfully. For more information, see the following:

If the deployment fails, you can troubleshoot the deployment on each core device. For more information, see Troubleshooting Amazon IoT Greengrass V2.

Step 3: Update the configuration on the core device

The Amazon IoT Greengrass Core software uses a configuration file that specifies how the device operates. This configuration file includes where to find the private key and certificate that the device uses to connect to the Amazon Web Services Cloud. Complete the following steps to import the core device's private key and certificate into the HSM and update the configuration file to use the HSM.

To update the configuration on the core device to use hardware security
  1. Stop the Amazon IoT Greengrass Core software. If you configured the Amazon 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 Amazon 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 Amazon 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 Amazon IoT Greengrass Core software configuration to use the private key and certificate in the HSM.

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

    Do the following:

    1. Create a back up of the Amazon 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 Amazon 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 Amazon 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 Amazon IoT Greengrass Core software. If you configured the Amazon 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 Amazon IoT Greengrass Core software.

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

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

    The following INFO-level log messages indicate that the Amazon IoT Greengrass Core software successfully connects to the Amazon IoT and Amazon 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 Amazon 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

Use hardware without PKCS#11 support

The PKCS#11 library is typically provided by the hardware vendor or is open source. For example, with standards-compliant hardware (such as TPM1.2), it might be possible to use existing open source software. However, if your hardware doesn't have a corresponding PKCS#11 library implementation, or if you want to write a custom PKCS#11 provider, contact your Amazon Web Services Enterprise Support representative with integration-related questions.

See also