Overview of Amazon IoT Greengrass security - Amazon IoT Greengrass
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. After this date, Amazon IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on Amazon 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 Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

Overview of Amazon IoT Greengrass security

Amazon IoT Greengrass uses X.509 certificates, Amazon IoT policies, and IAM policies and roles to secure the applications that run on devices in your local Greengrass environment.

The following diagram shows the components of the Amazon IoT Greengrass security model:

A - Greengrass service role

A customer-created IAM role assumed by Amazon IoT Greengrass when accessing to your Amazon resources from Amazon IoT Core, Amazon Lambda, and other Amazon services. For more information, see Greengrass service role.

B - Core device certificate

An X.509 certificate used to authenticate a Greengrass core with Amazon IoT Core and Amazon IoT Greengrass. For more information, see Device authentication and authorization for Amazon IoT Greengrass.

C - Device certificate

An X.509 certificate used to authenticate a client device, which is also known as a connected device, with Amazon IoT Core and Amazon IoT Greengrass. For more information, see Device authentication and authorization for Amazon IoT Greengrass.

D - Group role

A customer-created IAM role assumed by Amazon IoT Greengrass when calling Amazon services from a Greengrass core.

You use this role to specify access permissions that your user-defined Lambda functions and connectors need to access Amazon services, such as DynamoDB. You also use it to allow Amazon IoT Greengrass to export stream manager streams to Amazon services and write to CloudWatch Logs. For more information, see Greengrass group role.

Note

Amazon IoT Greengrass doesn't use the Lambda execution role that's specified in Amazon Lambda for the cloud version of a Lambda function.

E - MQTT server certificate

The certificate used for Transport Layer Security (TLS) mutual authentication between a Greengrass core device and client devices in the Greengrass group. The certificate is signed by the group CA certificate, which is stored in the Amazon Web Services Cloud.

Device connection workflow

This section describes how client devices connect to the Amazon IoT Greengrass service and Greengrass core devices. Client devices are registered Amazon IoT Core devices that are in the same Greengrass group as the core device.

  • A Greengrass core device uses its device certificate, private key, and the Amazon IoT Core root CA certificate to connect to the Amazon IoT Greengrass service. On the core device, the crypto object in the configuration file specifies the file path for these items.

  • The Greengrass core device downloads group membership information from the Amazon IoT Greengrass service.

  • When a deployment is made to the Greengrass core device, the Device Certificate Manager (DCM) handles local server certificate management for the Greengrass core device.

  • A client device connects to the Amazon IoT Greengrass service using its device certificate, private key, and the Amazon IoT Core root CA certificate. After making the connection, the client device uses the Greengrass Discovery Service to find the IP address of its Greengrass core device. The client device also downloads the group CA certificate, which is used for TLS mutual authentication with the Greengrass core device.

  • A client device attempts to connect to the Greengrass core device, passing its device certificate and client ID. If the client ID matches the thing name of the client device and the certificate is valid (part of the Greengrass group), the connection is made. Otherwise, the connection is terminated.

The Amazon IoT policy for client devices must grant the greengrass:Discover permission to allow client devices to discover connectivity information for the core. For more information about the policy statement, see Discovery authorization.

Configuring Amazon IoT Greengrass security

To configure your Greengrass application's security
  1. Create an Amazon IoT Core thing for your Greengrass core device.

  2. Generate a key pair and device certificate for your Greengrass core device.

  3. Create and attach an Amazon IoT policy to the device certificate. The certificate and policy allow the Greengrass core device access to Amazon IoT Core and Amazon IoT Greengrass services. For more information, see Minimal Amazon IoT policy for the core device.

    Note

    The use of thing policy variables (iot:Connection.Thing.*) in the Amazon IoT policy for a core device is not supported. The core uses the same device certificate to make multiple connections to Amazon IoT Core but the client ID in a connection might not be an exact match of the core thing name.

  4. Create a Greengrass service role. This IAM role authorizes Amazon IoT Greengrass to access resources from other Amazon services on your behalf. This allows Amazon IoT Greengrass to perform essential tasks, such as retrieving Amazon Lambda functions and managing device shadows.

    You can use the same service role across Amazon Web Services Regions, but it must be associated with your Amazon Web Services account in every Amazon Web Services Region where you use Amazon IoT Greengrass.

  5. (Optional) Create a Greengrass group role. This IAM role grants permission to Lambda functions and connectors running on a Greengrass core to call Amazon services. For example, the Kinesis Firehose connector requires permission to write records to an Amazon Data Firehose delivery stream.

    You can attach only one role to a Greengrass group.

  6. Create an Amazon IoT Core thing for each device that connects to your Greengrass core.

    Note

    You can also use existing Amazon IoT Core things and certificates.

  7. Create device certificates, key pairs, and Amazon IoT policies for each device that connects to your Greengrass core.

Amazon IoT Greengrass core security principals

The Greengrass core uses the following security principals: Amazon IoT client, local MQTT server, and local secrets manager. The configuration for these principals is stored in the crypto object in the config.json configuration file. For more information, see Amazon IoT Greengrass core configuration file.

This configuration includes the path to the private key used by the principal component for authentication and encryption. Amazon IoT Greengrass supports two modes of private key storage: hardware-based or file system-based (default). For more information about storing keys on hardware security modules, see Hardware security integration.

Amazon IoT Client

The Amazon IoT client (IoT client) manages communication over the internet between the Greengrass core and Amazon IoT Core. Amazon IoT Greengrass uses X.509 certificates with public and private keys for mutual authentication when establishing TLS connections for this communication. For more information, see X.509 certificates and Amazon IoT Core in the Amazon IoT Core Developer Guide.

