Web Crypto API

May 18, 2024

Web Crypto API 提供了 SubtleCrypto 接口，该接口提供一系列加密相关的静态函数。
这个接口通过 globalThis.crypto.subtle 暴露。

需要注意的是，这些函数是面向过程的：虽然密钥通过 CryptoKey 对象表示，但该对象只含描述该密钥的只读字段，不包含方法。
要使用密钥，需要将密钥通过参数提供给 SubtleCrypto 接口上的函数。

在下文中，为了简洁，对于 SubtleCrypto 接口上的静态函数，我们将做一些省略表示，即：
crypto.subtle.generateKey() 将表示为 generateKey()
此外，它们都是异步函数，即返回值都是 Promise，但下面将做一些省略。

Note

本文不涉及 Proposal webcrypto-secure-curves 中的算法。

生成 `CryptoKey` 对象

下面只考虑加密算法，因此密钥是必须的。

若没有已导出的密钥，则首先需要生成之：generateKey(algorithm, extractable, keyUsages)。

algorithm：若为对称加密，返回值是 CryptoKey；若为非对称加密，返回值是 CryptoKeyPair（只不过是包装了 privateKey 和 publicKey 属性的对象而已）
（详细参见 W3C 规范，哈希算法不包含在下表中。另外，这个表格的分类可能不够准确，另有分类参见后文）

加密类型	参数类型	算法名称	描述
非对称加密	RsaHashedKeyGenParams	RSASSA-PKCS1-v1_5	RSA Signature Scheme with Appendix - Public Key Cryptography Standards #1 version 1.5
		RSA-PSS	RSA - Probabilistic Signature Scheme
		RSA-OAEP	RSA - Optimal Asymmetric Encryption Padding
	EcKeyGenParams	ECDSA	Elliptic Curve Digital Signature Algorithm
	EcKeyGenParams	ECDH	Elliptic Curve Diffie-Hellman
对称加密	AesKeyGenParams	AES-CTR	AES Counter Mode
		AES-CBC	AES Cipher Block Chaining
		AES-GCM	AES Galois/Counter Mode
		AES-KW	AES Key Wrap
	HmacKeyGenParams	HMAC	Hash-based Message Authentication Code

extractable：布尔值，指定该密钥是否允许通过 exportKey() 或 wrapKey() 导出
keyUsages：字符串数组，指定该密钥是否可以执行以下操作：
- "encrypt": 使用 encrypt(algorithm, key, data) 对数据进行加密
- "decrypt": 使用 decrypt(algorithm, key, data) 对数据进行解密
- "sign": 使用 sign(algorithm, key, data) 对数据进行签名
- "verify": 使用 verify(algorithm, key, signature, data) 验证签名的有效性
- "deriveKey": 使用 deriveKey(algorithm, baseKey, derivedKeyType, extractable, keyUsages) 从现有密钥派生出新密钥
- "deriveBits": 使用 deriveBits(algorithm, baseKey, length) 从现有密钥派生出指定长度的位数据
- "wrapKey": 使用 wrapKey(format, key, wrappingKey, wrapAlgorithm) 将密钥包装成可导出格式
- "unwrapKey": 使用 unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgorithm, unwrappedKeyAlgorithm, extractable, keyUsages) 将包装好的密钥解包成可用的 CryptoKey

导出 `CryptoKey` 对象

为了能够使用 importKey() 函数导入密钥，首先还需要通过 exportKey() 将 generateKey() 生成的密钥导出：

exportKey(format, key) 函数将一个 CryptoKey 对象导出为指定格式的密钥数据

format：字符串，指定导出密钥的格式，即返回值取决于此参数。支持的格式包括：
- "raw"：用于导出对称密钥的原始字节数据
- "pkcs8"：Public-Key Cryptography Standards，用于导出非对称密钥对中的私钥，以 PKCS #8 格式表示
- "spki"：Simple Public Key Infrastructure，用于导出非对称密钥对中的公钥，以 X.509 Subject Public Key Info 格式表示
- "jwk"：用于导出密钥为 JSON Web Key 格式
key：一个 CryptoKey 对象，表示要导出的密钥

密钥本身只是一个字节数组，即 raw 格式为原始密钥的 ArrayBuffer。
jwk 格式可将密钥或密钥对表示为 JSON 文本格式（在 SubtleCrypto 接口中则是 JSONWebKey 对象）。
对称密钥没有其它包装的格式，即直接使用 raw 或通用的 jwk 格式即可。
对于非对称密钥：pkcs8 格式用于编码私钥，spki 格式用于编码公钥，它们都是 DER 编码的二进制格式（即 ArrayBuffer）。

导入 `CryptoKey` 对象

要将导出的密钥数据导入为 CryptoKey 对象，可以使用 importKey(format, keyData, algorithm, extractable, keyUsages) 函数。
该函数接收以下参数：

format：字符串，对应于 exportKey() 的 format 参数
keyData：对应于 exportKey() 的返回值
algorithm：对应于 generateKey() 的 algorithm 的参数
extractable：对应于 generateKey() 的 extractable 的参数
keyUsages：对应于 generateKey() 的 keyUsages 的参数

哈希算法

digest(algorithm: AlgorithmIdentifier, data: BufferSource): Promise<ArrayBuffer> 函数用于哈希。
algorithm 可以是 "SHA-1" "SHA-256" "SHA-384" 和 "SHA-512"

派生算法

派生指的是派生密钥（deriveKey()）和派生密码（deriveBits()）。

HKDF 和 PBKDF2 算法用于通过密码实现派生。
这两种算法虽然不是密钥，但是还是被抽象为了 CryptoKey，这样我们就有一个统一的 API。

const key: CryptoKey = await importKey(
    "raw",
    passwordBuffer, // 密码
    { name: "HKDF" || "PBKDF2" },
    false,
    ["deriveBits", "deriveKey"],
);

ECDH 本身则是专门用于派生的非对称密钥（只能用于 importKey 和 exportKey），所以它可以被生成（generateKey()）和导入（importKey()）

附：其它非对称密钥封装格式

DER

SPKI（Subject Public Key Info）和 PKCS#8 都是基于 ASN.1（Abstract Syntax Notation One）定义的结构。

ASN.1 结构本身只是结构而非二进制，而 DER（Distinguished Encoding Rules）是一种用于编码 ASN.1 结构的规则（二进制格式）。

PEM

PEM（Privacy-Enhanced Message）则是文本格式，它非常简单，只是通过 base64 编码二进制密钥而已，并不关心输入的密钥是原始格式还是其它二进制格式，但往往是 DER 格式。

该格式通常如下：

-----BEGIN XXX-----
base64字符串，可以换行但仅出于可读性
-----END XXX-----

其它参考

示例代码

https://github.com/diafygi/webcrypto-examples
https://github.com/mdn/dom-examples/tree/main/web-crypto

兼容性

Node.js 见：https://nodejs.org/api/webcrypto.html

Deno 见：https://deno.land/api?s=SubtleCrypto

YieldRay

Web Crypto API

Preview: