SubtleCrypto：generateKey() 方法

基线 广泛可用

此功能已经非常成熟，并且可以在许多设备和浏览器版本中使用。它自以下时间起在各浏览器中可用： 2015 年 7 月.

安全上下文：此功能仅在安全上下文（HTTPS）中可用，在部分或所有支持的浏览器中可用。

SubtleCrypto 接口的 generateKey() 方法用于生成新的密钥（用于对称算法）或密钥对（用于公钥算法）。

语法

js
generateKey(algorithm, extractable, keyUsages)

参数

algorithm

一个对象，用于定义要生成的密钥类型并提供额外的特定于算法的参数。

extractable

一个布尔值，指示是否可以使用 SubtleCrypto.exportKey() 或 SubtleCrypto.wrapKey() 导出密钥。

keyUsages

一个 Array，其中包含字符串，指示可以使用新生成的密钥执行的操作。数组元素的可能值为

encrypt

该密钥可用于加密消息。

decrypt

该密钥可用于解密消息。

sign

该密钥可用于签名消息。

verify

该密钥可用于验证签名。

deriveKey

该密钥可用于派生新密钥。

deriveBits

该密钥可用于派生比特。

wrapKey

该密钥可用于包装密钥。

unwrapKey

该密钥可用于解包密钥。

返回值

一个 Promise，该 Promise 将解析为一个 CryptoKey（用于对称算法）或一个 CryptoKeyPair（用于公钥算法）。

异常

当遇到以下异常时，promise 将被拒绝

SyntaxError DOMException

当结果是类型为 secret 或 private 的 CryptoKey 但 keyUsages 为空或对于算法类型无效时引发。

SyntaxError DOMException

当结果是 CryptoKeyPair 且其 privateKey.usages 属性为空或对于算法类型无效时引发。

示例

注意：您可以在 GitHub 上尝试使用示例。

RSA 密钥对生成

此代码生成 RSA-OAEP 加密密钥对。在 GitHub 上查看完整代码。

js
let keyPair = await window.crypto.subtle.generateKey(
  {
    name: "RSA-OAEP",
    modulusLength: 4096,
    publicExponent: new Uint8Array([1, 0, 1]),
    hash: "SHA-256",
  },
  true,
  ["encrypt", "decrypt"],
);

椭圆曲线密钥对生成

此代码生成 ECDSA 签名密钥对。在 GitHub 上查看完整代码。

js
let keyPair = await window.crypto.subtle.generateKey(
  {
    name: "ECDSA",
    namedCurve: "P-384",
  },
  true,
  ["sign", "verify"],
);

HMAC 密钥生成

此代码生成 HMAC 签名密钥。在 GitHub 上查看完整代码。

js
let key = await window.crypto.subtle.generateKey(
  {
    name: "HMAC",
    hash: { name: "SHA-512" },
  },
  true,
  ["sign", "verify"],
);

AES 密钥生成

此代码生成 AES-GCM 加密密钥。在 GitHub 上查看完整代码。

js
let key = await window.crypto.subtle.generateKey(
  {
    name: "AES-GCM",
    length: 256,
  },
  true,
  ["encrypt", "decrypt"],
);

Ed25519 密钥生成

此代码生成 Ed25519 签名密钥对。它源自GitHub 上的此源代码，您可以在此处在线运行。

JavaScript

下面显示了使用 Ed25519 算法生成密钥对并在每个密钥中记录信息的代码。请注意，代码在 try..catch 块中运行，因为并非所有浏览器都支持此算法。

JavaScript 首先获取 #sign-button 和 #message <input> 元素，然后为按钮上的 click 事件添加侦听器。事件处理程序清除日志并运行其他操作，并将 <input> 元素的内容作为参数传递。

js
const button = document.querySelector("#run-button");
const input = document.querySelector("#log");

button.addEventListener("click", () => {
  // Clear log
  logElement.innerText = "";
  logElement.scrollTop = logElement.scrollHeight;
  // Run test
  test();
});

async function test() {
  try {
    // Create a key pair and use destructuring assignment to assign to variables
    const { publicKey, privateKey } = await crypto.subtle.generateKey(
      {
        name: "Ed25519",
      },
      true,
      ["sign", "verify"],
    );

    // Log the properties of the keys
    log(`publicKey: ${publicKey}`);
    log(` type: ${publicKey.type}`);
    log(` extractable: ${publicKey.extractable}`);
    log(` algorithm: ${JSON.stringify(publicKey.algorithm)}`);
    log(` usages: ${publicKey.usages}`);
    log(`privateKey: ${privateKey}`);
    log(` type: ${privateKey.type}`);
    log(` extractable: ${privateKey.extractable}`);
    log(` algorithm: ${JSON.stringify(privateKey.algorithm)}`);
    log(` usages: ${privateKey.usages}`);
  } catch (error) {
    log(error);
  }
}

结果

已创建密钥的信息记录在下面（如果浏览器不允许创建密钥，则为错误字符串）。

X25519 密钥生成

此代码生成可用于 SubtleCrypto.deriveKey() 创建共享密钥或用于 SubtleCrypto.deriveBits() 创建共享密钥的 X25519 公钥和私钥对。

JavaScript

下面显示了使用 X25519 算法生成密钥对并在每个密钥中记录信息的代码。请注意，代码在 try..catch 块中运行，因为并非所有浏览器都支持此算法。

JavaScript 首先获取 #run-button 和 #log <input> 元素，然后为按钮上的 click 事件添加侦听器。事件处理程序清除日志、生成 X25519 密钥对并记录其某些属性。

js
const button = document.querySelector("#run-button");
const input = document.querySelector("#log");

button.addEventListener("click", () => {
  // Clear log
  logElement.innerText = "";
  logElement.scrollTop = logElement.scrollHeight;
  // Run test
  test();
});

async function test() {
  try {
    // Create a key pair and use destructuring assignment to assign to variables
    const { publicKey, privateKey } = await crypto.subtle.generateKey(
      {
        name: "X25519",
      },
      true,
      ["deriveKey", "deriveBits"],
    );

    // Log the properties of the keys
    log(`publicKey: ${publicKey}`);
    log(` type: ${publicKey.type}`);
    log(` extractable: ${publicKey.extractable}`);
    log(` algorithm: ${JSON.stringify(publicKey.algorithm)}`);
    log(` usages: ${publicKey.usages}`);
    log(`privateKey: ${privateKey}`);
    log(` type: ${privateKey.type}`);
    log(` extractable: ${privateKey.extractable}`);
    log(` algorithm: ${JSON.stringify(privateKey.algorithm)}`);
    log(` usages: ${privateKey.usages}`);
  } catch (error) {
    log(error);
  }
}

结果

已创建密钥的信息记录在下面（如果浏览器不允许创建密钥，则为错误字符串）。

规范

规范
Web 密码学 API
# SubtleCrypto-method-generateKey

浏览器兼容性

BCD 表仅在启用 JavaScript 的浏览器中加载。

另请参阅