View a markdown version of this page

組態套件加密 - Amazon Bedrock AgentCore
運作方式監控組態套件的 KMS 用量當金鑰無法使用時的行為

組態套件加密

當您在組態套件kmsKeyArn上指定 時，服務會使用信封加密來加密元件組態 （系統提示、工具描述和其他組態內容）。所有其他套件中繼資料 （名稱、描述、版本 IDs、時間戳記） 都會使用 AWS 擁有的金鑰進行加密。

運作方式

組態套件加密使用信封加密搭配呼叫者登入資料。當您使用 建立或更新套件時kmsKeyArn，服務會使用 登入資料 （透過轉送存取工作階段) 從 KMS 產生資料加密金鑰 (DEK)。服務會使用 AES-GCM 搭配該 DEK 在本機加密元件組態，然後將加密的 DEK 與套件一起存放。當您擷取套件時，服務會使用登入資料解密 DEK，並解密元件。

發起人必須擁有金鑰的 kms:GenerateDataKey、kms:DescribeKey、 kms:Decrypt和 kms:ReEncrypt*許可。

AgentCore 最佳化僅支援對稱加密 KMS 金鑰。KMS 金鑰必須與組態套件位於相同的 AWS 區域。

設定使用客戶受管 KMS 金鑰的許可

下列金鑰政策提供組態套件加密所需的最低許可。此政策具有兩個陳述式：

  • AllowCallerAccess – 允許 IAM 使用者或角色透過 驗證金鑰DescribeKey。

  • AllowCallerCryptoOps – 允許 IAM 使用者或角色產生資料金鑰、解密和重新加密 （用於金鑰輪換），範圍依加密內容而定。

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCallerAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyConfigBundleRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*"
    },
    {
      "Sid": "AllowCallerCryptoOps",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyConfigBundleRole"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt",
        "kms:ReEncrypt*"
      ],
      "Resource": "*",
      "Condition": {
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore:configurationBundleArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/*"
        }
      }
    }
  ]
}

此政策包含下列陳述式：

  • AllowCallerAccess – 在套件建立或更新時間授予金鑰驗證的 IAM 角色kms:DescribeKey許可。將 111122223333 取代為您的帳戶 ID，並將 MyConfigBundleRole 取代為管理組態套件的 IAM 角色或使用者。

  • AllowCallerCryptoOps – 授予加密aws:bedrock-agentcore:configurationBundleArn內容範圍內的 IAM 角色 kms:GenerateDataKey、 kms:Decrypt和 kms:ReEncrypt*許可。金鑰輪換需要 kms:ReEncrypt*許可 （變更現有套件上的 KMS 金鑰）。將 111122223333、MyConfigBundleRole 和 us-east-1 取代為您的值。若要允許存取您帳戶中的所有組態套件，請使用萬用字元搭配 StringLike：arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/*。

縮小對客戶受管 KMS 金鑰的存取範圍

您可以使用加密內容來縮小對客戶受管金鑰的存取範圍。AgentCore 最佳化在所有 KMS 操作中包含下列加密內容：

{
  "aws:bedrock-agentcore:configurationBundleArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/bundle-id"
}

您可以在金鑰政策條件中使用此加密內容，將 KMS 操作限制為特定組態套件，如上述範例金鑰政策中的 AllowCallerCryptoOps陳述式所示。

使用客戶受管 KMS 金鑰建立組態套件

若要加密組態套件，請在呼叫 CreateConfigurationBundle 時指定 kmsKeyArn 參數。

範例
AWS CLI
aws bedrock-agentcore-control create-configuration-bundle \
  --bundle-name "MyEncryptedBundle" \
  --kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
  --components '{
    "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent": {
      "configuration": {
        "systemPrompt": "You are a helpful assistant.",
        "modelId": "anthropic.claude-3-sonnet"
      }
    }
  }'
Python (Boto3)
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.create_configuration_bundle(
    bundleName='MyEncryptedBundle',
    kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
    components={
        'arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent': {
            'configuration': {
                'systemPrompt': 'You are a helpful assistant.',
                'modelId': 'anthropic.claude-3-sonnet'
            }
        }
    }
)

print(f"Bundle ID: {response['bundleId']}")

在現有套件上變更加密組態

您可以使用 UpdateConfigurationBundle 變更現有套件上的加密組態：

  • 新增加密 – 在沒有加密的套件kmsKeyArn上指定 。服務會產生新的 DEK 並加密元件組態。

  • 輪換索引鍵 – 指定不同的 kmsKeyArn。服務會使用 將現有 DEK 從舊金鑰重新包裝至新金鑰kms:ReEncrypt。發起人必須擁有兩個金鑰的許可。如果舊金鑰無法使用 （停用、刪除或缺少許可），更新將會失敗。

注意

新增客戶受管金鑰加密後，就無法從組態套件中移除。

監控組態套件的 KMS 用量

組態套件 KMS 操作會顯示下列 CloudTrail 事件名稱：

  • GenerateDataKey – 使用客戶受管金鑰建立套件，或將加密新增至現有套件時。encryptionContext 欄位包含 aws:bedrock-agentcore:configurationBundleArn。

  • Decrypt – 擷取套件內容 (GetConfigurationBundle、GetConfigurationBundleVersion) 或更新加密套件時。

  • ReEncrypt – 透過 UpdateConfigurationBundle 在現有套件上輪換 KMS 金鑰時。

  • DescribeKey – 在套件建立或更新時間驗證金鑰時。

當金鑰無法使用時的行為

如果您停用或刪除組態套件所使用的客戶受管 KMS 金鑰：

  • CreateConfigurationBundle – 使用 驗證時失敗ValidationException。

  • UpdateConfigurationBundle – 失敗，因為服務無法解密現有的 DEK 以重新加密新元件。金鑰輪換也會失敗，因為舊金鑰無法重新包裝。

  • GetConfigurationBundle / GetConfigurationBundleVersion – 失敗，因為服務無法解密 DEK 或元件組態。

  • ListConfigurationBundles / ListConfigurationBundleVersions – 成功，因為列出只會傳回中繼資料，且不需要 KMS 操作。

  • DeleteConfigurationBundle – 由於刪除不需要解密套件資料，因此成功。

若要還原存取權，請重新啟用金鑰或更新金鑰政策，以授予所需的許可。