3939namespace 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>
4953public 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