AWS IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the AWS IoT Greengrass V1 maintenance policy. After this date, AWS IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on AWS IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to AWS IoT Greengrass Version 2, which adds significant new features and support for additional platforms.
Module 7: Simulating hardware security integration
This feature is available for AWS IoT Greengrass Core v1.7 and later.
This advanced module shows you how to configure a simulated hardware security module (HSM) for use with a Greengrass core. The configuration uses SoftHSM, which is a pure software implementation that uses the PKCS#11 application programming interface (API). The purpose of this module is to allow you to set up an environment where you can learn and do initial testing against a software-only implementation of the PKCS#11 API. It is provided only for learning and initial testing, not for production use of any kind.
You can use this configuration to experiment
with using a PKCS#11-compatible service to store your private keys. For more
information about the software-only implementation, see SoftHSM
Important
This module is intended for experimentation purposes only. We strongly discourage the use of SoftHSM in a production environment because it might provide a false sense of additional security. The resulting configuration doesn't provide any actual security benefits. The keys stored in SoftHSM are not stored more securely than any other means of secrets storage in the Greengrass environment.
The purpose of this module is to allow you to learn about the PKCS#11 specification and do initial testing of your software if you plan to use a real hardware-based HSM in the future.
You must test your future hardware implementation separately and completely before any production usage because there might be differences between the PKCS#11 implementation provided in SoftHSM and a hardware-based implementation.
If you need assistance with the onboarding of a supported hardware security module, contact your AWS Enterprise Support representative.
Before you begin, run the Greengrass Device Setup script, or make sure that you completed Module 1 and Module 2 of the Getting Started tutorial. In this module, we assume that your core is already provisioned and communicating with AWS. This module should take about 30 minutes to complete.
Install the SoftHSM software
In this step, you install SoftHSM and the pkcs11 tools, which are used to manage your SoftHSM instance.
-
In a terminal on your AWS IoT Greengrass core device, run the following command:
sudo apt-get install softhsm2 libsofthsm2-dev pkcs11-dump
For more information about these packages, see Install softhsm2
, Install libsofthsm2-dev , and Install pkcs11-dump . Note
If you encounter issues when using this command on your system, see SoftHSM version 2
on GitHub. This site provides more installation information, including how to build from source.
Configure SoftHSM
In this step, you configure SoftHSM
-
Switch to the root user.
sudo su
-
Use the manual page to find the system-wide
softhsm2.conf
location. A common location is/etc/softhsm/softhsm2.conf
, but the location might be different on some systems.man softhsm2.conf
-
Create the directory for the softhsm2 configuration file in the system-wide location. In this example, we assume the location is
/etc/softhsm/softhsm2.conf
.mkdir -p /etc/softhsm
-
Create the token directory in the
/greengrass
directory.Note
If this step is skipped, softhsm2-util reports
ERROR: Could not initialize the library
.mkdir -p /greengrass/softhsm2/tokens
-
Configure the token directory.
echo "directories.tokendir = /greengrass/softhsm2/tokens" > /etc/softhsm/softhsm2.conf
-
Configure a file-based backend.
echo "objectstore.backend = file" >> /etc/softhsm/softhsm2.conf
Note
These configuration settings are intended for experimentation purposes only. To see all configuration options, read the manual page for the configuration file.
man softhsm2.conf
Import the private key into SoftHSM
In this step, you initialize the SoftHSM token, convert the private key format, and then import the private key.
-
Initialize the SoftHSM token.
softhsm2-util --init-token --slot 0 --label greengrass --so-pin 12345 --pin 1234
Note
If prompted, enter an SO pin of
12345
and a user pin of1234
. AWS IoT Greengrass doesn't use the SO (supervisor) pin, so you can use any value.If you receive the error
CKR_SLOT_ID_INVALID: Slot 0 does not exist
, try the following command instead:softhsm2-util --init-token --free --label greengrass --so-pin 12345 --pin 1234
-
Convert the private key to a format that can be used by the SoftHSM import tool. For this tutorial, you convert the private key that you obtained from the Default Group creation option in Module 2 of the Getting Started tutorial.
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in
hash
.private.key -outhash
.private.pem -
Import the private key into SoftHSM. Run only one of the following commands, depending on your version of softhsm2-util.
- Raspbian softhsm2-util v2.2.0 syntax
-
softhsm2-util --import hash.private.pem --token greengrass --label iotkey --id 0000 --pin 12340
- Ubuntu softhsm2-util v2.0.0 syntax
-
softhsm2-util --import hash.private.pem --slot 0 --label iotkey --id 0000 --pin 1234
This command identifies the slot as
0
and defines the key label asiotkey
. You use these values in the next section.
After the private key is imported, you can optionally remove it from the
/greengrass/certs
directory. Make sure to
keep the root CA and device certificates in the directory.
Configure the Greengrass core to use SoftHSM
In this step, you modify the Greengrass core configuration file to use SoftHSM.
Find the path to the SoftHSM provider library (
libsofthsm2.so
) on your system:Get the list of installed packages for the library.
sudo dpkg -L libsofthsm2
The
libsofthsm2.so
file is located in thesofthsm
directory.Copy the full path to the file (for example,
/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so
). You use this value later.
Stop the Greengrass daemon.
cd /greengrass/ggc/core/ sudo ./greengrassd stop
Open the Greengrass configuration file. This is the config.json file in the
/greengrass/config
directory.Note
The examples in this procedure are written with the assumption that the
config.json
file uses the format that's generated from the Default Group creation option in Module 2 of the Getting Started tutorial.-
In the
crypto.principals
object, insert the following MQTT server certificate object. Add a comma where needed to create a valid JSON file."MQTTServerCertificate": { "privateKeyPath": "path-to-private-key" }
-
In the
crypto
object, insert the followingPKCS11
object. Add a comma where needed to create a valid JSON file."PKCS11": { "P11Provider": "/path-to-pkcs11-provider-so", "slotLabel": "crypto-token-name", "slotUserPin": "crypto-token-user-pin" }
Your file should look similar to the following:
{ "coreThing" : { "caPath" : "root.ca.pem", "certPath" : "
hash
.cert.pem", "keyPath" : "hash
.private.key", "thingArn" : "arn:partition
:iot:region
:account-id
:thing/core-thing-name
", "iotHost" : "host-prefix
.iot.region
.amazonaws.com", "ggHost" : "greengrass.iot.region
.amazonaws.com", "keepAlive" : 600 }, "runtime" : { "cgroup" : { "useSystemd" : "yes" } }, "managedRespawn" : false, "crypto": {"PKCS11": { "P11Provider": "/path-to-pkcs11-provider-so", "slotLabel": "crypto-token-name", "slotUserPin": "crypto-token-user-pin" },
"principals" : {"MQTTServerCertificate": { "privateKeyPath": "path-to-private-key" },
"IoTCertificate" : { "privateKeyPath" : "file:///greengrass/certs/hash
.private.key", "certificatePath" : "file:///greengrass/certs/hash
.cert.pem" }, "SecretsManager" : { "privateKeyPath" : "file:///greengrass/certs/hash
.private.key" } }, "caPath" : "file:///greengrass/certs/root.ca.pem" } }Note
To use over-the-air (OTA) updates with hardware security, the
PKCS11
object must also contain theOpenSSLEngine
property. For more information, see Configure support for over-the-air updates. -
Edit the
crypto
object:Configure the
PKCS11
object.For
P11Provider
, enter the full path tolibsofthsm2.so
.For
slotLabel
, entergreengrass
.For
slotUserPin
, enter1234
.
Configure the private key paths in the
principals
object. Do not edit thecertificatePath
property.For the
privateKeyPath
properties, enter the following RFC 7512 PKCS#11 path (which specifies the key's label). Do this for theIoTCertificate
,SecretsManager
, andMQTTServerCertificate
principals.pkcs11:object=iotkey;type=private
-
Check the
crypto
object. It should look similar to the following:"crypto": { "PKCS11": { "P11Provider": "/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so", "slotLabel": "greengrass", "slotUserPin": "1234" }, "principals": { "MQTTServerCertificate": { "privateKeyPath": "pkcs11:object=iotkey;type=private" }, "SecretsManager": { "privateKeyPath": "pkcs11:object=iotkey;type=private" }, "IoTCertificate": { "certificatePath": "file://certs/core.crt", "privateKeyPath": "pkcs11:object=iotkey;type=private" } }, "caPath": "file://certs/root.ca.pem" }
-
Remove the
caPath
,certPath
, andkeyPath
values from thecoreThing
object. It should look similar to the following:"coreThing" : { "thingArn" : "arn:
partition
:iot:region
:account-id
:thing/core-thing-name", "iotHost" : "host-prefix
-ats.iot.region
.amazonaws.com", "ggHost" : "greengrass-ats.iot.region
.amazonaws.com", "keepAlive" : 600 }
Note
For this tutorial, you specify the same private key for all principals. For more information about choosing the private key for the local MQTT server, see Performance. For more information about the local secrets manager, see Deploy secrets to the AWS IoT Greengrass core.
Test the configuration
Start the Greengrass daemon.
cd /greengrass/ggc/core/ sudo ./greengrassd start
If the daemon starts successfully, then your core is configured correctly.
You are now ready to learn about the PKCS#11 specification and do initial testing with the PKCS#11 API that's provided by the SoftHSM implementation.
Important
Again, it's extremely important to be aware that this module is intended for learning and testing only. It doesn't actually increase the security posture of your Greengrass environment.
Instead, the purpose of the module is to enable you to start learning and testing in preparation for using a true hardware-based HSM in the future. At that time, you must separately and completely test your software against the hardware-based HSM prior to any production usage, because there might be differences between the PKCS#11 implementation provided in SoftHSM and a hardware-based implementation.
See also
-
PKCS #11 Cryptographic Token Interface Usage Guide Version 2.40. Edited by John Leiseboer and Robert Griffin. 16 November 2014. OASIS Committee Note 02. http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/cn02/pkcs11-ug-v2.40-cn02.html
. Latest version: http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/pkcs11-ug-v2.40.html .