demos/linux/sss_pkcs11/Readme.rst - a71ch-crypto-support - Git at Google

 ..
     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
	..
	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