# @aws-crypto/node-jose\_aws-kms-extension 中文文档

规范地址：https://npmcn.com/package/%40aws-crypto/node-jose_aws-kms-extension/

版本：2\.1\.0
npm 元数据更新时间：2025-05-22T20:13:41.580Z
中文译文更新时间：2026-11-07T15:48:11.387Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：74 kB，25 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18\.0\.0
- 运行依赖：2 个
- 首次发布：2023-09-29T20:04:48.325Z
- 最新版本发布：2024-05-19T19:22:06.076Z
- 近 30 天下载量：6636（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

这个库是在 AWS KMS 支持下的节点快取库的扩展

## 安装

```sh
npm install @aws-crypto/node-jose_aws-kms-extension
```

也可以使用：`pnpm add @aws-crypto/node-jose_aws-kms-extension`、`yarn add @aws-crypto/node-jose_aws-kms-extension`、`bun add @aws-crypto/node-jose_aws-kms-extension`

## README

# 节点- jose aws- kms- 扩展

这个库是扩展 [节点夹](https://www.npmjs.com/package/node-jose) 库,并使用猴子相扑来扩展节点-jose的能力. 它为基于JWE的加密器/解密器和基于JWS的签名器/验证器提供加密操作,并存储在AWS密钥管理服务(KMS)中.

## 安装

您可以从 [无](https://www.npmjs.com/package/@aws-crypto/node-jose_aws-kms-extension) 使用下列命令。 这个图书馆需要18个或以上的Node.js.

```bash
npm install @aws-crypto/node-jose_aws-kms-extension
```

## 使用量

从 `@aws-crypto/node-jose_aws-kms-extension` 模块 :

```ts
import {
  KMSAsymmetricSigningKey,
  KMSSymmetricCEK,
  KMSSymmetricKey,
} from '@aws-crypto/node-jose_aws-kms-extension';
```

导入主jose 对象 .

```ts
import { jose } from '@aws-crypto/node-jose_aws-kms-extension';
```

现在,你可以使用所有现有的节点-快感特性, 和没有这个库时一样。 这个库透明地增加了 AWS KMS 支持 。 您可以使用您的 AWS KMS 密钥进行各种加密和签名操作, 使用常规节点- jose 函数 。 AWS KMS 特定的算法名称被支持.

支助 `node-jose` 职能包括:

1.  `jose.JWE.createEncrypt()`
2.  `jose.JWE.createDecrypt()`
3.  `jose.JWS.createSign()`
4.  `jose.JWS.createVerify()`

此库使用 [@aws- sdk/ 客户端 - kms](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/kms/) 它与AWS KMS的所有通讯.

[支持的 KMS 签名算法](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-kms/Variable/SigningAlgorithmSpec/)

[支持的 KMS 加密算法](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-kms/Variable/EncryptionAlgorithmSpec/)

[支持的数据密钥光谱](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-kms/Variable/DataKeySpec/)

## 实例

### 从模块@aws-crypto/node-jose aws-kms-extension和@aws-sdk/客户端-kms导入变量

```ts
import {
  jose,
  KMSAsymmetricSigningKey,
  KMSSymmetricCEK,
  KMSSymmetricKey,
} from '@aws-crypto/node-jose_aws-kms-extension';
import { KMSClient } from "@aws-sdk/client-kms";
```

### 创建 AWS KMS 客户端

```ts
const kmsClient: KMSClient = new KMSClient({ region: 'REGION' });
```

### 签名

1.  准备格式为 `compact`,以及标题字段.
2.  将密钥与 KMSA 对称标记关键对象一起编写签名 .
3.  用乔斯 JWS. 创建签名方法 签署有效载荷.

```ts
const signingOpts = {
  format: 'compact',
  fields: {
    alg: 'SIGNING_ALGORITHM',
    kid: 'KMS_SIGNING_KEY_ID',
    JWS_CRIT_HEADER1: 'JWS_CRIT_HEADER1_VALUE',
    JWS_CRIT_HEADER2: 'JWS_CRIT_HEADER2_VALUE',
    crit: ['JWS_CRIT_HEADER1', 'JWS_CRIT_HEADER2'],
  },
};

const signatory = {
  key: new KMSAsymmetricSigningKey('KMS_SIGNING_KEY_ID', kmsClient),
};

const dataToSign = 'This is the data to sign';
const signer = jose.JWS.createSign(signingOpts, signatory);
const jws: Promise<string> = signer
  .update(dataToSign)
  .final()
  .then(function (result: string) {
    console.log('JWS: ', result);
    return result;
  });

```

### 加密

1.  编写格式为 `compact`,标题字段和 cek 作为 KMSS对称CEK 对象.
2.  将加密收件人编制为 `false`键。 使用相同的 KMS 密钥创建 KMSS对称CEK 和 KMSS对称Key .
3.  使用乔斯。 JWE.创建加密jws有效载荷的方法.

```ts
const encryptionOpts = {
  format: 'compact',
  fields: {
    kid: 'ENCRYPTION_KMS_KEY_ID',
    alg: 'KEY_ENCRYPTION_ALGORITHM',
    enc: 'CONTENT_ENCRYPTION_ALGORITHM',
    JWE_CRIT_HEADER1: 'JWE_CRIT_HEADER1_VALUE',
    JWE_CRIT_HEADER2: 'JWE_CRIT_HEADER2_VALUE',
    crit: ['JWE_CRIT_HEADER1', 'JWE_CRIT_HEADER2'],
  },
  cek: new KMSSymmetricCEK('KMS_ENCRYPTION_KEY_ID', kmsClient, 'KEY_SPEC'),
};

const encryptionRecipient = {
  reference: false,
  key: new KMSSymmetricKey('KMS_ENCRYPTION_KEY_ID', kmsClient),
};

const encrypter = jose.JWE.createEncrypt(
  encryptionOpts,
  encryptionRecipient,
);
const jwe: Promise<string> = jws.then(function (jws: string) {
  return encrypter
    .update(jws)
    .final()
    .then(function (result: string) {
      console.log('JWE: ', result);
      return result;
    });
});

```

### 解密

1.  与处理器一起准备解密选项来处理jwe关键头.
2.  预解密被假定为 KMSS 对称Key 对象
3.  用乔斯 JWE.创建解密jwe有效载荷的方法.

```ts
const decryption_opts = {
  handlers: {
    JWE_CRIT_HEADER1: function(jwe: any) {
      console.log(jwe.header.JWE_CRIT_HEADER1)
      // process JWE_CRIT_HEADER1
    },
    JWE_CRIT_HEADER2: function(jwe: any) {
      console.log(jwe.header.JWE_CRIT_HEADER2)
      // process JWE_CRIT_HEADER2
    }
  },
};

const decryption_assumedKey = new KMSSymmetricKey(
  'KMS_ENCRYPTION_KEY_ID',
  kmsClient,
);

const decrypter = jose.JWE.createDecrypt(
  decryption_assumedKey,
  decryption_opts,
);

const decyptedContent: Promise<any> = jwe.then(function (jwe: string) {
  return decrypter.decrypt(jwe).then(function (result: any) {
    console.log('JWE decryption result: ', result);
    return result;
  });
});
```

### 核查

1.  与处理器一起编写验证选项,处理jws关键头.
2.  准备假想的 KMSA 对称签名关键对象的校验
3.  用乔斯 JWS.创建验证jws有效载荷的方法.

```ts
const verification_opts = {
  handlers: {
    JWS_CRIT_HEADER1: function(jws: any) {
      console.log(jws.header.JWS_CRIT_HEADER1)
      // process JWS_CRIT_HEADER1
    },
    JWS_CRIT_HEADER2: function(jws: any) {
      console.log(jws.header.JWS_CRIT_HEADER2)
      // process JWS_CRIT_HEADER2
    }
  },
};

const verificationAssumedKey = new KMSAsymmetricSigningKey(
  'KMS_SIGNING_KEY_ID',
  kmsClient,
);

const verifier = jose.JWS.createVerify(
  verificationAssumedKey,
  verification_opts,
);
const verificationResult: Promise<any> = decyptedContent.then(function (
  decryptedContent: any,
) {
  const payloadToVerify = jose.util.utf8.encode(decryptedContent.payload);
  return verifier.verify(payloadToVerify).then(function (result: any) {
    console.log('JWS verification result: ', result);
    console.log('Verified payload: ', jose.util.utf8.encode(result.payload));
    return result;
  });
});
```

#### 注:KMS SIGNING KEY ID和KMS ENCRYPTION KEY ID可以是KMS密钥ID,密钥ARN,别名,或别名ARN. 当使用别名时, 它会有前缀 `alias/`。应在不同的亚马逊网络服务账户中指定关键ARN或别名ARN.

# 警卫

见 [捐款](https://npmcn.com/package/%40aws-crypto/node-jose_aws-kms-extension/CONTRIBUTING.md#security-issue-notifications) 更多信息.

## 许可证

该图书馆在以下 [Apache 许可证,2.0版本](http://www.apache.org/licenses/LICENSE-2.0), (中文(简体) ), 见 [自由主义](https://npmcn.com/package/%40aws-crypto/node-jose_aws-kms-extension/LICENSE) 财务报告和审定财务报表 [通知](https://npmcn.com/package/%40aws-crypto/node-jose_aws-kms-extension/NOTICE) 更多信息.

## 常见问题

### @aws-crypto/node-jose\_aws-kms-extension 是什么？

这个库是在 AWS KMS 支持下的节点快取库的扩展

### 如何安装 @aws-crypto/node-jose\_aws-kms-extension？

在项目目录运行 npm install @aws-crypto/node-jose\_aws-kms-extension，或使用 pnpm add / yarn add / bun add。

### @aws-crypto/node-jose\_aws-kms-extension 支持 TypeScript 吗？

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

### @aws-crypto/node-jose\_aws-kms-extension 支持 ESM 还是 CommonJS？

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

### @aws-crypto/node-jose\_aws-kms-extension 需要什么版本的 Node\.js？

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

### @aws-crypto/node-jose\_aws-kms-extension 可以商用吗？

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

### @aws-crypto/node-jose\_aws-kms-extension 的下载量有多少？

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

### @aws-crypto/node-jose\_aws-kms-extension 还在维护吗？

最新版本 2\.1\.0 发布于 2024/05/20（2 年前）；至今共发布 4 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/09/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。