# @aws-cdk/aws-kms 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/aws-kms/

版本：1\.204\.0
npm 元数据更新时间：2023-11-21T10:16:03.541Z
中文译文更新时间：2026-11-07T09:20:37.532Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-kms
原文对照：https://npmcn.com/package/%40aws-cdk/aws-kms/?lang=original
项目主页：https://github.com/aws/aws-cdk
源码仓库：https://github.com/aws/aws-cdk

弃用说明：AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：649 kB，25 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：5 个
- peer 依赖：@aws-cdk/aws-iam 1\.204\.0，@aws-cdk/cloud-assembly-schema 1\.204\.0，@aws-cdk/core 1\.204\.0，@aws-cdk/cx-api 1\.204\.0，constructs ^3\.3\.69
- 首次发布：2018-07-31T13:37:28.114Z
- 最新版本发布：2023-06-19T21:05:35.430Z
- 近 30 天下载量：440694（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：288（近 12 个月 0 个）

## 中文简介

AWS: KMS 的 CDK 构建库

## 安装

```sh
npm install @aws-cdk/aws-kms
```

也可以使用：`pnpm add @aws-cdk/aws-kms`、`yarn add @aws-cdk/aws-kms`、`bun add @aws-cdk/aws-kms`

## README

# AWS 密钥管理服务构建库

* * *

