@fast-china/utils 2.0.0 → 2.0.3

package/dist/crypto/index.d.mts

@@ -1,16 +1,9 @@
+import "crypto-js/pad-ansix923.js";
 //#region src/crypto/index.d.ts
-/** 可直接哈希或比较的二进制输入。 */
-type TextOrBytes = string | Uint8Array;
-/** {@link encryptTextWithPassword} 的密钥派生选项。 */
-interface PasswordEncryptionOptions {
-  /**
-   * PBKDF2-HMAC-SHA-256 迭代次数，默认 `600_000`，允许 100,000 至 5,000,000。
-   * 低于默认值需要调用方基于目标硬件完成明确的安全与性能评估。
-   */
-  iterations?: number;
-}
-/** CryptoJS 兼容 AES 模式。 */
-type LegacyAesCipherMode = "CBC" | "ECB";
+/** AES 分组密码模式；与 .NET `CipherMode.CBC` 和 `CipherMode.ECB` 对应。 */
+type AesCipherMode = "CBC" | "ECB";
+/** AES 填充模式；与 .NET `PaddingMode` 中可由 CryptoJS 互操作的成员对应。 */
+type AesPaddingMode = "None" | "PKCS7" | "Zeros" | "ANSIX923" | "ISO10126";
 /** Web Crypto 导出的 PEM 公私钥对。 */
 interface PemKeyPair {
   /** 未加密的 PKCS#8 PEM 私钥，包含标准 `PRIVATE KEY` 头尾和 64 字符换行。 */
@@ -18,11 +11,6 @@ interface PemKeyPair {
   /** SubjectPublicKeyInfo PEM 公钥，包含标准 `PUBLIC KEY` 头尾和 64 字符换行。 */
   publicKey: string;
 }
-/** RSA-OAEP 密钥生成选项。 */
-interface RsaKeyPairOptions {
-  /** RSA 模数位数，默认 2048；必须是不小于 2048 的 256 倍数。 */
-  modulusLength?: number;
-}
 /** 本模块支持的 Web Crypto 椭圆曲线。 */
 type EcNamedCurve = "P-256" | "P-384" | "P-521";
 /**
@@ -32,7 +20,33 @@ type EcNamedCurve = "P-256" | "P-384" | "P-521";
  * @returns 新建的 `Uint8Array`。
  * @throws 参数非法时抛出 `RangeError`；缺少 Web Crypto 时抛出 `Error`。
  */
-declare function generateRandomBytes(length: number): Uint8Array;
+declare function GenerateRandomBytes(length: number): Uint8Array;
+/**
+ * 以不提前退出的方式比较两个字节数组。
+ *
+ * @remarks JavaScript 引擎不保证严格常量时间；该函数只避免显式短路，不能替代服务端
+ * 密码学库提供的 timing-safe primitive。长度是否相同仍属于可观察信息。
+ * @param left - 第一字节序列。
+ * @param right - 第二字节序列。
+ * @returns 长度和每个字节均相同时返回 `true`。
+ */
+declare function FixedTimeEquals(left: Uint8Array, right: Uint8Array): boolean;
+/**
+ * 计算 MD5 摘要并返回小写十六进制文本。
+ *
+ * @remarks MD5 仅用于非安全的普通校验，不得用于密码、签名或抗碰撞场景。
+ * @param value - UTF-8 文本。
+ * @returns 32 字符小写十六进制摘要。
+ */
+declare function MD5Encrypt(value: string): string;
+/**
+ * 计算 SHA-1 摘要并返回大写十六进制文本。
+ *
+ * @remarks SHA-1 仅用于非安全的普通校验，不得用于密码、签名或抗碰撞场景。
+ * @param value - UTF-8 文本。
+ * @returns 40 字符大写十六进制摘要。
+ */
+declare function SHA1Encrypt(value: string): string;
 /**
  * 计算 SHA-256 摘要。
  *
@@ -41,117 +55,272 @@ declare function generateRandomBytes(length: number): Uint8Array;
  * @returns 32 字节摘要。
  * @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
  */
-declare function sha256Bytes(value: TextOrBytes): Promise<Uint8Array>;
+declare function SHA256Bytes(value: string): Promise<Uint8Array>;
 /**
  * 计算 SHA-256 并格式化为十六进制。
  *
  * @param value - UTF-8 字符串或原始字节。
- * @returns 64 字符小写十六进制文本。
+ * @returns 64 字符大写十六进制文本。
  * @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
  */
-declare function sha256Hex(value: TextOrBytes): Promise<string>;
+declare function SHA256Encrypt(value: string): Promise<string>;
 /**
- * 计算 MD5 摘要并返回小写十六进制文本。
+ * 计算 SHA-384 摘要。
  *
- * @remarks MD5 仅用于历史协议和非安全校验，不得用于密码、签名或抗碰撞场景。
- * @param value - UTF-8 文本。
- * @returns 32 字符小写十六进制摘要。
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 48 字节摘要。
  */
-declare function md5Hex(value: string): string;
+declare function SHA384Bytes(value: string): Promise<Uint8Array>;
 /**
- * 计算 SHA-1 摘要并返回小写十六进制文本。
+ * 计算 SHA-384 并格式化为十六进制文本。
  *
- * @remarks SHA-1 仅用于旧系统互通；新用途应使用 {@link sha256Hex}。
- * @param value - UTF-8 文本。
- * @returns 40 字符小写十六进制摘要。
- */
-declare function sha1Hex(value: string): string;
-/**
- * 使用 AES-256-CBC 与 PKCS#7 填充加密文本。
- *
- * @remarks 密钥按 UTF-8 文本补齐或截断为 32 个字符，IV 补齐或截断为 16 个字符。
- * 该格式不包含认证标签；新数据优先使用 {@link encryptTextWithPassword}。
- * @param plaintext - UTF-8 明文。
- * @param key - 兼容密钥文本。
- * @param vector - 兼容初始化向量文本。
- * @returns CryptoJS Base64 密文。
- */
-declare function encryptLegacyAesCbc(plaintext: string, key: string, vector: string): string;
-/** 解密 {@link encryptLegacyAesCbc} 生成的 CryptoJS Base64 密文。 */
-declare function decryptLegacyAesCbc(ciphertext: string, key: string, vector: string): string;
-/**
- * 使用 AES-256-ECB 与 PKCS#7 填充加密文本。
- *
- * @remarks ECB 会暴露重复明文块结构，只能用于必须兼容的旧协议，不得用于新数据设计。
- * @param plaintext - UTF-8 明文。
- * @param key - 兼容密钥文本，补齐或截断为 32 个字符。
- * @returns CryptoJS Base64 密文。
- */
-declare function encryptLegacyAesEcb(plaintext: string, key: string): string;
-/** 解密 {@link encryptLegacyAesEcb} 生成的 CryptoJS Base64 密文。 */
-declare function decryptLegacyAesEcb(ciphertext: string, key: string): string;
-/** 生成可导出的 RSA-OAEP/SHA-256 PEM 密钥对。 */
-declare function generateRsaOaepKeyPair(options?: RsaKeyPairOptions): Promise<PemKeyPair>;
-/** 使用 RSA-OAEP/SHA-256 公钥加密 UTF-8 文本，并返回 Base64 密文。 */
-declare function encryptRsaOaep(plaintext: string, publicKeyPem: string): Promise<string>;
-/** 使用 RSA-OAEP/SHA-256 私钥解密 Base64 密文。 */
-declare function decryptRsaOaep(ciphertext: string, privateKeyPem: string): Promise<string>;
-/** 生成 ECDSA PEM 签名密钥对。 */
-declare function generateEcdsaKeyPair(namedCurve?: EcNamedCurve): Promise<PemKeyPair>;
-/** 使用 ECDSA 私钥签名文本或字节，并返回 Base64 签名。 */
-declare function signEcdsa(value: TextOrBytes, privateKeyPem: string, namedCurve?: EcNamedCurve): Promise<string>;
-/** 使用 ECDSA 公钥验证 Base64 签名。 */
-declare function verifyEcdsa(value: TextOrBytes, signature: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<boolean>;
-/** 生成 ECDH PEM 密钥协商密钥对。 */
-declare function generateEcdhKeyPair(namedCurve?: EcNamedCurve): Promise<PemKeyPair>;
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 96 个大写十六进制字符组成的摘要。
+ */
+declare function SHA384Encrypt(value: string): Promise<string>;
 /**
- * 使用本方 ECDH 私钥与对方 ECDH 公钥派生共享秘密。
+ * 计算 SHA-512 摘要。
  *
- * @remarks 返回值仍需经过合适的 KDF 后才能作为对称密钥，不应直接长期存储。
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 64 字节摘要。
  */
-declare function deriveEcdhSecret(privateKeyPem: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<Uint8Array>;
+declare function SHA512Bytes(value: string): Promise<Uint8Array>;
 /**
- * 以不提前退出的方式比较两个字节数组。
+ * 计算 SHA-512 并格式化为十六进制文本。
  *
- * @remarks JavaScript 引擎不保证严格常量时间；该函数只避免显式短路，不能替代服务端
- * 密码学库提供的 timing-safe primitive。长度是否相同仍属于可观察信息。
- * @param left - 第一字节序列。
- * @param right - 第二字节序列。
- * @returns 长度和每个字节均相同时返回 `true`。
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 128 个大写十六进制字符组成的摘要。
+ */
+declare function SHA512Encrypt(value: string): Promise<string>;
+/**
+ * 使用 HMAC-SHA-256 认证文本，并返回十六进制标签。
+ *
+ * @param value - 要认证的 UTF-8 文本或原始字节。
+ * @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+ * @returns 64 个小写十六进制字符组成的认证标签。
+ */
+declare function HMACSHA256Encrypt(value: string, key: string): Promise<string>;
+/**
+ * 使用 HMAC-SHA-384 认证文本或字节，并返回十六进制标签。
+ *
+ * @param value - 要认证的 UTF-8 文本或原始字节。
+ * @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+ * @returns 96 个小写十六进制字符组成的认证标签。
+ */
+declare function HMACSHA384Encrypt(value: string, key: string): Promise<string>;
+/**
+ * 使用 HMAC-SHA-512 认证文本或字节，并返回十六进制标签。
+ *
+ * @param value - 要认证的 UTF-8 文本或原始字节。
+ * @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+ * @returns 128 个小写十六进制字符组成的认证标签。
+ */
+declare function HMACSHA512Encrypt(value: string, key: string): Promise<string>;
+/**
+ * 使用 PBKDF2-HMAC-SHA-256 从密码派生密钥。
+ *
+ * @param password - 1 至 1,024 UTF-8 字节的密码。
+ * @param salt - 至少 8 字节的盐。
+ * @param iterations - 迭代次数，范围为 100,000 至 5,000,000。
+ * @param outputLength - 输出长度，范围为 1 至 1,024 字节。
+ * @returns 指定长度的派生密钥。
+ * @throws 参数超过协议边界时抛出 `TypeError` 或 `RangeError`。
+ */
+declare function PBKDF2SHA256(password: string, salt: Uint8Array, iterations?: number, outputLength?: number): Promise<Uint8Array>;
+/**
+ * 生成可持久化的随机盐 PBKDF2-HMAC-SHA-256 密码哈希。
+ *
+ * @param password - 1 至 1,024 UTF-8 字节的密码。
+ * @param iterations - 迭代次数，范围为 100,000 至 5,000,000。
+ * @returns 包含版本、迭代次数、16 字节随机盐和 32 字节派生密钥的自描述字符串。
+ */
+declare function HashPasswordPBKDF2SHA256(password: string, iterations?: number): Promise<string>;
+/**
+ * 验证 {@link HashPasswordPBKDF2SHA256} 生成的密码哈希。
+ *
+ * @param password - 要验证的密码。
+ * @param passwordHash - 自描述的 PBKDF2-HMAC-SHA-256 密码哈希。
+ * @returns 格式有效且密码匹配时返回 `true`；格式无效或密码错误时返回 `false`。
+ */
+declare function VerifyPasswordPBKDF2SHA256(password: string, passwordHash: string): Promise<boolean>;
+/**
+ * 使用 RFC 5869 HKDF-SHA-256 派生上下文隔离的密钥材料。
+ *
+ * @param inputKeyMaterial - 输入密钥材料，例如 ECDH 原始共享秘密。
+ * @param salt - 可选盐；空值按 RFC 5869 的零盐语义处理。
+ * @param info - 应用、协议和密钥用途上下文。
+ * @param outputLength - 输出长度，范围为 1 至 8,160 字节。
+ * @returns 与 `salt` 和 `info` 绑定的派生密钥。
+ */
+declare function HKDFSHA256(inputKeyMaterial: Uint8Array, salt?: Uint8Array, info?: Uint8Array, outputLength?: number): Promise<Uint8Array>;
+/**
+ * 使用 AES-256 对 UTF-8 文本进行分组加密。
+ *
+ * @remarks 密钥和 IV 分别补字符 `f` 或截断到 32、16 个 UTF-16 Code Unit，与 .NET
+ * `AESEncrypt` 保持一致。CBC/ECB 不提供完整性认证，密文可能被篡改。
+ * @param dataStr - 要加密的 UTF-8 文本；空白文本返回 `null`。
+ * @param key - 非空白的密钥文本。
+ * @param vector - 非空白的初始化向量文本；ECB 模式仍要求传入该参数以对齐 .NET 签名。
+ * @param cipherMode - AES 分组模式，默认 `CBC`。
+ * @param paddingMode - AES 填充模式，默认 `PKCS7`。
+ * @returns Base64 密文；输入、密钥或 IV 为空白时返回 `null`。
+ * @throws 模式或填充不受支持时抛出 `RangeError`。
+ */
+declare function AESEncrypt(dataStr: string, key: string, vector: string, cipherMode?: AesCipherMode, paddingMode?: AesPaddingMode): string | null;
+/**
+ * 使用 AES-256 解密 Base64 分组密文。
+ *
+ * @remarks 参数归一化规则与 {@link AESEncrypt} 以及 .NET `AESDecrypt` 相同。
+ * @param dataStr - Base64 密文；空白文本返回 `null`。
+ * @param key - 加密时使用的密钥文本。
+ * @param vector - 加密时使用的初始化向量文本。
+ * @param cipherMode - AES 分组模式，默认 `CBC`。
+ * @param paddingMode - AES 填充模式，默认 `PKCS7`。
+ * @returns 解密后的 UTF-8 文本；输入、密钥或 IV 为空白时返回 `null`。
+ * @throws 模式、填充、Base64、密钥或密文无效时抛出错误。
+ */
+declare function AESDecrypt(dataStr: string, key: string, vector: string, cipherMode?: AesCipherMode, paddingMode?: AesPaddingMode): string | null;
+/**
+ * 使用 SHA-256 归一化文本密钥，再以 AES-256-GCM 认证加密 UTF-8 文本。
+ *
+ * @remarks 输出与 .NET `AESEncryptAuthenticated` 的 v1 Base64 二进制载荷完全一致。
+ * @param plaintext - 要加密的 UTF-8 文本。
+ * @param key - 非空的 UTF-8 文本密钥；内部归一化为 32 字节 SHA-256 摘要。
+ * @returns Base64 编码的 v1 AES-GCM 认证载荷。
+ * @throws 密钥为空或运行时缺少 Web Crypto 时抛出错误。
  */
-declare function areBytesEqualWithoutEarlyExit(left: Uint8Array, right: Uint8Array): boolean;
+declare function AESEncryptAuthenticated(plaintext: string, key: string): Promise<string>;
+/**
+ * 解密并认证 .NET `AESEncryptAuthenticated` 或 {@link AESEncryptAuthenticated} 生成的载荷。
+ *
+ * @param payload - Base64 编码的 v1 AES-GCM 二进制载荷。
+ * @param key - 加密时使用的非空 UTF-8 文本密钥。
+ * @returns 通过认证的 UTF-8 明文。
+ * @throws 载荷格式无效、密钥错误或认证失败时抛出错误。
+ */
+declare function AESDecryptAuthenticated(payload: string, key: string): Promise<string>;
 /**
  * 使用 PBKDF2-HMAC-SHA-256 派生密钥，再以 AES-256-GCM 认证加密 UTF-8 文本。
  *
- * @remarks 每次调用生成独立 16 字节盐与 12 字节 IV。输出是本库 v2 自描述载荷，
- * 不应被拆分、修改或当作跨语言标准格式。密码加密不替代密钥管理；长期高价值数据
- * 应使用平台 KMS 或专门的加密方案。
+ * @remarks 每次调用生成独立 16 字节盐与 12 字节 IV。输出是与 .NET `AESEncryptWithPassword`
+ * 一致的 v1 自描述载荷，不应由业务代码手动拆分或修改。密码加密不替代密钥管理。
  * @param plaintext - 原始文本，不进行 JSON 推断；UTF-8 编码后最大 8 MiB。
  * @param password - 1 至 1024 UTF-8 字节的秘密口令。
- * @param options - PBKDF2 工作因子。
+ * @param iterations - PBKDF2 工作因子，默认 600,000。
  * @returns 认证密文字符串；相同输入每次产生不同结果。
  * @throws 口令非法时抛出 `TypeError` 或 `RangeError`；明文过大时抛出 `RangeError`；
  * 运行时缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
  */
-declare function encryptTextWithPassword(plaintext: string, password: string, options?: PasswordEncryptionOptions): Promise<string>;
+declare function AESEncryptWithPassword(plaintext: string, password: string, iterations?: number): Promise<string>;
 /**
- * 解密 {@link encryptTextWithPassword} 生成的 v2 认证载荷。
+ * 解密 {@link AESEncryptWithPassword} 生成的 v1 认证载荷。
  *
- * @param payload - 未修改的 v2 载荷，最大约 16 MiB 文本。
+ * @param payload - 未修改的 v1 载荷，最大约 16 MiB 文本。
  * @param password - 加密时使用的口令。
  * @returns 原始 UTF-8 文本。
  * @throws 格式或字段非法时抛出 `TypeError`，载荷过大时抛出 `RangeError`，认证或密码
  * 失败及缺少平台能力时抛出 `Error`。
  */
-declare function decryptTextWithPassword(payload: string, password: string): Promise<string>;
-/** 解密历史 AES-CBC/ECB 字符串，并优先解析 JSON 结果。 */
-declare function decryptLegacyAesValue<Result = string>(dataStr: string, key: string, vector: string, cipherMode?: LegacyAesCipherMode): Result | null;
-/** 按指定 CBC/ECB 模式加密历史 AES 字符串。 */
-declare function encryptLegacyAes(dataStr: string, key: string, vector: string, cipherMode?: LegacyAesCipherMode): string;
-/** 返回历史兼容的大写 MD5 十六进制摘要。 */
-declare function md5UpperHex(value: string): string;
-/** 返回历史兼容的大写 SHA-1 十六进制摘要。 */
-declare function sha1UpperHex(value: string): string;
+declare function AESDecryptWithPassword(payload: string, password: string): Promise<string>;
+/**
+ * 生成可供 RSA-OAEP/SHA-256 与 RSA-PSS/SHA-256 共用的 PEM 密钥对。
+ *
+ * @param modulusLength - RSA 模数位数，默认 2,048；必须是不小于 2,048 的 256 倍数。
+ * @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+ * @throws 模数小于 2,048 或不是 256 的倍数时抛出 `RangeError`。
+ */
+declare function GenerateRSAKeyPair(modulusLength?: number): Promise<PemKeyPair>;
+/**
+ * 使用 RSA-OAEP/SHA-256 公钥加密 UTF-8 文本。
+ *
+ * @param plaintext - 要加密的 UTF-8 文本；长度必须满足 RSA-OAEP 模数限制。
+ * @param publicKeyPem - SubjectPublicKeyInfo PEM 公钥。
+ * @returns Base64 编码的 RSA 密文。
+ * @throws 公钥格式无效或明文超过 RSA-OAEP 容量时抛出错误。
+ */
+declare function RSAEncryptOAEP(plaintext: string, publicKeyPem: string): Promise<string>;
+/**
+ * 使用 RSA-OAEP/SHA-256 私钥解密 Base64 密文。
+ *
+ * @param ciphertext - Base64 编码的 RSA 密文。
+ * @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥。
+ * @returns 解密后的 UTF-8 文本。
+ * @throws 私钥、Base64 或密文无效时抛出错误。
+ */
+declare function RSADecryptOAEP(ciphertext: string, privateKeyPem: string): Promise<string>;
+/**
+ * 使用 RSA-PSS/SHA-256 私钥签名文本或字节。
+ *
+ * @param value - 要签名的 UTF-8 文本或原始字节。
+ * @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥。
+ * @returns Base64 编码的 RSA-PSS 签名；盐长度固定为 32 字节。
+ * @throws 私钥格式无效或签名失败时抛出错误。
+ */
+declare function RSASignPSS(value: string, privateKeyPem: string): Promise<string>;
+/**
+ * 使用 RSA-PSS/SHA-256 公钥验证 Base64 签名。
+ *
+ * @param value - 签名时使用的 UTF-8 文本或原始字节。
+ * @param signature - Base64 编码的 RSA-PSS 签名。
+ * @param publicKeyPem - SubjectPublicKeyInfo PEM 公钥。
+ * @returns 签名与内容、公钥匹配时返回 `true`。
+ * @throws 公钥或 Base64 格式无效时抛出错误。
+ */
+declare function RSAVerifyPSS(value: string, signature: string, publicKeyPem: string): Promise<boolean>;
+/**
+ * 生成 ECDSA PEM 签名密钥对。
+ *
+ * @param namedCurve - NIST 曲线：P-256、P-384 或 P-521。
+ * @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+ */
+declare function GenerateECDSAKeyPair(namedCurve?: EcNamedCurve): Promise<PemKeyPair>;
+/**
+ * 使用 ECDSA 私钥签名文本或字节。
+ *
+ * @remarks Web Crypto 返回 IEEE P1363 固定字段拼接格式，与 .NET 实现一致。
+ * @param value - 要签名的 UTF-8 文本或原始字节。
+ * @param privateKeyPem - 未加密的 EC PKCS#8 PEM 私钥。
+ * @param namedCurve - 私钥使用的 NIST 曲线。
+ * @returns Base64 编码的 IEEE P1363 ECDSA 签名。
+ */
+declare function ECDSASign(value: string, privateKeyPem: string, namedCurve?: EcNamedCurve): Promise<string>;
+/**
+ * 使用 ECDSA 公钥验证 Base64 签名。
+ *
+ * @param value - 签名时使用的 UTF-8 文本或原始字节。
+ * @param signature - Base64 编码的 IEEE P1363 ECDSA 签名。
+ * @param publicKeyPem - EC SubjectPublicKeyInfo PEM 公钥。
+ * @param namedCurve - 公钥使用的 NIST 曲线。
+ * @returns 签名与内容、公钥和曲线匹配时返回 `true`。
+ */
+declare function ECDSAVerify(value: string, signature: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<boolean>;
+/**
+ * 生成 ECDH PEM 密钥协商密钥对。
+ *
+ * @param namedCurve - NIST 曲线：P-256、P-384 或 P-521。
+ * @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+ */
+declare function GenerateECDHKeyPair(namedCurve?: EcNamedCurve): Promise<PemKeyPair>;
+/**
+ * 使用本方 ECDH 私钥与对方 ECDH 公钥派生共享秘密。
+ *
+ * @remarks 返回值仍需经过合适的 KDF 后才能作为对称密钥，不应直接长期存储。
+ * @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥。
+ * @param publicKeyPem - 对方的 EC SubjectPublicKeyInfo PEM 公钥。
+ * @param namedCurve - 双方密钥使用的 NIST 曲线。
+ * @returns 曲线字段长度的原始 ECDH 共享秘密。
+ */
+declare function DeriveECDHSecret(privateKeyPem: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<Uint8Array>;
+/**
+ * 使用 ECDH 后以 SHA-256 派生共享密钥。
+ *
+ * @remarks 相比直接使用原始共享秘密，此入口与 .NET `DeriveECDHKeySHA256` 一致并固定输出 32 字节。
+ * @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥。
+ * @param publicKeyPem - 对方的 EC SubjectPublicKeyInfo PEM 公钥。
+ * @param namedCurve - 双方密钥使用的 NIST 曲线。
+ * @returns 32 字节共享密钥。
+ */
+declare function DeriveECDHKeySHA256(privateKeyPem: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<Uint8Array>;
 //#endregion
-export { EcNamedCurve, LegacyAesCipherMode, PasswordEncryptionOptions, PemKeyPair, RsaKeyPairOptions, TextOrBytes, areBytesEqualWithoutEarlyExit, decryptLegacyAesCbc, decryptLegacyAesEcb, decryptLegacyAesValue, decryptRsaOaep, decryptTextWithPassword, deriveEcdhSecret, encryptLegacyAes, encryptLegacyAesCbc, encryptLegacyAesEcb, encryptRsaOaep, encryptTextWithPassword, generateEcdhKeyPair, generateEcdsaKeyPair, generateRandomBytes, generateRsaOaepKeyPair, md5Hex, md5UpperHex, sha1Hex, sha1UpperHex, sha256Bytes, sha256Hex, signEcdsa, verifyEcdsa };
+export { AESDecrypt, AESDecryptAuthenticated, AESDecryptWithPassword, AESEncrypt, AESEncryptAuthenticated, AESEncryptWithPassword, AesCipherMode, AesPaddingMode, DeriveECDHKeySHA256, DeriveECDHSecret, ECDSASign, ECDSAVerify, EcNamedCurve, FixedTimeEquals, GenerateECDHKeyPair, GenerateECDSAKeyPair, GenerateRSAKeyPair, GenerateRandomBytes, HKDFSHA256, HMACSHA256Encrypt, HMACSHA384Encrypt, HMACSHA512Encrypt, HashPasswordPBKDF2SHA256, MD5Encrypt, PBKDF2SHA256, PemKeyPair, RSADecryptOAEP, RSAEncryptOAEP, RSASignPSS, RSAVerifyPSS, SHA1Encrypt, SHA256Bytes, SHA256Encrypt, SHA384Bytes, SHA384Encrypt, SHA512Bytes, SHA512Encrypt, VerifyPasswordPBKDF2SHA256 };
 //# sourceMappingURL=index.d.mts.map