# 組態套件加密
<a name="configuration-bundles-encryption"></a>

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

## 運作方式
<a name="configuration-bundles-encryption-how-it-works"></a>

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

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

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

### 設定使用客戶受管 KMS 金鑰的許可
<a name="configuration-bundles-encryption-key-policy"></a>

下列金鑰政策提供組態套件加密所需的最低許可。此政策具有兩個陳述式：
+  **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 金鑰的存取範圍
<a name="configuration-bundles-encryption-scoping"></a>

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

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

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

### 使用客戶受管 KMS 金鑰建立組態套件
<a name="configuration-bundles-encryption-creating"></a>

若要加密組態套件，請在呼叫 [CreateConfigurationBundle](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateConfigurationBundle.html) 時指定 `kmsKeyArn` 參數。

**Example**  

```
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"
      }
    }
  }'
```

```
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']}")
```

### 在現有套件上變更加密組態
<a name="configuration-bundles-encryption-changing"></a>

您可以使用 [UpdateConfigurationBundle](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateConfigurationBundle.html) 變更現有套件上的加密組態：
+  **新增加密** – 在沒有加密的套件`kmsKeyArn`上指定 。服務會產生新的 DEK 並加密元件組態。
+  **輪換索引鍵** – 指定不同的 `kmsKeyArn`。服務會使用 將現有 DEK 從舊金鑰重新包裝至新金鑰`kms:ReEncrypt`。發起人必須擁有兩個金鑰的許可。如果舊金鑰無法使用 （停用、刪除或缺少許可），更新將會失敗。

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

## 監控組態套件的 KMS 用量
<a name="configuration-bundles-encryption-monitoring"></a>

組態套件 KMS 操作會顯示下列 CloudTrail 事件名稱：
+  `GenerateDataKey` – 使用客戶受管金鑰建立套件，或將加密新增至現有套件時。`encryptionContext` 欄位包含 `aws:bedrock-agentcore:configurationBundleArn`。
+  `Decrypt` – 擷取套件內容 (GetConfigurationBundle、GetConfigurationBundleVersion) 或更新加密套件時。
+  `ReEncrypt` – 透過 UpdateConfigurationBundle 在現有套件上輪換 KMS 金鑰時。
+  `DescribeKey` – 在套件建立或更新時間驗證金鑰時。

## 當金鑰無法使用時的行為
<a name="configuration-bundles-encryption-unavailable"></a>

如果您停用或刪除組態套件所使用的客戶受管 KMS 金鑰：
+  **CreateConfigurationBundle** – 使用 驗證時失敗`ValidationException`。
+  **UpdateConfigurationBundle** – 失敗，因為服務無法解密現有的 DEK 以重新加密新元件。金鑰輪換也會失敗，因為舊金鑰無法重新包裝。
+  **GetConfigurationBundle / GetConfigurationBundleVersion** – 失敗，因為服務無法解密 DEK 或元件組態。
+  **ListConfigurationBundles / ListConfigurationBundleVersions** – 成功，因為列出只會傳回中繼資料，且不需要 KMS 操作。
+  **DeleteConfigurationBundle** – 由於刪除不需要解密套件資料，因此成功。

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