| .. |
| Copyright 2019 NXP |
| |
| |
| |
| .. _linux-demos-greengrass: |
| |
| ================================================== |
| 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 |
| |
| 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 :ref:`cli-tool` |
| |
| |
| .. _prepare-greengrass: |
| |
| 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. |
| |
| |
| #) 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 |
| |
| |
| #) If you used your own credentials, download sample :file:`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 :file:`/greengrass` directory) and the downloaded |
| :file:`config.json` under config directory. |
| |
| |
| #) Do **NOT** run the daemon yet. |
| |
| |
| 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. |
| |
| #) Complete :numref:`cli-doc-pre-steps` :ref:`cli-doc-pre-steps` for ssscli tool setup |
| |
| #) 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. For example, the label for the command used above would be |
| ``sss:20181001``. |
| |
| #) Build and install PKCS#11 library for Greengrass core. |
| Refer to :numref:`pkcs11-standalone` :ref:`pkcs11-standalone` |
| |
| |
| Updating Greengrass configuration |
| ================================================== |
| |
| If you have successfully completed :ref:`prepare-greengrass`, you would have |
| :file:`config.json` under config directory of AWS IoT Greengrass core software |
| (by default as :file:`/greengrass` directory). A sample of :file:`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:20181001;type=private*. |
| |
| Add the following ``MQTTServerCertificate`` object under ``principals`` object:: |
| |
| "MQTTServerCertificate": { |
| "privateKeyPath": "pkcs11:object=sss:20181001;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. |
| |
| |
| Running Greengrass Core |
| ================================================== |
| |
| Start the Greengrass daemon by running the following command in |
| :file:`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 :file:`/greengrass/ggc/var/log/system` directory. |
| |
| |
| Connecting Devices to Greengrass Core |
| ================================================== |
| |
| Follow steps mentioned from Module 3 to test Greengrass connectivity: |
| `Lambda Functions on AWS IoT Greengrass`_ |
| |
| |
| 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 :file:`/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 |
| :numref:`pkcs11-standalone` :ref:`pkcs11-standalone`. |
| |
| 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. |
| |
| |
| 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. |
| |
| #) 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`_. |
| |
| |
| |
| .. _OTA Updates of AWS IoT Greengrass Core Software: https://docs.aws.amazon.com/greengrass/latest/developerguide/core-ota-update.html |
| .. _Setting Up a Raspberry Pi: https://docs.aws.amazon.com/greengrass/latest/developerguide/setup-filter.rpi.html |
| .. _Troubleshooting AWS IoT Greengrass: https://docs.aws.amazon.com/greengrass/latest/developerguide/gg-troubleshooting.html |
| .. _Lambda Functions on AWS IoT Greengrass: https://docs.aws.amazon.com/greengrass/latest/developerguide/module3-I.html |
| .. _AWS IoT Greengrass Core Configuration File: https://docs.aws.amazon.com/greengrass/latest/developerguide/gg-core.html#config-json |
| .. _Environment Setup for Greengrass: https://docs.aws.amazon.com/greengrass/latest/developerguide/module1.html |
| .. _What Is AWS IoT Greengrass: https://docs.aws.amazon.com/greengrass/latest/developerguide/what-is-gg.html |