5.4.1. Greengrass Demo for Linux

AWS IoT Greengrass is a software provided by AWS to extend cloud capabilities to locally connected devices. This allows local devices to publish/subscribe to a topic even if there is no connectivity with AWS IoT console. A Greengrass group consists of a Greengrass core, multiple Greengrass devices connected to that core, and lambda functions and other services running on that core. In this, the Greengrass core performs the functions of AWS IoT console.

Also see What Is AWS IoT Greengrass for more details about AWS IoT Greengrass.

This demo is to demonstrate how to integrate SE050 with AWS IoT Greengrass core and RaspberryPi as hardware security to store core specific credentials for IoT client and MQTT server.

Note

Hardware security feature is available only for AWS IoT Greengrass Core v1.7 and later. We have used Greengrass core v1.10.0 for integration

5.4.1.1. Prerequisites

  • AWS Greengrass account (Also see supported regions for Greengrass)

  • RaspberryPi 3 Model B+ or Model B. The architecture of your Pi must be armv7l or later

  • Raspbian Buster operating system

  • Python 2.7

  • ssscli Tool. Refer to CLI Tool

5.4.1.2. Preparing the Greengrass group

  1. Follow the modules 1 and 2 as described in Environment Setup for Greengrass to set up Greengrass group and Greengrass core.

    Note

    In Module 2, if you choose Easy Group Creation, AWS will create credentials for Greengrass IoT core and provision in the registry. Skip the next step if you choose Easy Group Creation. You could otherwise create your own credentials and provision AWS registry as explained in the next step.

  2. If you wish to use your own credentials, upload the your RootCA and verification certificate in Secure->CAs tab under IoT Core.

    • While creating Greengrass group, choose Advanced group creation.

    • You can either assign IAM role or skip it for later.

    • Under Set up your security, choose Advanced setup and then choose Use my certificate.

    • Select your active RootCA certificate and upload corresponding device certificate

  3. If you used your own credentials, download sample config.json file for greengrass available at AWS IoT Greengrass Core Configuration File

    After completing Module 2, store your device certificate under certs directory where you have extracted AWS IoT Greengrass core software (by default /greengrass directory) and the downloaded config.json under config directory.

  4. Do NOT run the daemon yet.

5.4.1.3. Provisioning SE050 and Building PKCS#11 library

  1. Before running the Greengrass daemon, you would need to provision your SE050 and build PKCS#11 library.

  2. Complete Section 9.3 Steps needed before running ssscli tool for ssscli tool setup

  3. Run the following steps to provision your SE050 with Greengrass core keypair:

    ssscli connect se050 t1oi2c none
    ssscli se05x reset
    ssscli set ecc pair 0x20181001 <path-to-core-keypair>
    ssscli disconnect
    

    Note

    Greengrass uses labels to address objects on tokens. To make the PKCS#11 library use a specific keyID, the label should start with sss: followed by 32-bit keyID in hexadecimal format (little endian). For example, the label for the command used above would be sss:01101820.

  4. Build and install PKCS#11 library for Greengrass core. Refer to Section 8.7 PKCS#11 Standalone Library

5.4.1.4. Updating Greengrass configuration

If you have successfully completed Preparing the Greengrass group, you would have config.json under config directory of AWS IoT Greengrass core software (by default as /greengrass directory). A sample of config.json is:

{
  "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-ats.iot.region.amazonaws.com",
    "ggHost" : "greengrass-ats.iot.region.amazonaws.com",
    "keepAlive" : 600
  },
  "runtime" : {
    "cgroup" : {
      "useSystemd" : "yes"
    }
  },
  "managedRespawn" : false,
  "crypto" : {
    "principals" : {
      "SecretsManager" : {
        "privateKeyPath" : "file:///greengrass/certs/hash.private.key"
      },
      "IoTCertificate" : {
        "privateKeyPath" : "file:///greengrass/certs/hash.private.key",
        "certificatePath" : "file:///greengrass/certs/hash.cert.pem"
      }
    },
    "caPath" : "file:///greengrass/certs/root.ca.pem"
  }
}

Remove the caPath, certPath, and keyPath values from the coreThing object.

Update the certificatePath property of IoTCertificate object to the path of device certificate.

Note

