Greengrass local auth demo (#1831)

This PR adds a demo for connecting a device to a Greengrass core using the new feature that allows using custom CAs.

For more info on the feature, see:
https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-release-2022-11-15.html

Author: archigup

.github/workflows/ci.yml

@@ -39,7 +39,8 @@ jobs:
           -DCLAIM_PRIVATE_KEY_PATH="key/path" \
           -DPROVISIONING_TEMPLATE_NAME="template-name" \
           -DDEVICE_SERIAL_NUMBER="00000" \
-          -DCSR_SUBJECT_NAME="CN=Fleet Provisioning Demo"
+          -DCSR_SUBJECT_NAME="CN=Fleet Provisioning Demo" \
+          -DGREENGRASS_ADDRESS="greengrass-address"
       - name: Build Demos
         run: |
           make -C build/ help | grep demo | tr -d '. ' | xargs make -C build/
@@ -84,7 +85,8 @@ jobs:
           -DCLAIM_PRIVATE_KEY_PATH="key/path" \
           -DPROVISIONING_TEMPLATE_NAME="template-name" \
           -DDEVICE_SERIAL_NUMBER="00000" \
-          -DCSR_SUBJECT_NAME="CN=Fleet Provisioning Demo"
+          -DCSR_SUBJECT_NAME="CN=Fleet Provisioning Demo" \
+          -DGREENGRASS_ADDRESS="greengrass-address"
       - name: Build Demos
         run: |
           make -C build/ help | grep demo | tr -d '. ' | xargs make -C build/

README.md

@@ -50,6 +50,7 @@
         * [Configuring the AWS IoT Fleet Provisioning demo](#configuring-the-aws-iot-fleet-provisioning-demo)
         * [Configuring the S3 demos](#configuring-the-s3-demos)
         * [Setup for AWS IoT Jobs demo](#setup-for-aws-iot-jobs-demo)
+        * [Setup for the Greengrass local auth demo](#setup-for-the-greengrass-local-auth-demo)
         * [Prerequisites for the AWS Over-The-Air Update (OTA) demos](#prerequisites-for-the-aws-over-the-air-update-ota-demos)
         * [Scheduling an OTA Update Job](#scheduling-an-ota-update-job)
     * [Building and Running Demos](#building-and-running-demos)
@@ -491,6 +492,9 @@ The following creates a job that specifies a Linux Kernel link for downloading.
         --document '{"url":"https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.8.5.tar.xz"}'
 ```
 
+#### Setup for the Greengrass local auth demo
+
+For setting up the Greengrass local auth demo, see [the README in the demo folder](./demos/greengrass/greengrass_demo_local_auth/README.md).
 
 #### Prerequisites for the AWS Over-The-Air Update (OTA) demos
 

demos/CMakeLists.txt

@@ -48,6 +48,7 @@ if(NOT ${OpenSSL_FOUND})
             "ota_demo_core_http"
             "ota_demo_core_mqtt"
             "shadow_demo_main"
+            "greengrass_demo_local_auth"
     )
     message( WARNING "OpenSSL library could not be found. Demos that use it will be excluded from the default target." )
     foreach(demo_name ${openssl_demos})

demos/greengrass/greengrass_demo_local_auth/CMakeLists.txt

@@ -0,0 +1,47 @@
+set( DEMO_NAME "greengrass_demo_local_auth" )
+
+# Include MQTT library's source and header path variables.
+include( ${CMAKE_SOURCE_DIR}/libraries/standard/coreMQTT/mqttFilePaths.cmake )
+
+# Include backoffAlgorithm library file path configuration.
+include( ${CMAKE_SOURCE_DIR}/libraries/standard/backoffAlgorithm/backoffAlgorithmFilePaths.cmake )
+
+# CPP files are searched for supporting CI build checks that verify C++ linkage of the coreMQTT library
+file( GLOB DEMO_FILE "${DEMO_NAME}.c*" )
+
+# Demo target.
+add_executable(
+    ${DEMO_NAME}
+        "${DEMO_FILE}"
+        "openssl_posix.c"
+        ${MQTT_SOURCES}
+        ${MQTT_SERIALIZER_SOURCES}
+        ${BACKOFF_ALGORITHM_SOURCES}
+)
+
+find_package(OpenSSL)
+
+target_link_libraries(
+    ${DEMO_NAME}
+    PUBLIC
+        clock_posix
+        sockets_posix
+        ${OPENSSL_LIBRARIES}
+)
+
+target_include_directories(
+    ${DEMO_NAME}
+    PUBLIC
+        ${MQTT_INCLUDE_PUBLIC_DIRS}
+        ${BACKOFF_ALGORITHM_INCLUDE_PUBLIC_DIRS}
+        ${CMAKE_CURRENT_LIST_DIR}
+        ${LOGGING_INCLUDE_DIRS}
+)
+
+set_macro_definitions(TARGETS ${DEMO_NAME}
+                      REQUIRED
+                        "GREENGRASS_ADDRESS"
+                        "ROOT_CA_CERT_PATH"
+                        "THING_NAME"
+                        "CLIENT_CERT_PATH"
+                        "CLIENT_PRIVATE_KEY_PATH")

demos/greengrass/greengrass_demo_local_auth/README.md

@@ -0,0 +1,79 @@
+# Greengrass local auth demo
+
+This demo shows connecting a device using coreMQTT to a Greengrass core using
+local authentication. This feature is available since version [v2.9.0](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-release-2022-11-15.html)
+
+Connecting to a Greengrass core is similar to connecting to IoT core. The
+device's Thing will need to be registered on IoT core just as with connecting
+directly. When setting up the Greengrass core, use your own Root CA, and
+provision the connecting device with the Root CA used for the Greengrass core.
+
+To read more about using Greengrass with custom CAs, see the docs on
+[offline authentication](https://docs.aws.amazon.com/greengrass/v2/developerguide/offline-authentication.html).
+
+This demo uses macros in demo_config.h for provisioned data; the following need
+to be set:
+
+- `GREENGRASS_ADDRESS`
+  - Set this to the IP of the Greengrass core.
+- `ROOT_CA_CERT_PATH`
+  - Set this to the path to the CA certificate for the Greengrass core custom
+    CA.
+- `CLIENT_CERT_PATH`
+  - Set this to the client cert downloaded from IoT core when setting up the
+    Thing.
+- `CLIENT_PRIVATE_KEY_PATH`
+  - Set this to the client private key downloaded from IoT core when setting up
+    the Thing.
+- `THING_NAME`
+  - Set this to the Thing name configured in IoT core.
+
+These macros can also be set on the cmake command like follows:
+
+```sh
+cmake -S . -Bbuild -DGREENGRASS_ADDRESS="<your-gg-core-ip>" -DROOT_CA_CERT_PATH="<your-path-to-custom-root-ca>" -DCLIENT_CERT_PATH="<your-client-certificate-path>" -DCLIENT_PRIVATE_KEY_PATH="<your-client-private-key-path>" -DTHING_NAME="<your-registered-thing-name>"
+```
+
+## Setting up the prerequisites
+
+### Creating the Thing
+
+See the [Getting Started section of the README](../../../README.md#getting-started)
+for setting up this repo and your AWS IoT account. Use the Thing credentials
+generated for the above macros.
+
+### Setting up a Greengrass Core
+
+For setting up the Greengrass core, see [the Greengrass getting started guide](https://docs.aws.amazon.com/greengrass/v2/developerguide/getting-started.html)
+
+### Creating a custom CA
+
+Next you will need to set up a Root CA for your Greengrass device.
+
+On the Greengrass core, run the following command:
+
+```sh
+openssl req -x509 -new -nodes -key ca.key -sha256 -days 1826 -out ca.crt
+```
+
+This will create a custom CA cert ca.crt and private key ca.key.
+
+### Configuring the GG core for local auth and MQTT
+
+Deploy the following components to your Greengrass core:
+- aws.greengrass.clientdevices.Auth
+- aws.greengrass.clientdevices.mqtt.Moquette
+- aws.greengrass.clientdevices.mqtt.Bridge
+- aws.greengrass.clientdevices.IPDetector
+
+Set the configuration for the aws.greengrass.clientdevices.Auth component based
+off the [provided config](./greengrass_auth_conf.json). Ensure the certificate
+paths match the files created for your custom CA above.
+
+This config will allow associated Things to publish and subscribe to any topic
+on the Greengrass core broker.
+
+In the page for the Greengrass core in your AWS account, ensure that you
+associate your Thing with the Greengrass core under the Cloud Discovery tab.
+
+Afterwards, you can configure and run this demo.

demos/greengrass/greengrass_demo_local_auth/core_mqtt_config.h

@@ -0,0 +1,63 @@
+/*
+ * AWS IoT Device SDK for Embedded C 202108.00
+ * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#ifndef CORE_MQTT_CONFIG_H_
+#define CORE_MQTT_CONFIG_H_
+
+/* Configure name and log level for the MQTT library. */
+#ifndef LIBRARY_LOG_NAME
+    #define LIBRARY_LOG_NAME     "MQTT"
+#endif
+#ifndef LIBRARY_LOG_LEVEL
+    #define LIBRARY_LOG_LEVEL    LOG_INFO
+#endif
+
+#include "logging_stack.h"
+
+/**
+ * @brief Determines the maximum number of MQTT PUBLISH messages, pending
+ * acknowledgement at a time, that are supported for incoming and outgoing
+ * direction of messages, separately.
+ *
+ * QoS 1 and 2 MQTT PUBLISHes require acknowledgement from the server before
+ * they can be completed. While they are awaiting the acknowledgement, the
+ * client must maintain information about their state. The value of this
+ * macro sets the limit on how many simultaneous PUBLISH states an MQTT
+ * context maintains, separately, for both incoming and outgoing direction of
+ * PUBLISHes.
+ *
+ * @note The MQTT context maintains separate state records for outgoing
+ * and incoming PUBLISHes, and thus, 2 * MQTT_STATE_ARRAY_MAX_COUNT amount
+ * of memory is statically allocated for the state records.
+ */
+#define MQTT_STATE_ARRAY_MAX_COUNT    ( 10U )
+
+/**
+ * @brief Number of milliseconds to wait for a ping response to a ping
+ * request as part of the keep-alive mechanism.
+ *
+ * If a ping response is not received before this timeout, then
+ * #MQTT_ProcessLoop will return #MQTTKeepAliveTimeout.
+ */
+#define MQTT_PINGRESP_TIMEOUT_MS      ( 5000U )
+
+#endif /* ifndef CORE_MQTT_CONFIG_H_ */

demos/greengrass/greengrass_demo_local_auth/demo_config.h

@@ -0,0 +1,79 @@
+/*
+ * AWS IoT Device SDK for Embedded C 202108.00
+ * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#ifndef DEMO_CONFIG_H_
+#define DEMO_CONFIG_H_
+
+/**
+ * @brief IP or hostname of the Greengrass core.
+ *
+ * #define GREENGRASS_ADDRESS     "...insert here..."
+ */
+
+/**
+ * @brief Greengrass MQTT broker port number.
+ */
+#ifndef MQTT_PORT
+    #define MQTT_PORT    ( 8883 )
+#endif
+
+/**
+ * @brief Path of the file containing the Greengrass core's root CA certificate.
+ *
+ * @note This certificate should be PEM-encoded.
+ *
+ * #define ROOT_CA_CERT_PATH    "...insert here..."
+ */
+
+/**
+ * @brief Path of the file containing the client certificate.
+ *
+ * Refer to the AWS documentation below for details regarding client
+ * authentication.
+ * https://docs.aws.amazon.com/iot/latest/developerguide/client-authentication.html
+ *
+ * @note This certificate should be PEM-encoded.
+ *
+ * #define CLIENT_CERT_PATH    "...insert here..."
+ */
+
+/**
+ * @brief Path of the file containing the client's private key.
+ *
+ * Refer to the AWS documentation below for details regarding client
+ * authentication.
+ * https://docs.aws.amazon.com/iot/latest/developerguide/client-authentication.html
+ *
+ * @note This private key should be PEM-encoded.
+ *
+ * #define CLIENT_PRIVATE_KEY_PATH    "...insert here..."
+ */
+
+/**
+ * @brief Device Thing name.
+ *
+ * This should the Thing name created on IoT core with the above certificate.
+ *
+ * #define THING_NAME    "...insert here..."
+ */
+
+#endif /* ifndef DEMO_CONFIG_H_ */

demos/greengrass/greengrass_demo_local_auth/greengrass_auth_conf.json

@@ -0,0 +1,46 @@
+{
+	"certificateAuthority": {
+		"privateKeyUri": "file:///home/user/ca.key",
+		"certificateUri": "file:///home/user/ca.crt"
+	},
+	"deviceGroups": {
+		"formatVersion": "2021-03-05",
+		"definitions": {
+			"MyDeviceGroup": {
+				"selectionRule": "thingName: *",
+				"policyName": "DemoClientDevicePolicy"
+			}
+		},
+		"policies": {
+			"DemoClientDevicePolicy": {
+				"AllowConnect": {
+					"statementDescription": "Allow client devices to connect.",
+					"operations": [
+						"mqtt:connect"
+					],
+					"resources": [
+						"*"
+					]
+				},
+				"AllowPublish": {
+					"statementDescription": "Allow client devices to publish to all topics.",
+					"operations": [
+						"mqtt:publish"
+					],
+					"resources": [
+						"*"
+					]
+				},
+				"AllowSubscribe": {
+					"statementDescription": "Allow client devices to subscribe to all topics.",
+					"operations": [
+						"mqtt:subscribe"
+					],
+					"resources": [
+						"*"
+					]
+				}
+			}
+		}
+	}
+}