Encryption options How Amazon IoT SiteWise uses a customer managed key Configuring encryption Key policy Creating a workspace with a customer managed key Scoping down access to the customer managed key Monitoring KMS usage with CloudTrail

Encryption at rest

Amazon IoT SiteWise encrypts all Scenario Discovery session data at rest. By default, Amazon IoT SiteWise uses an Amazon owned key to encrypt your data at no additional charge and with no administrative overhead. You can also choose to encrypt session data with a customer managed key for full control and auditability of the encryption key that protects your resources.

Encryption options

When you create a workspace, you choose one of the following encryption types:

SITEWISE_DEFAULT_ENCRYPTION – Amazon IoT SiteWise encrypts your session data using an Amazon owned key at no additional charge. No configuration is required.
KMS_BASED_ENCRYPTION – Amazon IoT SiteWise encrypts your session data using a customer managed key that you specify. You maintain full control over the key.

Important

The encryption configuration is set at workspace creation and cannot be changed after the workspace is created.

How Amazon IoT SiteWise uses a customer managed key

When you configure a workspace with a customer managed key, Amazon IoT SiteWise uses that key to encrypt the following data:

Video – All video streams captured and stored for the workspace.
Annotations – All annotation data associated with sessions in the workspace.
Telemetry – All telemetry data collected and stored for the workspace.

Amazon IoT SiteWise uses envelope encryption to protect your session data. During data ingestion, Amazon IoT SiteWise calls kms:GenerateDataKey scoped through source-context conditions (aws:SourceAccount and aws:SourceArn) to generate data encryption keys.

Amazon IoT SiteWise uses a KMS grant through FAS (Forward Access Session) to perform KMS operations on your behalf. The grant is scoped to the workspace and enables Amazon IoT SiteWise to call GenerateDataKey, Decrypt, and ReEncrypt operations. Amazon IoT SiteWise retires the grant when the associated workspace is deleted.

In addition, Amazon IoT SiteWise configures underlying Amazon managed data stores (such as Amazon S3 and Amazon OpenSearch Serverless) to use your customer managed key. This means that session data stored in these services is encrypted with your key, providing end-to-end encryption under your control. You might see CloudTrail events from these Amazon services using your KMS key – this is expected behavior.

Configuring encryption

When you create a workspace, specify the encryption configuration using the encryptionConfiguration parameter with the following fields:

encryptionType (required) – The type of encryption to use. Valid values are SITEWISE_DEFAULT_ENCRYPTION and KMS_BASED_ENCRYPTION.
kmsKeyId (required when encryptionType is KMS_BASED_ENCRYPTION) – The ID, ARN, alias name, or alias ARN of the customer managed key. The key must be a symmetric key with ENCRYPT_DECRYPT usage.

Key policy

