SubtleCrypto.generateKey()

语法

generateKey(algorithm, extractable, keyUsages)

参数

algorithm

一个对象，用于定义要生成的算法类型，并提供所需的参数。

• 对于 RSASSA-PKCS1-v1_5、RSA-PSS 或 RSA-OAEP 算法：传递 RsaHashedKeyGenParams 对象。
• 对于 ECDSA 或 ECDH 算法：传递 EcKeyGenParams 对象。
• 对于 HMAC 算法：传递 HmacKeyGenParams 对象。
• 对于 AES-CTR、AES-CBC、AES-GCM 或 AES-KW 算法：传递 AesKeyGenParams 对象。

extractable

一个布尔值，表示生成的密钥是否可被 SubtleCrypto.exportKey() 和 SubtleCrypto.wrapKey() 方法导出。

keyUsages

一个数组，表示生成出来的密钥可被用于做什么，数组元素可能的值有：

• encrypt：密钥可用于加密消息。
• decrypt：密钥可用于解密消息。
• sign：密钥可用于对消息进行签名。
• verify：密钥可用于验证签名。
• deriveKey：密钥可用于派生新的密钥。
• deriveBits：密钥可用于派生比特序列。
• wrapKey：密钥可用于包装一个密钥。
• unwrapKey：密钥可用于解开一个密钥的包装。

返回值

一个 Promise，会兑现为 CryptoKey（用于对称加密算法）或 CryptoKeyPair（用于非对称加密算法）。

异常

当发生以下几种异常时，promise 会被拒绝：

SyntaxError DOMException

当结果是类型为 secret 或 private 的加密密钥，但 keyUsages 参数为空时触发。

SyntaxError DOMException

当结果是加密密钥对，但它的 privateKey.usages 属性为空时触发。

示例

生成 RSA 密钥对

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

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 上查看完整代码。

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

生成 HMAC 密钥

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

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

生成 AES 密钥

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

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

规范

浏览器兼容性

参见

• 加密密钥长度的建议。
• NIST 过度使用的加密算法和密钥长度。