Skip to content

Commit 389a98b

Browse files
committed
fix(encryption): 完善 Encryption 模块的双语文档注释
- 为 AesHelper、XorHelper、RsaHelper、DsaHelper 添加英文翻译 - 为 Sm2Helper、Sm4Helper 添加英文翻译 - 为 SM2、SM3、SM4 算法实现类添加英文翻译 - 为 Cipher、GeneralDigest、Sm3Digest 添加英文翻译 - 为 Localization/Keys 添加英文翻译 - 统一使用双语格式:summary 中文,remarks 英文,param/returns 使用分隔符
1 parent ec8637a commit 389a98b

17 files changed

Lines changed: 994 additions & 410 deletions

File tree

GameFrameX.Foundation.Encryption/AesHelper.cs

Lines changed: 66 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -39,34 +39,61 @@
3939
namespace GameFrameX.Foundation.Encryption;
4040

4141
/// <summary>
42-
/// AES 加密解密
42+
/// AES 加密解密工具类,提供基于 AES-CBC 算法的加密和解密功能。
4343
/// </summary>
4444
/// <remarks>
45+
/// AES encryption and decryption utility class, providing encryption and decryption based on AES-CBC algorithm.
4546
/// 加密输出格式:[Salt(16 字节) | IV(16 字节) | 密文]
47+
/// Encryption output format: [Salt(16 bytes) | IV(16 bytes) | Ciphertext]
4648
/// Salt 和 IV 每次随机生成,与密文拼接存储,解密时自动从密文头部读取。
49+
/// Salt and IV are randomly generated each time, concatenated with the ciphertext for storage, and automatically read from the ciphertext header during decryption.
4750
/// 此格式与旧版本(固定 IV/Salt)不兼容。
51+
/// This format is incompatible with older versions (fixed IV/Salt).
4852
/// </remarks>
4953
public static class AesHelper
5054
{
51-
/// <summary>PBKDF2 迭代次数(符合 OWASP 2023 建议 600,000 次)</summary>
55+
/// <summary>
56+
/// PBKDF2 迭代次数(符合 OWASP 2023 建议 600,000 次)。
57+
/// </summary>
58+
/// <remarks>
59+
/// PBKDF2 iteration count (compliant with OWASP 2023 recommendation of 600,000).
60+
/// </remarks>
5261
private const int Pbkdf2Iterations = 600_000;
5362

54-
/// <summary>Salt 长度(字节)</summary>
63+
/// <summary>
64+
/// Salt 长度(字节)。
65+
/// </summary>
66+
/// <remarks>
67+
/// Salt length in bytes.
68+
/// </remarks>
5569
private const int SaltSize = 16;
5670

57-
/// <summary>IV 长度(字节)</summary>
71+
/// <summary>
72+
/// IV 长度(字节)。
73+
/// </summary>
74+
/// <remarks>
75+
/// IV length in bytes.
76+
/// </remarks>
5877
private const int IvSize = 16;
5978

60-
/// <summary>输出头部长度 = Salt + IV</summary>
79+
/// <summary>
80+
/// 输出头部长度 = Salt + IV。
81+
/// </summary>
82+
/// <remarks>
83+
/// Output header length = Salt + IV.
84+
/// </remarks>
6185
private const int HeaderSize = SaltSize + IvSize;
6286

6387
/// <summary>
64-
/// 使用 AES 算法加密字符串(输出 Base64 编码)
88+
/// 使用 AES 算法加密字符串(输出 Base64 编码)
6589
/// </summary>
66-
/// <param name="encryptString">待加密的明文字符串</param>
67-
/// <param name="encryptKey">加密密钥</param>
68-
/// <returns>加密后的 Base64 编码字符串,格式为 [Salt(16) | IV(16) | 密文] 的 Base64 表示</returns>
69-
/// <exception cref="ArgumentException">当明文或密钥为空时抛出</exception>
90+
/// <remarks>
91+
/// Encrypts a string using AES algorithm (output as Base64 encoding).
92+
/// </remarks>
93+
/// <param name="encryptString">待加密的明文字符串 / Plain text string to encrypt</param>
94+
/// <param name="encryptKey">加密密钥 / Encryption key</param>
95+
/// <returns>加密后的 Base64 编码字符串,格式为 [Salt(16) | IV(16) | 密文] 的 Base64 表示 / Base64 encoded encrypted string, format is Base64 representation of [Salt(16) | IV(16) | Ciphertext]</returns>
96+
/// <exception cref="ArgumentException">当明文或密钥为空时抛出 / Thrown when plain text or key is empty</exception>
7097
public static string Encrypt(string encryptString, string encryptKey)
7198
{
7299
if (string.IsNullOrEmpty(encryptString))
@@ -86,12 +113,16 @@ public static string Encrypt(string encryptString, string encryptKey)
86113
/// 使用 AES-CBC 算法加密字节数组。
87114
/// 每次加密随机生成 Salt 和 IV,输出格式:[Salt(16 字节) | IV(16 字节) | 密文]。
88115
/// </summary>
89-
/// <param name="encryptByte">待加密的明文字节数组</param>
90-
/// <param name="encryptKey">加密密钥,用于通过 PBKDF2(600,000 次) 派生密钥</param>
91-
/// <returns>加密后的字节数组,头部包含 Salt 和 IV</returns>
92-
/// <exception cref="ArgumentNullException">当明文字节数组为 null 时抛出</exception>
93-
/// <exception cref="ArgumentException">当明文字节数组为空或密钥为空时抛出</exception>
94-
/// <exception cref="CryptographicException">当加密过程失败时抛出</exception>
116+
/// <remarks>
117+
/// Encrypts a byte array using AES-CBC algorithm.
118+
/// Salt and IV are randomly generated for each encryption, output format: [Salt(16 bytes) | IV(16 bytes) | Ciphertext].
119+
/// </remarks>
120+
/// <param name="encryptByte">待加密的明文字节数组 / Plain text byte array to encrypt</param>
121+
/// <param name="encryptKey">加密密钥,用于通过 PBKDF2(600,000 次) 派生密钥 / Encryption key used to derive key via PBKDF2(600,000 iterations)</param>
122+
/// <returns>加密后的字节数组,头部包含 Salt 和 IV / Encrypted byte array with Salt and IV in the header</returns>
123+
/// <exception cref="ArgumentNullException">当明文字节数组为 null 时抛出 / Thrown when plain text byte array is null</exception>
124+
/// <exception cref="ArgumentException">当明文字节数组为空或密钥为空时抛出 / Thrown when plain text byte array is empty or key is empty</exception>
125+
/// <exception cref="CryptographicException">当加密过程失败时抛出 / Thrown when encryption process fails</exception>
95126
public static byte[] Encrypt(byte[] encryptByte, string encryptKey)
96127
{
97128
if (encryptByte == null)
@@ -136,13 +167,16 @@ public static byte[] Encrypt(byte[] encryptByte, string encryptKey)
136167
}
137168

138169
/// <summary>
139-
/// 使用 AES 算法解密字符串
170+
/// 使用 AES 算法解密字符串
140171
/// </summary>
141-
/// <param name="decryptString">待解密的 Base64 编码字符串(格式:[Salt(16) | IV(16) | 密文] 的 Base64 表示)</param>
142-
/// <param name="decryptKey">解密密钥,必须与加密时使用的密钥相同</param>
143-
/// <returns>解密后的明文字符串</returns>
144-
/// <exception cref="ArgumentException">当密文或密钥为空时抛出</exception>
145-
/// <exception cref="CryptographicException">当解密失败(如密钥错误或数据被篡改)时抛出</exception>
172+
/// <remarks>
173+
/// Decrypts a string using AES algorithm.
174+
/// </remarks>
175+
/// <param name="decryptString">待解密的 Base64 编码字符串(格式:[Salt(16) | IV(16) | 密文] 的 Base64 表示)/ Base64 encoded string to decrypt (format: Base64 representation of [Salt(16) | IV(16) | Ciphertext])</param>
176+
/// <param name="decryptKey">解密密钥,必须与加密时使用的密钥相同 / Decryption key, must be the same as the key used for encryption</param>
177+
/// <returns>解密后的明文字符串 / Decrypted plain text string</returns>
178+
/// <exception cref="ArgumentException">当密文或密钥为空时抛出 / Thrown when ciphertext or key is empty</exception>
179+
/// <exception cref="CryptographicException">当解密失败(如密钥错误或数据被篡改)时抛出 / Thrown when decryption fails (e.g., wrong key or data tampered)</exception>
146180
public static string Decrypt(string decryptString, string decryptKey)
147181
{
148182
if (string.IsNullOrEmpty(decryptString))
@@ -162,12 +196,16 @@ public static string Decrypt(string decryptString, string decryptKey)
162196
/// 使用 AES-CBC 算法解密字节数组。
163197
/// 期望输入格式:[Salt(16 字节) | IV(16 字节) | 密文],与 <see cref="Encrypt(byte[],string)"/> 输出格式对应。
164198
/// </summary>
165-
/// <param name="decryptByte">待解密的密文字节数组,头部须包含 Salt 和 IV</param>
166-
/// <param name="decryptKey">解密密钥,必须与加密时使用的密钥相同</param>
167-
/// <returns>解密后的明文字节数组</returns>
168-
/// <exception cref="ArgumentNullException">当密文字节数组为 null 时抛出</exception>
169-
/// <exception cref="ArgumentException">当密文长度不足或密钥为空时抛出</exception>
170-
/// <exception cref="CryptographicException">当解密失败(如密钥错误或数据被篡改)时抛出</exception>
199+
/// <remarks>
200+
/// Decrypts a byte array using AES-CBC algorithm.
201+
/// Expected input format: [Salt(16 bytes) | IV(16 bytes) | Ciphertext], corresponding to <see cref="Encrypt(byte[],string)"/> output format.
202+
/// </remarks>
203+
/// <param name="decryptByte">待解密的密文字节数组,头部须包含 Salt 和 IV / Ciphertext byte array to decrypt, must contain Salt and IV in the header</param>
204+
/// <param name="decryptKey">解密密钥,必须与加密时使用的密钥相同 / Decryption key, must be the same as the key used for encryption</param>
205+
/// <returns>解密后的明文字节数组 / Decrypted plain text byte array</returns>
206+
/// <exception cref="ArgumentNullException">当密文字节数组为 null 时抛出 / Thrown when ciphertext byte array is null</exception>
207+
/// <exception cref="ArgumentException">当密文长度不足或密钥为空时抛出 / Thrown when ciphertext length is insufficient or key is empty</exception>
208+
/// <exception cref="CryptographicException">当解密失败(如密钥错误或数据被篡改)时抛出 / Thrown when decryption fails (e.g., wrong key or data tampered)</exception>
171209
public static byte[] Decrypt(byte[] decryptByte, string decryptKey)
172210
{
173211
if (decryptByte == null)

0 commit comments

Comments
 (0)