To allow Amazon IoT SiteWise to use a customer managed key, the key policy must grant the necessary permissions. The following is a least-privilege key policy with six statements:


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowSiteWiseIngestionGenerateDataKey",
      "Effect": "Allow",
      "Principal": {
        "Service": "iotsitewise.amazonaws.com"
      },
      "Action": "kms:GenerateDataKey*",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "111122223333"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:iotsitewise:us-east-1:111122223333:workspace/*"
        }
      }
    },
    {
      "Sid": "AllowSiteWiseDecryptDescribeReEncrypt",
      "Effect": "Allow",
      "Principal": {
        "Service": "iotsitewise.amazonaws.com"
      },
      "Action": [
        "kms:Decrypt",
        "kms:DescribeKey",
        "kms:ReEncrypt*"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AllowSiteWiseToEncryptDataViaGrant",
      "Effect": "Allow",
      "Principal": {
        "Service": "iotsitewise.amazonaws.com"
      },
      "Action": "kms:CreateGrant",
      "Resource": "*",
      "Condition": {
        "ForAllValues:StringEquals": {
          "kms:GrantOperations": [
            "Decrypt",
            "GenerateDataKey",
            "ReEncrypt"
          ]
        }
      }
    },
    {
      "Sid": "AllowCustomerRoleDescribeKeyViaSiteWise",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/YourRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "iotsitewise.us-east-1.amazonaws.com"
        }
      }
    },
    {
      "Sid": "AllowCustomerRoleDecryptViaSiteWise",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/YourRole"
      },
      "Action": "kms:Decrypt",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "iotsitewise.us-east-1.amazonaws.com"
        },
        "StringLike": {
          "kms:EncryptionContext:aws:iotsitewise:subscriberId": "111122223333"
        }
      }
    },
    {
      "Sid": "AllowCustomerRoleCreateGrantViaSiteWise",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/YourRole"
      },
      "Action": "kms:CreateGrant",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "iotsitewise.us-east-1.amazonaws.com"
        },
        "StringLike": {
          "kms:EncryptionContext:aws:iotsitewise:subscriberId": "111122223333"
        },
        "ForAllValues:StringEquals": {
          "kms:GrantOperations": [
            "Decrypt",
            "GenerateDataKey",
            "ReEncrypt"
          ]
        }
      }
    }
  ]
}

Explanation of each policy statement

The following describes the purpose of each statement in the key policy:

AllowSiteWiseIngestionGenerateDataKey – Allows the Amazon IoT SiteWise service to call kms:GenerateDataKey* to create data encryption keys during data ingestion. The aws:SourceAccount and aws:SourceArn conditions scope access to your account and workspace, preventing the confused deputy problem.
AllowSiteWiseDecryptDescribeReEncrypt – Allows the Amazon IoT SiteWise service to call kms:Decrypt, kms:DescribeKey, and kms:ReEncrypt*. These operations do not carry the workspace source ARN in the request context, so source conditions are not applied to this statement.
AllowSiteWiseToEncryptDataViaGrant – Allows the Amazon IoT SiteWise service to call kms:CreateGrant to create a grant scoped to Decrypt, GenerateDataKey, and ReEncrypt operations. The kms:GrantOperations condition restricts the grant to only these operations.
AllowCustomerRoleDescribeKeyViaSiteWise – Allows your IAM role to call kms:DescribeKey through FAS. Amazon IoT SiteWise invokes this during workspace creation to validate that the key exists, is in ENABLED state, has KeySpec of SYMMETRIC_DEFAULT, and has KeyUsage of ENCRYPT_DECRYPT.
AllowCustomerRoleDecryptViaSiteWise – Allows your IAM role to call kms:Decrypt through FAS. Amazon IoT SiteWise uses this to verify that the calling principal has Decrypt permissions on the key. The kms:ViaService condition ensures this permission is only usable through Amazon IoT SiteWise, and the encryption context condition scopes access to your account.
AllowCustomerRoleCreateGrantViaSiteWise – Allows your IAM role to call kms:CreateGrant through FAS during workspace creation. Amazon IoT SiteWise uses this grant to invoke GenerateDataKey, Decrypt, and ReEncrypt operations for the lifetime of the workspace. The grant operations condition limits what the grant can authorize.

Creating a workspace with a customer managed key

To create a workspace with a customer managed key, specify the --encryption-configuration parameter in the CreateWorkspace API request:


aws iotsitewise create-workspace \
    --workspace-name my-workspace \
    --encryption-configuration encryptionType=KMS_BASED_ENCRYPTION,kmsKeyId=arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --region us-east-1

Scoping down access to the customer managed key

Encryption context

Amazon IoT SiteWise includes the following encryption context key-value pair in every Amazon KMS request:


"aws:iotsitewise:subscriberId": "<CustomerAccountId>"

You can use kms:EncryptionContext conditions in the key policy to further restrict which resources can use the key for encryption and decryption. The encryption context also appears in plaintext in Amazon CloudTrail logs. Each grant that Amazon IoT SiteWise creates includes an encryption context constraint, so the grant cannot be used to encrypt or decrypt data for another workspace or Amazon account.

Confused deputy protection

The aws:SourceArn and aws:SourceAccount conditions prevent the confused deputy problem by ensuring only your workspace can trigger key usage. These conditions apply to GenerateDataKey only. The Decrypt, DescribeKey, and ReEncrypt operations do not carry the workspace source ARN in the request context, so source conditions cannot be applied to those operations.

kms:ViaService condition

The kms:ViaService condition key restricts key usage to Forward Access Session requests that come from Amazon IoT SiteWise:


"kms:ViaService": "iotsitewise.us-east-1.amazonaws.com"

This ensures that the customer role permissions in the key policy are only usable when the request originates from Amazon IoT SiteWise, preventing direct use of the key outside the service context.

Monitoring KMS usage with CloudTrail

Amazon CloudTrail logs all KMS API calls made by Amazon IoT SiteWise and underlying Amazon services on your customer managed key. Use the CloudTrail console or the LookupEvents operation to search for log entries. The following are examples of CloudTrail events you can expect to see.

CreateGrant (Amazon OpenSearch Serverless)

Amazon OpenSearch Serverless creates a grant to use your customer managed key for encrypting indexed session data:


{
  "eventSource": "kms.amazonaws.com",
  "eventName": "CreateGrant",
  "userIdentity": {
    "type": "AWSService",
    "invokedBy": "aoss.amazonaws.com"
  },
  "requestParameters": {
    "granteePrincipal": "aoss.us-east-1.amazonaws.com",
    "keyId": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "constraints": {
      "encryptionContextSubset": {
        "aws:aoss:arn": "arn:aws:aoss:us-east-1:111122223333:collection/*"
      }
    },
    "retiringPrincipal": "aoss.us-east-1.amazonaws.com",
    "operations": ["Decrypt", "GenerateDataKey"]
  }
}

GenerateDataKey (Amazon S3)

Amazon S3 uses your customer managed key to encrypt stored video data:


{
  "eventSource": "kms.amazonaws.com",
  "eventName": "GenerateDataKey",
  "userIdentity": {
    "type": "AWSService",
    "invokedBy": "fas.s3.amazonaws.com"
  },
  "requestParameters": {
    "keyId": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "keySpec": "AES_256",
    "encryptionContext": {
      "aws:s3:arn": "arn:aws:s3:::iotsitewise-workspace-111122223333-us-east-1"
    }
  }
}

GenerateDataKey (Amazon IoT SiteWise)

Amazon IoT SiteWise generates data keys for internal encryption operations:


{
  "eventSource": "kms.amazonaws.com",
  "eventName": "GenerateDataKey",
  "userIdentity": {
    "type": "AWSService",
    "invokedBy": "AWS Internal"
  },
  "requestParameters": {
    "keyId": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "keySpec": "AES_256",
    "encryptionContext": {
      "aws:iotsitewise:subscriberId": "111122223333"
    }
  }
}

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Query language

Appendix: Workspace deletion