ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/cryptoUtils.md

@@ -0,0 +1,253 @@
+# 加密模块 (CryptoUtils)
+
+加密模块提供了常用的加密和解密功能，支持 AES、RSA 以及 MD5、SHA1、SHA256 等哈希算法。
+
+## 功能概览
+
+- **AES 加解密**: 支持 AES-ECB 模式的加密与解密
+- **RSA 加解密**: 支持 RSA 公钥加密与私钥解密
+- **哈希算法**: 支持 MD5, SHA1, SHA256 消息摘要计算
+
+## API 参考
+
+### AES 加解密
+
+#### encryptWithAES_ECB - 使用 AES ECB 模式加密数据
+
+默认使用 PKCS7 填充。
+
+```lua
+---@param data string
+---@param aesKey string
+---@param noPadding boolean?
+---@return string
+function encryptWithAES_ECB(data, aesKey, noPadding) end
+```
+
+**参数:**
+
+| 参数名      | 类型    | 是否必填 | 默认值 | 描述                                                                   |
+| ----------- | ------- | -------- | ------ | ---------------------------------------------------------------------- |
+| `data`      | string  | 是       |        | 要加密的数据                                                           |
+| `aesKey`    | string  | 是       |        | AES 密钥，支持 16 位、24 位、32 位字符串                               |
+| `noPadding` | boolean | 否       | false  | 是否禁用填充。`false`: 使用 PKCS7 填充; `true`: 不使用填充 (NoPadding) |
+
+**返回值:**
+
+| 类型     | 描述                             |
+| -------- | -------------------------------- |
+| `string` | 加密后的数据 (Base64 编码字符串) |
+
+**示例:**
+
+```lua
+local cryptoUtils = require("cryptoUtils")
+local data = "Hello World"
+local key = "1234567890123456"; -- 16位密钥
+local encrypted = cryptoUtils.encryptWithAES_ECB(data, key)
+print("AES Encrypted = " .. tostring(encrypted))
+```
+
+#### decryptWithAES_ECB - 使用 AES ECB 模式解密数据
+
+默认使用 PKCS7 填充。
+
+```lua
+---@param data string
+---@param aesKey string
+---@param noPadding boolean?
+---@return string
+function decryptWithAES_ECB(data, aesKey, noPadding) end
+```
+
+**参数:**
+
+| 参数名      | 类型    | 是否必填 | 默认值 | 描述                                                                   |
+| ----------- | ------- | -------- | ------ | ---------------------------------------------------------------------- |
+| `data`      | string  | 是       |        | 要解密的数据 (Base64 编码字符串)                                       |
+| `aesKey`    | string  | 是       |        | AES 密钥，支持 16 位、24 位、32 位字符串                               |
+| `noPadding` | boolean | 否       | false  | 是否禁用填充。`false`: 使用 PKCS7 填充; `true`: 不使用填充 (NoPadding) |
+
+**返回值:**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `string` | 解密后的原始数据 |
+
+**示例:**
+
+```lua
+local cryptoUtils = require("cryptoUtils")
+local encryptedData = "Base64EncodedString..."
+local key = "1234567890123456"
+local decrypted = cryptoUtils.decryptWithAES_ECB(encryptedData, key)
+print("AES Decrypted = " .. tostring(decrypted))
+```
+
+### RSA 加解密
+
+#### encryptWithRSA - 使用 RSA 公钥加密数据
+
+使用 PKCS1 填充。
+
+```lua
+---@param data string
+---@param rsaPublicKey string
+---@return string
+function encryptWithRSA(data, rsaPublicKey) end
+```
+
+**参数:**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述         |
+| -------------- | ------ | -------- | ------ | ------------ |
+| `data`         | string | 是       |        | 要加密的数据 |
+| `rsaPublicKey` | string | 是       |        | RSA 公钥     |
+
+**返回值:**
+
+| 类型     | 描述                             |
+| -------- | -------------------------------- |
+| `string` | 加密后的数据 (Base64 编码字符串) |
+
+**示例:**
+
+```lua
+local cryptoUtils = require("cryptoUtils")
+local data = "123456"
+local publicKey = "-----BEGIN PUBLIC KEY-----
+公钥内容
+-----END PUBLIC KEY-----
+"
+local encrypted = cryptoUtils.encryptWithRSA(data, publicKey)
+print("RSA Encrypted = " .. tostring(encrypted))
+```
+
+#### decryptWithRSA - 使用 RSA 私钥解密数据
+
+使用 PKCS1 填充。
+
+```lua
+---@param data string
+---@param rsaPrivateKey string
+---@return string
+function decryptWithRSA(data, rsaPrivateKey) end
+```
+
+**参数:**
+
+| 参数名          | 类型   | 是否必填 | 默认值 | 描述                             |
+| --------------- | ------ | -------- | ------ | -------------------------------- |
+| `data`          | string | 是       |        | 要解密的数据 (Base64 编码字符串) |
+| `rsaPrivateKey` | string | 是       |        | RSA 私钥                         |
+
+**返回值:**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `string` | 解密后的原始数据 |
+
+**示例:**
+
+```lua
+local cryptoUtils = require("cryptoUtils")
+local encryptedData = "加密后字符串"
+local privateKey = "-----BEGIN PRIVATE KEY-----
+私钥内容
+-----END PRIVATE KEY-----"
+local decrypted = cryptoUtils.decryptWithRSA(encryptedData, privateKey)
+print("RSA Decrypted = " .. tostring(decrypted))
+```
+
+### 哈希算法
+
+#### md5 - 计算 MD5 值
+
+```lua
+---@param data string
+---@return string
+function md5(data) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述              |
+| ------ | ------ | -------- | ------ | ----------------- |
+| `data` | string | 是       |        | 要计算 MD5 的数据 |
+
+**返回值:**
+
+| 类型     | 描述                            |
+| -------- | ------------------------------- |
+| `string` | MD5 哈希值 (小写 16 进制字符串) |
+
+**示例:**
+
+```lua
+local cryptoUtils = require("cryptoUtils")
+local data = "123456"
+local hash = cryptoUtils.md5(data)
+print("MD5 = " .. tostring(hash)); -- e10adc3949ba59abbe56e057f20f883e
+```
+
+#### sha1 - 计算 SHA1 值
+
+```lua
+---@param data string
+---@param key string?
+---@return string
+function sha1(data, key) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                       |
+| ------ | ------ | -------- | ------ | -------------------------- |
+| `data` | string | 是       |        | 要计算 SHA1 的数据         |
+| `key`  | string | 否       |        | 可选的密钥，用于 HMAC-SHA1 |
+
+**返回值:**
+
+| 类型     | 描述                             |
+| -------- | -------------------------------- |
+| `string` | SHA1 哈希值 (小写 16 进制字符串) |
+
+**示例:**
+
+```lua
+local cryptoUtils = require("cryptoUtils")
+local data = "123456"
+local hash = cryptoUtils.sha1(data)
+print("SHA1 = " .. tostring(hash))
+```
+
+#### sha256 - 计算 SHA256 值
+
+```lua
+---@param data string
+---@param key string?
+---@return string
+function sha256(data, key) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                         |
+| ------ | ------ | -------- | ------ | ---------------------------- |
+| `data` | string | 是       |        | 要计算 SHA256 的数据         |
+| `key`  | string | 否       |        | 可选的密钥，用于 HMAC-SHA256 |
+
+**返回值:**
+
+| 类型     | 描述                               |
+| -------- | ---------------------------------- |
+| `string` | SHA256 哈希值 (小写 16 进制字符串) |
+
+**示例:**
+
+```lua
+local cryptoUtils = require("cryptoUtils")
+local data = "123456"
+local hash = cryptoUtils.sha256(data)
+print("SHA256 = " .. tostring(hash))
+```