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 OpenSearch Service custom package Amazon KMS integration

Amazon OpenSearch Service custom packages provide encryption by default to protect your ZIP-PLUGIN packages at rest using Amazon managed keys.

For more information, see Customer managed keys in the Amazon Key Management Service Developer Guide.

How Amazon OpenSearch Service custom packages service uses grants in Amazon KMS

OpenSearch Service custom packages require a grant to use your customer managed key.

When you create a ZIP-PLUGIN package encrypted with a customer managed key, the Amazon OpenSearch Service custom packages service creates a grant on your behalf by sending a CreateGrant request to Amazon KMS. Grants in Amazon KMS give OpenSearch Service access to a Amazon KMS key in your account. The grants created by OpenSearch Service custom packages have a constraint that allows operations only when the request includes an encryption context with your custom package ID.

Amazon OpenSearch Service custom packages require the grant to use your customer managed key for the following internal operations:

You can revoke access to the grant or remove the service's access to the customer managed key at any time. If you do, OpenSearch Service won't be able to access any data encrypted by the customer managed key, which affects operations that depend on that data. For example, if you attempt to associate a plugin package that OpenSearch Service can't access, the operation returns an AccessDeniedException error.

Create a customer managed key

You can create a symmetric customer managed key by using the Amazon Web Services Management Console or the Amazon KMS APIs.

Key policy

Key policies control access to your customer managed key. Every customer managed key must have exactly one key policy, which contains statements that determine who can use the key and how they can use it. When you create your customer managed key, you can specify a key policy. For more information, see Key policies in Amazon KMS in the Amazon Key Management Service Developer Guide.

To use your customer managed key with your plugin resources, you must permit the following API operations in the key policy:

The following are policy statement examples you can add for OpenSearch Service custom packages:

"Statement" : [
  {
    "Sid" : "Allow access to principals authorized to use OpenSearch Service custom packages",
    "Effect" : "Allow",
    "Principal" : {
      "AWS" : "*"
    },
    "Action" : [
      "kms:CreateGrant",
      "kms:GenerateDataKey",
      "kms:GenerateDataKeyWithoutPlaintext",
      "kms:Decrypt"
    ],
    "Resource" : "*",
    "Condition" : {
      "StringEquals" : {
        "kms:ViaService" : "custom-packages.region.amazonaws.com"
      },
      "StringEquals" : {
        "kms:EncryptionContext:packageId": "Id of the package"
      }
    }
  },
  {
    "Sid" : "Allow access to principals authorized to use Amazon OpenSearch Service custom packages",
    "Effect" : "Allow",
    "Principal" : {
      "AWS" : "*"
    },
    "Action" : [
      "kms:DescribeKey"
    ],
    "Resource" : "*",
    "Condition" : {
      "StringEquals" : {
        "kms:ViaService" : "custom-packages.region.amazonaws.com"
      }
    }
  }
]
      

For more information about specifying permissions in a policy, see Key policies in Amazon KMS in the Amazon Key Management Service Developer Guide.

For more information about troubleshooting key access, see Troubleshooting Amazon KMS permissions in the Amazon Key Management Service Developer Guide.

Specify a customer managed key for Amazon OpenSearch Service custom packages

You can specify a customer managed key as a second layer of encryption for your ZIP-PLUGIN packages.

When you create a plugin package, you can specify the data key by entering a Amazon KMS key ID, which OpenSearch Service custom packages use to encrypt the plugin package.

Amazon KMS key ID — A key identifier for a Amazon KMS customer managed key. Enter a key ID, key ARN, alias name, or alias ARN.

Amazon OpenSearch Service custom packages encryption context

An encryption context is an optional set of key-value pairs that contain additional contextual information about the data.

Amazon KMS uses the encryption context as additional authenticated data to support authenticated encryption. When you include an encryption context in a request to encrypt data, Amazon KMS binds the encryption context to the encrypted data. To decrypt data, you include the same encryption context in the request.

Amazon OpenSearch Service custom packages encryption context

Amazon OpenSearch Service custom packages use the same encryption context in all Amazon KMS cryptographic operations, where the key is packageId and the value is the package-id of your plugin package.

Use encryption context for monitoring

When you use a symmetric customer managed key to encrypt your plugin package, you can use the encryption context in audit records and logs to identify how the customer managed key is being used. The encryption context also appears in logs generated by Amazon CloudTrail or Amazon CloudWatch Logs.

Using encryption context to control access to your customer managed key

You can use the encryption context in key policies and IAM policies as conditions to control access to your symmetric customer managed key. You can also use encryption context constraints in a grant.

OpenSearch Service custom packages use an encryption context constraint in grants to control access to the customer managed key in your account or Region. The grant constraint requires that the operations that the grant allows use the specified encryption context.

The following are example key policy statements to grant access to a customer managed key for a specific encryption context. The condition in this policy statement requires that the grants have an encryption context constraint that specifies the encryption context.

{
    "Sid": "Enable DescribeKey",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExampleReadOnlyRole"
    },
    "Action": "kms:DescribeKey",
    "Resource": "*"
},
{
    "Sid": "Enable OpenSearch Service custom packages to use the key",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExampleReadOnlyRole"
    },
    "Action" : [
         "kms:CreateGrant",
        "kms:GenerateDataKey",
        "kms:GenerateDataKeyWithoutPlaintext",
        "kms:Decrypt"
    ],
    "Resource": "*",
    "Condition": {
        "StringEquals" : {
            "kms:EncryptionContext:packageId": "ID of the package"
         }
    }
}
      

Monitoring your encryption keys for OpenSearch custom packages service

When you use an Amazon KMS customer managed key with your OpenSearch Service custom packages service resources, you can use CloudTrail or CloudWatch Logs to track requests that OpenSearch custom packages send to Amazon KMS.

Learn more

The following resources provide more information about data encryption at rest.