Deploy secrets to the Amazon IoT Greengrass core - Amazon IoT Greengrass
Secrets encryptionRequirementsSpecify the private key for secret encryptionAllow Amazon IoT Greengrass to get secret valuesSee also
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.

Deploy secrets to the Amazon IoT Greengrass core

This feature is available for Amazon IoT Greengrass Core v1.7 and later.

Amazon IoT Greengrass lets you authenticate with services and applications from Greengrass devices without hard-coding passwords, tokens, or other secrets.

Amazon Secrets Manager is a service that you can use to securely store and manage your secrets in the cloud. Amazon IoT Greengrass extends Secrets Manager to Greengrass core devices, so your connectors and Lambda functions can use local secrets to interact with services and applications. For example, the Twilio Notifications connector uses a locally stored authentication token.

To integrate a secret into a Greengrass group, you create a group resource that references the Secrets Manager secret. This secret resource references the cloud secret by ARN. To learn how to create, manage, and use secret resources, see Working with secret resources.

Amazon IoT Greengrass encrypts your secrets while in transit and at rest. During group deployment, Amazon IoT Greengrass fetches the secret from Secrets Manager and creates a local, encrypted copy on the Greengrass core. After you rotate your cloud secrets in Secrets Manager, redeploy the group to propagate the updated values to the core.

The following diagram shows the high-level process of deploying a secret to the core. Secrets are encrypted in transit and at rest.

Amazon IoT Greengrass fetches a secret from Amazon Secrets Manager and deploys it as a secret resource to the core device, where it is available to connectors and Lambda functions.

Using Amazon IoT Greengrass to store your secrets locally offers these advantages:

  • Decoupled from code (not hard-coded). This supports centrally managed credentials and helps protect sensitive data from the risk of compromise.

  • Available for offline scenarios. Connectors and functions can securely access local services and software when disconnected from the internet.

  • Controlled access to secrets. Only authorized connectors and functions in the group can access your secrets. Amazon IoT Greengrass uses private key encryption to secure your secrets. Secrets are encrypted in transit and at rest. For more information, see Secrets encryption.

  • Controlled rotation. After you rotate your secrets in Secrets Manager, redeploy the Greengrass group to update the local copies of your secrets. For more information, see Creating and managing secrets.

    Important

    Amazon IoT Greengrass doesn't automatically update the values of local secrets after cloud versions are rotated. To update local values, you must redeploy the group.

Secrets encryption

Amazon IoT Greengrass encrypts secrets in transit and at rest.

Important

Make sure that your user-defined Lambda functions handle secrets securely and don't log any any sensitive data that's stored in the secret. For more information, see Mitigate the Risks of Logging and Debugging Your Lambda Function in the Amazon Secrets Manager User Guide. Although this documentation specifically refers to rotation functions, the recommendation also applies to Greengrass Lambda functions.

Encryption in transit

Amazon IoT Greengrass uses Transport Layer Security (TLS) to encrypt all communication over the internet and local network. This protects secrets while in transit, which occurs when secrets are retrieved from Secrets Manager and deployed to the core. For supported TLS cipher suites, see TLS cipher suites support.

Encryption at rest

Amazon IoT Greengrass uses the private key specified in config.json for encryption of the secrets that are stored on the core. For this reason, secure storage of the private key is critical for protecting local secrets. In the Amazon shared responsibility model, it's the responsibility of the customer to guarantee secure storage of the private key on the core device.

Amazon IoT Greengrass supports two modes of private key storage:

  • Using hardware security modules. For more information, see Hardware security integration.

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

  • Using file system permissions (default).

The private key is used to secure the data key, which is used to encrypt local secrets. The data key is rotated with each group deployment.

The Amazon IoT Greengrass core is the only entity that has access to the private key. Greengrass connectors or Lambda functions that are affiliated with a secret resource get the value of the secret from the core.

Requirements