The IoT client supports RSA and EC certificates and keys. The certificate and private key path are specified for the IoTCertificate principal in config.json.

MQTT Server

The local MQTT server manages communication over the local network between the Greengrass core and client devices in the group. Amazon IoT Greengrass uses X.509 certificates with public and private keys for mutual authentication when establishing TLS connections for this communication.

By default, Amazon IoT Greengrass generates an RSA private key for you. To configure the core to use a different private key, you must provide the key path for the MQTTServerCertificate principal in config.json. You are responsible for rotating a customer-provided key.

Private key support
RSA key EC key
Key type Supported Supported
Key parameters Minimum 2048-bit length NIST P-256 or NIST P-384 curve
Disk format PKCS#1, PKCS#8 SECG1, PKCS#8
Minimum GGC version
  • Use default RSA key: 1.0

  • Specify an RSA key: 1.7

  • Specify an EC key: 1.9

The configuration of the private key determines related processes. For the list of cipher suites that the Greengrass core supports as a server, see TLS cipher suites support.

If no private key is specified (default)
  • Amazon IoT Greengrass rotates the key based on your rotation settings.

  • The core generates an RSA key, which is used to generate the certificate.

  • The MQTT server certificate has an RSA public key and an SHA-256 RSA signature.

If an RSA private key is specified (requires GGC v1.7 or later)
  • You are responsible for rotating the key.

  • The core uses the specified key to generate the certificate.

  • The RSA key must have a minimum length of 2048 bits.

  • The MQTT server certificate has an RSA public key and an SHA-256 RSA signature.

If an EC private key is specified (requires GGC v1.9 or later)
  • You are responsible for rotating the key.

  • The core uses the specified key to generate the certificate.

  • The EC private key must use an NIST P-256 or NIST P-384 curve.

  • The MQTT server certificate has an EC public key and an SHA-256 RSA signature.

    The MQTT server certificate presented by the core has an SHA-256 RSA signature, regardless of the key type. For this reason, clients must support SHA-256 RSA certificate validation to establish a secure connection with the core.

Secrets Manager

The local secrets manager securely manages local copies of secrets that you create in Amazon Secrets Manager. It uses a private key to secure the data key that's used to encrypt the secrets. For more information, see Deploy secrets to the Amazon IoT Greengrass core.

By default, the IoT client private key is used, but you can specify a different private key for the SecretsManager principal in config.json. Only the RSA key type is supported. For more information, see Specify the private key for secret encryption.

Note

Currently, Amazon IoT Greengrass supports only the PKCS#1 v1.5 padding mechanism for encryption and decryption of local secrets when using hardware-based private keys. If you're following vendor-provided instructions to manually generate hardware-based private keys, make sure to choose PKCS#1 v1.5. Amazon IoT Greengrass doesn't support Optimal Asymmetric Encryption Padding (OAEP).

Private key support
RSA key EC key
Key type Supported Not supported
Key parameters Minimum 2048-bit length Not applicable
Disk format PKCS#1, PKCS#8 Not applicable
Minimum GGC version 1.7 Not applicable

Managed subscriptions in the MQTT messaging workflow

Amazon IoT Greengrass uses a subscription table to define how MQTT messages can be exchanged between client devices, functions, and connectors in a Greengrass group, and with Amazon IoT Core or the local shadow service. Each subscription specifies a source, target, and MQTT topic (or subject) over which messages are sent or received. Amazon IoT Greengrass allows messages to be sent from a source to a target only if a corresponding subscription is defined.

A subscription defines the message flow in one direction only, from the source to the target. To support two-way message exchange, you must create two subscriptions, one for each direction.

TLS cipher suites support

Amazon IoT Greengrass uses the Amazon IoT Core transport security model to encrypt communication with the cloud by using TLS cipher suites. In addition, Amazon IoT Greengrass data is encrypted when at rest (in the cloud). For more information about Amazon IoT Core transport security and supported cipher suites, see Transport security in the Amazon IoT Core Developer Guide.

Supported Cipher Suites for Local Network Communication

As opposed to Amazon IoT Core, the Amazon IoT Greengrass core supports the following local network TLS cipher suites for certificate-signing algorithms. All of these cipher suites are supported when private keys are stored on the file system. A subset are supported when the core is configured to use hardware security modules (HSM). For more information, see Amazon IoT Greengrass core security principals and Hardware security integration. The table also includes the minimum version of Amazon IoT Greengrass Core software required for support.

Cipher HSM support Minimum GGC version
TLSv1.2 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA Supported 1.0
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA Supported 1.0
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 Supported 1.0
TLS_RSA_WITH_AES_128_CBC_SHA Not supported 1.0
TLS_RSA_WITH_AES_128_GCM_SHA256 Not supported 1.0
TLS_RSA_WITH_AES_256_CBC_SHA Not supported 1.0
TLS_RSA_WITH_AES_256_GCM_SHA384 Not supported 1.0
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 Supported 1.9
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 Supported 1.9
TLSv1.1 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA Supported 1.0
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA Supported 1.0
TLS_RSA_WITH_AES_128_CBC_SHA Not supported 1.0
TLS_RSA_WITH_AES_256_CBC_SHA Not supported 1.0
TLSv1.0 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA Supported 1.0
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA Supported 1.0
TLS_RSA_WITH_AES_128_CBC_SHA Not supported 1.0
TLS_RSA_WITH_AES_256_CBC_SHA Not supported 1.0