![End-of-Support](https://img.shields.io/badge/End--of--Support-critical.svg?style=for-the-badge)

> AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.
> 
> 关于如何移徙的更多信息,请参见: [_移动到 AWS CDK v2_ 指南](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html)。 。 。 .

* * *

定义 KMS 密钥 :

```ts
new kms.Key(this, 'MyKey', {
  enableKeyRotation: true,
});
```

定义有等待时间的 KMS 密钥 :

指定 AWS KMS 删除从 CloudFormation 堆栈中移除的 CMK 之前的等待期的天数.

```ts
const key = new kms.Key(this, 'MyKey', {
  pendingWindow: Duration.days(10), // Default to 30 Days
});
```

添加几个别名:

```ts
const key = new kms.Key(this, 'MyKey');
key.addAlias('alias/foo');
key.addAlias('alias/bar');
```

定义带有特定密钥规格和密钥用途的密钥 :

有效 `keySpec` 值取决于 `keyUsage` 数值.

```ts
const key = new kms.Key(this, 'MyKey', {
  keySpec: kms.KeySpec.ECC_SECG_P256K1, // Default to SYMMETRIC_DEFAULT
  keyUsage: kms.KeyUsage.SIGN_VERIFY,    // and ENCRYPT_DECRYPT
});
```

## 堆栈之间共享密钥

要在同一 CDK 应用程序中使用不同的堆栈中的 KMS 密钥, 将构造传递到另一个堆栈 :

[在堆栈之间共享密钥](https://npmcn.com/package/%40aws-cdk/aws-kms/test/integ.key-sharing.lit.ts)

## 导入已存在的密钥

### 由 ARN 导入密钥

要使用此 CDK app 中没有定义的 KMS 密钥, 但通过其他方式创建, 请使用 `Key.fromKeyArn(parent, name, ref)`数字 :

```ts
const myKeyImported = kms.Key.fromKeyArn(this, 'MyImportedKey', 'arn:aws:...');

// you can do stuff with this imported key.
myKeyImported.addAlias('alias/foo');
```

请注意呼吁 `.addToResourcePolicy(statement)` 打开 `myKeyImported` 将没有 对密钥政策的影响,因为它不是您的堆栈所拥有。 电话 将是一个不开放.

### 用别名导入密钥

如果一个密钥有关联的异名, 异名可以按名称导入并使用到原位 作为参考。 这方面的一个共同方案是参考AWS管理的密钥.

```ts
import * as cloudtrail from '@aws-cdk/aws-cloudtrail';

const myKeyAlias = kms.Alias.fromAliasName(this, 'myKey', 'alias/aws/s3');
const trail = new cloudtrail.Trail(this, 'myCloudTrail', {
  sendToCloudWatchLogs: true,
  kmsKey: myKeyAlias,
});
```

注意呼吁 `addToResourcePolicy` 财务报告和审定财务报表 `grant*` 方法 `myKeyAlias` 将会是 没有 -ops,和 `addAlias` 财务报告和审定财务报表 `aliasTargetKey` 将失败,因为输入的别名没有 提到基本的 KMS 密钥.

### 用别名查找密钥

如果您不能使用用别名导入的 KMS 密钥( 例如, 您需要访问密钥 ID), 您可以使用 `Key.fromLookup()`。 。 。 .

一般来说,首选方法是使用 `Alias.fromAliasName()` 返回一个 `IAlias` 延伸对象 `IKey`然而,一些服务机构需要获得基本的关键标识。 在这种情况下, `Key.fromLookup()` 允许查找密钥 id.

产生的结果 `Key.fromLookup()` 操作将被写入文件 调用 `cdk.context.json`您必须将此文件输入到源控件中 在非特权环境中可以获得检索值 作为 CI 构建步骤,并确保您的模板构建可重复.

是这样的 `Key.fromLookup()` 可用于:

```ts
const myKeyLookup = kms.Key.fromLookup(this, 'MyKeyLookup', {
  aliasName: 'alias/KeyAlias',
});

const role = new iam.Role(this, 'MyRole', {
  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
});
myKeyLookup.grantEncryptDecrypt(role);
```

请注意呼吁 `.addToResourcePolicy(statement)` 打开 `myKeyLookup` 将没有 对密钥政策的影响,因为它不是您的堆栈所拥有。 电话 将是一个不开放.

## 主要政策

控制KMS密钥的获取和使用需要使用关键政策(与密钥相关的资源政策); 这与大多数其他AWS资源形成对比,在这些资源中,准入可以完全由IAM政策控制, 并有资源政策的选择性补充。 关于对KMS关键接入和政策的更深入了解,见

-   [https://docs.aws.amazon.com/kms/latest/developerguide/control-access-overview.html 页面存档备份,存于互联网档案馆](https://docs.aws.amazon.com/kms/latest/developerguide/control-access-overview.html)
-   [https://docs.aws.amazon.com/kms/latest/developerguide/key-politics.html 互联网档案馆的存檔,存档日期2013-12-21](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)

可创建 KMS 键来信任 IAM 政策. 这是 KMS API 和 in的默认行为 操纵台 此行为由“ @aws- cdk/aws- kms:defaultKeyPolicies” 特性旗启用, 用于所有新项目;对于现有项目,可以通过 传递 `trustAccountIdentities` 属性为 `true` 创建密钥时 :

```ts
new kms.Key(this, 'MyKey', { trustAccountIdentities: true });
```

无论是 `@aws-cdk/aws-kms:defaultKeyPolicies` 特性旗设定, 或 `trustAccountIdentities` 道具集,密钥将获得以下默认密钥策略:

```json
{
  "Effect": "Allow",
  "Principal": {"AWS": "arn:aws:iam::111122223333:root"},
  "Action": "kms:*",
  "Resource": "*"
}
```

这项政策使根账户用户能够完全使用密钥. 这使根账户用户能够通过IAM政策,允许访问其他IAM主机. 根据上述默认政策,未来权限可以添加到关键政策或IAM主要政策中.

```ts
const key = new kms.Key(this, 'MyKey');
const user = new iam.User(this, 'MyUser');
key.grantEncrypt(user); // Adds encrypt permissions to user policy; key policy is unmodified.
```

采用默认 KMS 密钥政策( 这样信任账户身份) 解决了堆栈之间循环依赖的许多问题. 如果没有这一默认的关键政策,关键政策和IAM主要政策都必须增加未来的授权, 如果权限跨越堆栈边界,则会导致循环依赖. (例如,一个堆放的加密桶,另一个堆放的Lambda功能。 )

### 追加或替换默认关键政策

默认密钥政策可以完全修改或替换,这取决于您的使用情况和要求. 对关键政策的一个共同补充是增加允许管理关键的其他关键管理人员 (如更改权限,撤销,删除). 在密钥创建时或之后可指定额外的密钥管理员 通过 `grantAdmin` 方法.

```ts
const myTrustedAdminRole = iam.Role.fromRoleArn(this, 'TrustedRole', 'arn:aws:iam:....');
const key = new kms.Key(this, 'MyKey', {
  admins: [myTrustedAdminRole],
});

const secondKey = new kms.Key(this, 'MyKey2');
secondKey.grantAdmin(myTrustedAdminRole);
```

或者,可以指定一个自定义密钥政策,以取代默认密钥政策.

> **说明**: 在未设置“ @aws- cdk/aws- kms:defaultKeyPolice” 特性旗的应用程序中 并带有 `trustedAccountIdentities` 设置为假(默认),在密钥创建时指定策略 _附录_ 页:1 为默认关键政策提供政策,而不是 _替换_ 默认政策.

```ts
const myTrustedAdminRole = iam.Role.fromRoleArn(this, 'TrustedRole', 'arn:aws:iam:....');
// Creates a limited admin policy and assigns to the account root.
const myCustomPolicy = new iam.PolicyDocument({
  statements: [new iam.PolicyStatement({
    actions: [
      'kms:Create*',
      'kms:Describe*',
      'kms:Enable*',
      'kms:List*',
      'kms:Put*',
    ],
    principals: [new iam.AccountRootPrincipal()],
    resources: ['*'],
  })],
});
const key = new kms.Key(this, 'MyKey', {
  policy: myCustomPolicy,
});
```

> **警告:** 将默认的关键政策替换为只允许特定用户或角色访问的政策 如果删除该用户或角色,则该密钥将面临无法管理的风险. 强烈建议,关键政策应赋予账户根,而不是具体的本金. 见 [https://docs.aws.amazon.com/kms/latest/developerguide/key-politics.html 互联网档案馆的存檔,存档日期2013-12-21](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) 更多信息.

## 常见问题

### @aws-cdk/aws-kms 是什么？

AWS: KMS 的 CDK 构建库注意：该包已被作者标记为弃用——AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

### 如何安装 @aws-cdk/aws-kms？

在项目目录运行 npm install @aws-cdk/aws-kms，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/aws-iam（1\.204\.0）、@aws-cdk/cloud-assembly-schema（1\.204\.0）、@aws-cdk/core（1\.204\.0）、@aws-cdk/cx-api（1\.204\.0）、constructs（^3\.3\.69）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-kms 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-cdk/aws-kms 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws-cdk/aws-kms 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 14\.15\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aws-cdk/aws-kms 可以商用吗？

@aws-cdk/aws-kms 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-cdk/aws-kms 的下载量有多少？

根据 npm 官方下载统计，@aws-cdk/aws-kms 在 2026/10/08 – 2026/11/06 这 30 天内被下载 440,694 次，日均约 14,690 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-cdk/aws-kms 还在维护吗？

最新版本 1\.204\.0 发布于 2023/06/20（3 年前）；至今共发布 288 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/07/31。作者已将其标记为弃用，新项目建议寻找替代方案。