These are the requirements for local secret support:

  • You must be using Amazon IoT Greengrass Core v1.7 or later.

  • To get the values of local secrets, your user-defined Lambda functions must use Amazon IoT Greengrass Core SDK v1.3.0 or later.

  • The private key used for local secrets encryption must be specified in the Greengrass configuration file. By default, Amazon IoT Greengrass uses the core private key stored in the file system. To provide your own private key, see Specify the private key for secret encryption. Only the RSA key type is supported.

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

  • Amazon IoT Greengrass must be granted permission to get your secret values. This allows Amazon IoT Greengrass to fetch the values during group deployment. If you're using the default Greengrass service role, then Amazon IoT Greengrass already has access to secrets with names that start with greengrass-. To customize access, see Allow Amazon IoT Greengrass to get secret values.

    Note

    We recommend that you use this naming convention to identify the secrets that Amazon IoT Greengrass is allowed to access, even if you customize permissions. The console uses different permissions to read your secrets, so it's possible that you can select secrets in the console that Amazon IoT Greengrass doesn't have permission to fetch. Using a naming convention can help avoid a permission conflict, which results in a deployment error.

Specify the private key for secret encryption

In this procedure, you provide the path to a private key that's used for local secret encryption. This must be an RSA key with a minimum length of 2048 bits. For more information about private keys used on the Amazon IoT Greengrass core, see Amazon IoT Greengrass core security principals.

Amazon IoT Greengrass supports two modes of private key storage: hardware-based or file system-based (default). For more information, see Secrets encryption.

Follow this procedure only if you want to change the default configuration, which uses the core private key in the file system. These steps are written with the assumption that you created your group and core as described in Module 2 of the Getting Started tutorial.

  1. Open the config.json file that's located in the /greengrass-root/config directory.

    Note

    greengrass-root represents the path where the Amazon IoT Greengrass Core software is installed on your device. Typically, this is the /greengrass directory.

  2. In the crypto.principals.SecretsManager object, for the privateKeyPath property, enter the path of the private key:

    • If your private key is stored in the file system, specify the absolute path to the key. For example:

      "SecretsManager" : {
  "privateKeyPath" : "file:///somepath/hash.private.key"
}

    • If your private key is stored in a hardware security module (HSM), specify the path using the RFC 7512 PKCS#11 URI scheme. For example:

      "SecretsManager" : {
  "privateKeyPath" : "pkcs11:object=private-key-label;type=private"
}

      For more information, see Hardware security configuration for an Amazon IoT Greengrass core.

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

Allow Amazon IoT Greengrass to get secret values

In this procedure, you add an inline policy to the Greengrass service role that allows Amazon IoT Greengrass to get the values of your secrets.

Follow this procedure only if you want to grant Amazon IoT Greengrass custom permissions to your secrets or if your Greengrass service role doesn't include the AWSGreengrassResourceAccessRolePolicy managed policy. AWSGreengrassResourceAccessRolePolicy grants access to secrets with names that start with greengrass-.

  1. Run the following CLI command to get the ARN of the Greengrass service role:

    aws greengrass get-service-role-for-account --region region

    The returned ARN contains the role name.

    {
  "AssociatedAt": "time-stamp",
  "RoleArn": "arn:aws-cn:iam::account-id:role/service-role/role-name"
}

    You use the ARN or name in the following step.

  2. Add an inline policy that allows the secretsmanager:GetSecretValue action. For instructions, see Adding and removing IAM policies in the IAM User Guide.

    You can grant granular access by explicitly listing secrets or using a wildcard * naming scheme, or you can grant conditional access to versioned or tagged secrets. For example, the following policy allows Amazon IoT Greengrass to read only the specified secrets.

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": [
                "arn:aws-cn:secretsmanager:region:account-id:secret:greengrass-SecretA-abc",
                "arn:aws-cn:secretsmanager:region:account-id:secret:greengrass-SecretB-xyz"
            ]
        }
    ]
}
    Note

    If you use a customer-managed Amazon KMS key to encrypt secrets, your Greengrass service role must also allow the kms:Decrypt action.

For more information about IAM policies for Secrets Manager, see Authentication and access control for Amazon Secrets Manager and Actions, resources, and context keys you can use in an IAM policy or secret policy for Amazon Secrets Manager in the Amazon Secrets Manager User Guide.

See also