Currently AWS IoT Greengrass core does not support loading certificates from hardware. These have to be provided as a path to a file on filesystem.

Update the values of privateKeyPath under SecretsManager and IoTCertificate objects with pkcs11:object=sss:01101820;type=private.

Add the following MQTTServerCertificate object under principals object:

"MQTTServerCertificate": {
    "privateKeyPath": "pkcs11:object=sss:01101820;type=private"
}

Add the following PKCS11 object under crypto object:

"PKCS11": {
    "P11Provider": "/path/to/libsss_pkcs11.so",
    "slotLabel": "SSS_PKCS11",
    "slotUserPin": "1234"
}

Add commas where needed to create a valid JSON document.

In this file, we have used a shared key for MQTTServerCertificate, IoTCertificate and SecretsManager components. In PKCS11 object, we specify which PKCS#11 module to load and which slot to use in that module. All PKCS#11 objects specified for different components will refer to the same token.

5.4.1.5. Running Greengrass Core

Start the Greengrass daemon by running the following command in ggc/core directory under AWS IoT Greengrass core software directory:

sudo ./greengrassd start

The Daemon should start successfully. If you face any problem while starting the Greengrass daemon, refer to Troubleshooting section below. Also see runtime logs under /greengrass/ggc/var/log/system directory.

5.4.1.6. Connecting Devices to Greengrass Core

Follow steps mentioned from Module 3 to test Greengrass connectivity: Lambda Functions on AWS IoT Greengrass

5.4.1.7. Over-The-Air (OTA) Updates

To configure your device for OTA updates, you also need additional PKCS#11 engine for OpenSSL. You can use OpenSC’s libp11 as the engine. It is recommended that you build the engine manually.

Run the following commands:

git clone https://github.com/OpenSC/libp11.git
cd libp11
sudo apt install pkgconf libssl-dev libtool
autoreconf --verbose --install --force
./configure && make && sudo make install

This will build the PKCS#11 engine for OpenSSL. Next, you have to specify the paths to the engine in your OpenSSL configuration file. Instead of editing default OpenSSL configuration file, you can maintain two separate files.

Place this line at the top, before any sections are defined:

openssl_conf = openssl_init

At the end of the file add the following configuration:

[openssl_init]
engines=engine_section

[engine_section]
pkcs11 = pkcs11_section

[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib/arm-linux-gnueabihf/engines-1.1/pkcs11.so
MODULE_PATH = /usr/local/lib/libsss_pkcs11.so
init = 0

Here, dynamic_path is the path to PKCS#11 engine .so file. This is installed in /usr/lib/arm-linux-gnueabihf/ directory. This path will also be printed out while installing libp11 library.

MODULE_PATH is the path to the PKCS#11 library installed in Section 8.7 PKCS#11 Standalone Library.

You can also test if OpenSSL is able to load the PKCS#11 library by executing the following command:

openssl engine dynamic -pre SO_PATH:/usr/lib/arm-linux-gnueabihf/engines-1.1/pkcs11.so -pre ID:pkcs11 -pre LOAD -pre MODULE_PATH:/usr/local/lib/libsss_pkcs11.so

You should be able to see the following output:

(dynamic) Dynamic engine loading support
[Success]: SO_PATH:/usr/lib/arm-linux-gnueabihf/engines-1.1/pkcs11.so
[Success]: ID:pkcs11
[Success]: LOAD
[Success]: MODULE_PATH:/usr/local/lib/libsss_pkcs11.so
Loaded: (pkcs11) pkcs11 engine

Follow the steps listed in OTA Updates of AWS IoT Greengrass Core Software to configure the backend for OTA updates.

5.4.1.8. Troubleshooting

  1. Error message greengrass deployment failed too many levels of symbolic links

    Check if your linux supports OverlayFS. Also confirm that the Raspberry Pi image version matches the version specified in Setting Up a Raspberry Pi. Currently, AWS IoT Greengrass Core has been tested on 2019-07-10-raspbian-buster image. Greengrass core might not work with other images like Raspbian Stretch.

  2. Error message connection reset by peer.

    Add properties iotHttpPort and ggHttpPort to coreThing object as:

    "iotHttpPort" : 443,
    "ggHttpPort" : 443
    

If you face any other issue, refer to Troubleshooting AWS IoT Greengrass.