> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 客户托管密钥

> 在你的 Devin Enterprise 专用部署中，使用你自己的 AWS KMS 密钥对静态数据进行加密。

<div id="overview">
  ## 概述
</div>

默认情况下，Cognition 会使用由其管理的密钥，对所有静态存储的客户数据进行加密。对于需要直接掌控加密密钥的组织，Devin 支持通过 [AWS Key Management Service (KMS)](https://aws.amazon.com/kms/) 使用 **客户托管密钥 (CMK)**。

使用 CMK 时，你需要提供自己的 AWS KMS 密钥，Cognition 会使用该密钥对存储在你的专用租户中的数据进行加密，其中包括会话数据和 VM 快照。这意味着你可以完全控制密钥的整个生命周期，并可随时轮换、禁用或撤销其访问权限。

<Note>
  CMK 仅适用于 **Enterprise Dedicated** 部署，且必须在初始部署设置时完成配置。有关部署模型的更多信息，请参阅 [企业部署](/zh/enterprise/deployment/overview)。
</Note>

<div id="how-it-works">
  ## 工作原理
</div>

在 Enterprise Dedicated 部署中，Devin 会将客户数据存储在你的专用租户内的 Amazon S3 存储桶中。启用 CMK 后：

1. 你的 AWS KMS 密钥将用于对写入这些 S3 存储桶的所有数据进行**服务器端加密**。
2. Cognition 的基础架构会在写入时使用该密钥加密数据，并在读取时使用该密钥解密数据。
3. 你仍然拥有自己 AWS 账户中的该密钥，并且可以独立管理其生命周期。

如果你未提供 KMS 密钥，Cognition 会代表你创建并管理一个加密密钥。

<div id="prerequisites">
  ## 先决条件
</div>

在设置 CMK 之前，请确保你已具备：

* 在 Cognition 上使用 **Enterprise Dedicated** 部署 (CMK 必须在初始部署时完成配置)
* 一个与 Devin 部署位于**同一 AWS 区域**的 **AWS KMS 密钥**
* 修改 KMS 密钥策略并创建密钥别名的权限

<Info>
  请联系你的 Cognition 账户团队，确认你的专用租户所在的 AWS 区域。
</Info>

<div id="setup">
  ## 设置
</div>

<div id="step-1-create-or-select-a-kms-key">
  ### 步骤 1：创建或选择 KMS 密钥
</div>

使用现有的对称 AWS KMS 密钥，或在与你的 Cognition 专用租户位于同一区域时，[创建一个新的密钥](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)。该密钥必须是**对称加密密钥** (AWS KMS 中的默认密钥类型) 。

<div id="step-2-add-a-key-alias">
  ### 步骤 2：添加密钥别名
</div>

将别名 **`devin-customer-managed-key`** 添加到你的 KMS 密钥。Cognition 的基础架构需要使用这个精确的别名来定位该密钥并将其用于加密。

<Tabs>
  <Tab title="AWS 控制台">
    1. 打开 [AWS KMS 控制台](https://console.aws.amazon.com/kms)。
    2. 选择你的密钥，然后前往 **Aliases** 选项卡。
    3. 选择 **Create alias**。
    4. 输入 `devin-customer-managed-key` 作为别名名称。
    5. 保存别名。
  </Tab>

  <Tab title="AWS CLI">
    ```bash theme={null}
    aws kms create-alias \
        --alias-name alias/devin-customer-managed-key \
        --target-key-id <your-key-id>
    ```
  </Tab>
</Tabs>

<div id="step-3-configure-the-key-policy">
  ### 步骤 3：配置密钥策略
</div>

更新你的 KMS 密钥策略，允许 Cognition 的 AWS 账户使用该密钥进行加密和解密。将以下语句添加到你的密钥策略中：

```json theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::272506498303:root",
                    "arn:aws:iam::063509147090:root"
                ]
            },
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:ReEncrypt*",
                "kms:GenerateDataKey*",
                "kms:DescribeKey"
            ],
            "Resource": "*"
        }
    ]
}
```

<Tabs>
  <Tab title="AWS 控制台">
    1. 打开 [AWS KMS 控制台](https://console.aws.amazon.com/kms)。
    2. 选择你的密钥，然后前往 **Key policy** 选项卡。
    3. 选择 **Edit**。
    4. 将上述语句添加到现有密钥策略的 `Statement` 数组中。
    5. 保存策略。
  </Tab>

  <Tab title="AWS CLI">
    ```bash theme={null}
    # 首先，获取当前的密钥策略
    aws kms get-key-policy \
        --key-id <your-key-id> \
        --policy-name default \
        --output text > key-policy.json

    # 编辑 key-policy.json，添加上述语句，
    # 然后应用更新后的策略
    aws kms put-key-policy \
        --key-id <your-key-id> \
        --policy-name default \
        --policy file://key-policy.json
    ```
  </Tab>
</Tabs>

<div id="step-4-provide-the-key-arn-to-cognition">
  ### 步骤 4：向 Cognition 账户团队提供密钥 ARN
</div>

请将你的 KMS 密钥 ARN 发送给你的 Cognition 账户团队。ARN 格式如下：

```text theme={null}
arn:aws:kms:<region>:<your-account-id>:key/<key-id>
```

一旦 Cognition 收到你的密钥 ARN，团队就会将你的专用租户配置为使用该密钥进行加密。你无需执行任何其他操作。

<div id="key-management">
  ## 密钥管理
</div>

<div id="key-rotation">
  ### 密钥轮换
</div>

AWS KMS 支持对客户托管密钥进行[自动密钥轮换](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)。启用后，AWS 每年都会自动为你的密钥生成新的加密材料，同时保留旧材料，以解密此前加密的数据。Cognition 建议启用自动密钥轮换。

<div id="revoking-access">
  ### 撤销访问权限
</div>

你可以随时移除在 [步骤 3](#step-3-configure-the-key-policy) 中添加的策略语句，以撤销 Cognition 对你的 KMS 密钥的访问权限。请注意，撤销访问权限后，Cognition 将无法在你的租户中读取或写入加密数据，这会导致 Devin 无法正常运行，直到访问权限恢复。

<Warning>
  禁用或删除你的 KMS 密钥，或撤销 Cognition 的访问权限，都将导致你租户中的所有已加密客户数据无法读取。请在更改你的密钥或其策略之前，确保你已了解相关影响。
</Warning>

<div id="monitoring-key-usage">
  ### 监控密钥用量
</div>

你可以通过 [AWS CloudTrail](https://docs.aws.amazon.com/kms/latest/developerguide/logging-using-cloudtrail.html) 监控你的 KMS 密钥的所有使用记录。CloudTrail 会记录针对你的密钥发起的每一次 API 调用，包括来自 Cognition 账户的调用，从而提供完整的加密和解密操作审计记录。

<div id="faqs">
  ## 常见问题
</div>

<AccordionGroup>
  <Accordion title="哪些数据会使用我的 KMS 密钥加密？">
    你的 KMS 密钥用于加密存储在专用租户内 Amazon S3 中的客户数据，包括会话数据和 VM 快照。
  </Accordion>

  <Accordion title="我可以使用其他 AWS 区域的 KMS 密钥吗？">
    不可以。你的 KMS 密钥必须与你的 Devin 部署位于同一 AWS 区域。请联系你的 Cognition 账户团队，确认你的租户所在区域。
  </Accordion>

  <Accordion title="如果我不提供 KMS 密钥，会发生什么？">
    Cognition 将代表你创建并管理一个加密密钥。所有数据在静态存储时仍会被加密——CMK 只是让你能够直接控制该密钥。
  </Accordion>

  <Accordion title="CMK 是否适用于 Enterprise Cloud 部署？">
    不适用。CMK 目前仅适用于 Enterprise Dedicated 部署。
  </Accordion>

  <Accordion title="完成初始设置后，我可以更换 KMS 密钥吗？">
    可以。请联系你的 Cognition 账户团队，更新你租户的 KMS 密钥 ARN。此前已加密的数据将继续使用原始密钥加密，除非重新加密。
  </Accordion>
</AccordionGroup>