本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 APIs管理 CMK
本主題說明如何使用 Amazon MSF APIs 建立和更新 KMS CMKs。若要遵循本主題中所述的程序，您必須具有管理 KMS 金鑰和 Amazon MSF 應用程式的許可。本主題中的程序使用寬鬆金鑰政策，僅供示範和測試之用。**我們不建議**針對生產工作負載使用這類寬鬆金鑰政策。在生產工作負載的真實案例中，會隔離角色、許可和工作流程。
**Topics**
+ [建立和指派 KMS 金鑰](#create-assign-cmk-api)
+ [更新現有應用程式以使用 CMK](#update-existing-app-use-cmk-api)
+ [從 CMK 還原至 AWS 擁有的金鑰](#revert-cmk-to-aok-api)
## 建立和指派 KMS 金鑰
開始之前，請先建立 KMS 金鑰。如需有關建立 KMS 金鑰的資訊，請參閱《 *AWS Key Management Service 開發人員指南*》中的[建立 KMS 金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)。
**Topics**
+ [建立 KMS 金鑰政策](#create-cmk-kms-key-policy)
+ [應用程式生命週期運算子 (API 呼叫者） 許可](#create-cmk-kms-api-caller-permissions)
### 建立 KMS 金鑰政策
若要在 Amazon MSF 中使用 CMK，您必須將下列服務主體新增至您的金鑰政策： `kinesisanalytics.amazonaws.com`和 `infrastructure.kinesisanalytics.amazonaws.com`。Amazon MSF 使用這些服務主體進行驗證和資源存取。如果您未包含這些服務主體，Amazon MSF 會拒絕請求。
下列 KMS 金鑰政策可讓 Amazon MSF 將 CMK 用於應用程式 {{MyCmkApplication}}。此政策會將必要的許可授予**Operator**角色和 Amazon MSF 服務主體`kinesisanalytics.amazonaws.com`，以及 `infrastructure.kinesisanalytics.amazonaws.com`，以執行下列操作：
+ 描述 CMK
+ 加密應用程式資料
+ 解密應用程式資料
+ 建立金鑰的授予
下列範例使用 IAM 角色。您可以使用下列範例做為範本，建立 KMS 金鑰的金鑰政策，但請務必執行下列動作：
+ `arn:aws:iam::{{123456789012}}:role/Operator` 將 取代為 **Operator**角色。您必須先建立**Operator**角色或使用者，才能建立金鑰政策。否則會導致請求失敗。
+ `arn:aws:kinesisanalytics:us-east-1:{{123456789012}}:application/{{MyCmkApplication}}` 將 取代為您應用程式的 ARN。
+ `kinesisanalytics.{{us-east-1}}.amazonaws.com` 將 取代為對應區域的服務值。
+ 將 {{123456789012}} 取代為您的 CMK 帳戶 idKey 政策。
+ 新增其他政策陳述式，[以允許金鑰管理員管理 KMS 金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html#key-policy-default-allow-administrators)。否則會導致失去管理金鑰的存取權。
下列金鑰政策陳述式很大，因為它們旨在明確顯示每個動作所需的條件。
```
{
"Version":"2012-10-17",
"Id": "MyMsfCmkApplicationKeyPolicy",
"Statement": [
{
"Sid": "AllowOperatorToDescribeKey",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::{{123456789012}}:role/Operator"
},
"Action": "kms:DescribeKey",
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": "kinesisanalytics.{{us-east-1}}.amazonaws.com"
}
}
},
{
"Sid": "AllowOperatorToConfigureAppToUseKeyForApplicationState",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::{{123456789012}}:role/Operator"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:GenerateDataKeyWithoutPlaintext"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:EncryptionContext:aws:kinesisanalytics:arn":
"arn:aws:kinesisanalytics:{{us-east-1}}:{{123456789012}}:application/{{MyCmkApplication}}",
"kms:ViaService": "kinesisanalytics.{{us-east-1}}.amazonaws.com"
}
}
},
{
"Sid": "AllowOperatorToConfigureAppToCreateGrantForRunningState",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::{{123456789012}}:role/Operator"
},
"Action": "kms:CreateGrant",
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:EncryptionContext:aws:kinesisanalytics:arn":
"arn:aws:kinesisanalytics:{{us-east-1}}:{{123456789012}}:application/{{MyCmkApplication}}",
"kms:ViaService": "kinesisanalytics.{{us-east-1}}.amazonaws.com",
"kms:GrantConstraintType": "EncryptionContextSubset"
},
"ForAllValues:StringEquals": {
"kms:GrantOperations": "Decrypt"
}
}
},
{
"Sid": "AllowMSFServiceToDescribeKey",
"Effect": "Allow",
"Principal": {
"Service": [
"kinesisanalytics.amazonaws.com",
"infrastructure.kinesisanalytics.amazonaws.com"
]
},
"Action": "kms:DescribeKey",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:SourceArn":
"arn:aws:kinesisanalytics:{{us-east-1}}:{{123456789012}}:application/{{MyCmkApplication}}",
"aws:SourceAccount": "{{123456789012}}"
}
}
},
{
"Sid": "AllowMSFServiceToGenerateDataKeyForDurableState",
"Effect": "Allow",
"Principal": {
"Service": "kinesisanalytics.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:SourceArn":
"arn:aws:kinesisanalytics:{{us-east-1}}:{{123456789012}}:application/{{MyCmkApplication}}",
"kms:EncryptionContext:aws:kinesisanalytics:arn":
"arn:aws:kinesisanalytics:{{us-east-1}}:{{123456789012}}:application/{{MyCmkApplication}}",
"aws:SourceAccount": "{{123456789012}}"
}
}
},
{
"Sid": "AllowMSFServiceToDecryptForDurableState",
"Effect": "Allow",
"Principal": {
"Service": "kinesisanalytics.amazonaws.com"
},
"Action": [
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:EncryptionContext:aws:kinesisanalytics:arn":
"arn:aws:kinesisanalytics:{{us-east-1}}:{{123456789012}}:application/{{MyCmkApplication}}"
}
}
},
{
"Sid": "AllowMSFServiceToUseKeyForRunningState",
"Effect": "Allow",
"Principal": {
"Service": [
"infrastructure.kinesisanalytics.amazonaws.com"
]
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKeyWithoutPlaintext"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:EncryptionContext:aws:kinesisanalytics:arn":
"arn:aws:kinesisanalytics:{{us-east-1}}:{{123456789012}}:application/{{MyCmkApplication}}"
}
}
},
{
"Sid": "AllowMSFServiceToCreateGrantForRunningState",
"Effect": "Allow",
"Principal": {
"Service": [
"infrastructure.kinesisanalytics.amazonaws.com"
]
},
"Action": "kms:CreateGrant",
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:EncryptionContext:aws:kinesisanalytics:arn":
"arn:aws:kinesisanalytics:{{us-east-1}}:{{123456789012}}:application/{{MyCmkApplication}}",
"kms:GrantConstraintType": "EncryptionContextSubset"
},
"ForAllValues:StringEquals": {
"kms:GrantOperations": "Decrypt"
}
}
}
]
}
```
### 應用程式生命週期運算子 (API 呼叫者） 許可
下列 IAM 政策可確保應用程式生命週期運算子具有將 KMS 金鑰指派給應用程式 {{MyCmkApplication}} 的必要許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowMSFAPICalls",
"Effect": "Allow",
"Action": "kinesisanalytics:*",
"Resource": "*"
},
{
"Sid": "AllowPassingServiceExecutionRole",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": "arn:aws:iam::{{123456789012}}:role/{{MyCmkApplicationRole}}"
},
{
"Sid": "AllowDescribeKey",
"Effect": "Allow",
"Action": [
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:{{us-east-1}}:{{123456789012}}:key/{{1234abcd-12ab-34cd-56ef-1234567890ab}}",
"Condition": {
"StringEquals": {
"kms:ViaService": "kinesisanalytics.{{us-east-1}}.amazonaws.com"
}
}
},
{
"Sid": "AllowMyCmkApplicationKeyOperationsForDurableState",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:{{us-east-1}}:{{123456789012}}:key/{{1234abcd-12ab-34cd-56ef-1234567890ab}}",
"Condition": {
"StringEquals": {
"kms:ViaService": "kinesisanalytics.{{us-east-1}}.amazonaws.com",
"kms:EncryptionContext:aws:kinesisanalytics:arn":
"arn:aws:kinesisanalytics:{{us-east-1}}:{{123456789012}}:application/{{MyCmkApplication}}"
}
}
},
{
"Sid": "AllowMyCmkApplicationKeyOperationsForRunningState",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKeyWithoutPlaintext"
],
"Resource": "arn:aws:kms:{{us-east-1}}:{{123456789012}}:key/{{1234abcd-12ab-34cd-56ef-1234567890ab}}",
"Condition": {
"StringEquals": {
"kms:ViaService": "kinesisanalytics.{{us-east-1}}.amazonaws.com",
"kms:EncryptionContext:aws:kinesisanalytics:arn":
"arn:aws:kinesisanalytics:{{us-east-1}}:{{123456789012}}:application/{{MyCmkApplication}}"
}
}
},
{
"Sid": "AllowMyCmkApplicationCreateGrantForRunningState",
"Effect": "Allow",
"Action": "kms:CreateGrant",
"Resource": "arn:aws:kms:{{us-east-1}}:{{123456789012}}:key/{{1234abcd-12ab-34cd-56ef-1234567890ab}}",
"Condition": {
"ForAllValues:StringEquals": {
"kms:GrantOperations": "Decrypt"
},
"StringEquals": {
"kms:ViaService": "kinesisanalytics.{{us-east-1}}.amazonaws.com",
"kms:EncryptionContext:aws:kinesisanalytics:arn":
"arn:aws:kinesisanalytics:{{us-east-1}}:{{123456789012}}:application/{{MyCmkApplication}}",
"kms:GrantConstraintType": "EncryptionContextSubset"
}
}
}
]
}
```
------
## 更新現有應用程式以使用 CMK
在 Amazon MSF 中，您可以將 CMK 政策套用至使用 AWS 擁有的金鑰 (AOKs的現有應用程式。
根據預設，Amazon MSF 會使用 AOKs來加密暫時性 （執行中的應用程式儲存） 和耐用 （耐用的應用程式儲存） 儲存中的所有資料。這表示根據預設，受 Flink [檢查點](how-fault.md)或[快照](how-snapshots.md)約束的所有資料都會使用 AOKs加密。當您以 CMK 取代 AOK 時，新的檢查點和快照會以 CMK 加密。不過，歷史快照將保持使用 AOK 加密。
**更新現有應用程式以使用 CMK**
1. 使用下列組態建立 JSON 檔案。
請務必將 的值取代`CurrentApplicationVersionId`為應用程式的目前版本編號。您可以使用 [DescribeApplication](https://docs.aws.amazon.com/managed-flink/latest/apiv2/API_DescribeApplication.html) 取得應用程式的目前版本編號。
在此 JSON 組態中，請記得將{{範例}}值取代為實際值。
```
{
"ApplicationName": "{{MyCmkApplication}}",
"CurrentApplicationVersionId": {{1}},
"ApplicationConfigurationUpdate": {
"ApplicationEncryptionConfigurationUpdate": {
"KeyTypeUpdate": "CUSTOMER_MANAGED_KEY",
"KeyIdUpdate": "{{arn:aws:kms:us-east-1:{{123456789012}}:key/{{1234abcd-12ab-34cd-56ef-1234567890ab}}}}"
}
}
}
```
1. 儲存此檔案。例如，將其儲存為名稱 **enable-cmk.json**。
1. 執行 [update-application](https://docs.aws.amazon.com/cli/latest/reference/kinesisanalyticsv2/update-application.html) AWS CLI 命令，如下列範例所示。在此命令中，提供您在先前步驟中建立的 JSON 組態檔案做為檔案引數。
```
aws kinesisanalyticsv2 update-application \
--cli-input-json file://enable-cmk.json
```
只有在符合下列條件時，才能接受上述組態來更新應用程式以使用 CMK：
+ API 呼叫者具有允許存取金鑰的政策陳述式。
+ 金鑰政策具有允許 API 呼叫者存取金鑰的政策陳述式。
+ 金鑰政策具有允許 Amazon MSF 服務主體`kinesisanalytics.amazonaws.com`存取金鑰的政策陳述式。
## 從 CMK 還原至 AWS 擁有的金鑰
**從 CMK 還原至 AOK**
1. 使用下列組態建立 JSON 檔案。
在此 JSON 組態中，請記得將{{範例}}值取代為實際值。
```
{
"ApplicationName": "{{MyCmkApplication}}",
"CurrentApplicationVersionId": {{1}},
"ApplicationConfigurationUpdate": {
"ApplicationEncryptionConfigurationUpdate": {
"KeyTypeUpdate": "AWS_OWNED_KEY"
}
}
}
```
1. 儲存此檔案。例如，將其儲存為名稱 **disable-cmk.json**。
1. 執行 [update-application](https://docs.aws.amazon.com/cli/latest/reference/kinesisanalyticsv2/update-application.html) AWS CLI 命令，如下列範例所示。在此命令中，提供您在先前步驟中建立的 JSON 組態檔案做為檔案引數。
```
aws kinesisanalyticsv2 update-application \
--cli-input-json file://disable-cmk.json
```