做C#开发这些年，加密解密基本是绕不开的活儿。不管是给客户交付桌面软件，还是写内部工具，总要处理数据库连接串保护、接口签名校验、文件校验和这类需求。很多时候不是不会写，而是每次都要翻资料、拼代码，甚至从老项目里拷贝一堆到处散落的类，改吧改吧凑合用。踩过的坑多了，我就萌生了一个念头：把日常用到的加密解密封装成一套独立的工具集，源码和类库文件都齐活，谁用谁拿。这篇文章就聊聊这套工具集的设计思路、核心模块、关键实现，以及我在实际项目中反复调整后总结的经验。

这套工具集能解决什么问题呢？简单说，就是把散落各处的常用密码学操作统一收拢，提供标准化调用入口。它包含哈希计算、对称加密、非对称加密、编码转换、文件摘要等模块，既能以源码形式嵌入项目，也能编译成类库DLL直接引用。适合刚入门的开发者快速上手，也适合团队统一加密逻辑，避免每个人写出来的算法五花八门、密钥管理随性而为。

1. 内容设计与方案选型：为什么单独做一套工具集

1.1 项目起步时的真实痛点

我在维护一个老项目时，光是连接字符串加密就有三套不同写法。有的用MD5只做哈希，有的用DES硬编码密钥，还有的直接把明文放到配置里。发生过两次尴尬情况：一次是客户要求升级安全策略，结果发现老数据根本解不出来；另一次是同事离职后，留下一段自定义加密代码，谁也没看懂逻辑。那会儿我就意识到，加密解密不是“能跑就行”的小事，必须有统一封装、明确算法选择、可维护的版本。

这套工具集的定位很明确：不追求“颠覆性创新”，而是把.NET平台上成熟、稳定的密码学能力封装成友好接口。选型上坚持三个原则：

• 默认算法向现代标准看齐，优先AES、SHA-256、RSA，非必要不用DES、MD5这类弱算法。
• 所有密钥、向量、盐值等参数必须有明确约定，不能靠“手填一个字符串碰运气”。
• 提供源码和类库两种形态，方便不同项目的集成方式。

1.2 为什么不用第三方加密库

调研的时候有人推荐引入第三方加密库，功能确实强大。但我最终放弃了，原因很实际：很多企业项目对第三方依赖管控严格，安全审计时要解释每个引用的来源；另外常规业务根本用不到那些超复杂特性，.NET自带的System.Security.Cryptography已经足够。自己封装的好处是可控性强，出问题能直接改源码。坏处是需要花心思设计接口和边界，毕竟密码学代码容不得半点马虎。

还有个重要考虑：不同项目用的.NET版本不同。有老框架下的，也有新环境的。所以工具集分两层，核心算法层保持纯净，只依赖标准运行库；外围辅助层负责字符串转换、文件处理、日志记录等平台相关功能。这种分层让核心层可以快速移植。

1.3 功能范围与边界定义

起初我想把所有密码学相关功能都塞进去，后来收住了。过度设计只会让工具集臃肿难用。最终确定六个核心模块：

• 哈希摘要：MD5、SHA1、SHA256、SHA384、SHA512、HMAC系列。
• 对称加密：AES、DES（兼容老数据）、3DES，支持ECB/CBC/CFB等常见模式。
• 非对称加密：RSA密钥生成、加密解密、签名验签。
• 编码转换：Base64、Hex等常用编码，以及URL安全的编码处理。
• 文件工具：文件哈希校验、大文件分段加解密。
• 辅助工具：随机数生成、密钥派生、常量定义等。

边界则是：不处理密钥交换协议、不实现TLS通信、不做证书生命周期管理。这些属于专业安全框架的范畴，工具集只需要提供基础的密钥生成和加解密能力，往上层应用去各自组合。

2. 核心模块解析与实操要点

2.1 哈希模块：不只是算个摘要

哈希模块是整个工具集里最简单也最容易用错的部分。很多新手以为MD5就是“加密”，其实哈希是单向的，不可逆。它的价值在于数据完整性校验和口令存储（配合盐值）。我在工具集里提供了一套统一方法：

public static string ComputeHash(string input, HashAlgorithmType type = HashAlgorithmType.SHA256) { using (var algorithm = HashAlgorithmFactory.Create(type)) { byte[] bytes = Encoding.UTF8.GetBytes(input); byte[] hash = algorithm.ComputeHash(bytes); return Convert.ToHexString(hash); } }

这里有个细节需要注意：如果直接用Encoding.Default获取字节，在不同操作系统上可能得到不同结果。尤其涉及中文时，必须明确使用UTF-8。老项目里出现过Linux和Windows下哈希结果不一致的bug，其实就是编码问题。

对于口令存储，工具集额外提供PBKDF2派生方案：

public static string HashPassword(string password, byte[] salt, int iterations = 10000) { using (var deriveBytes = new Rfc2898DeriveBytes(password, salt, iterations, HashAlgorithmName.SHA256)) { return Convert.ToBase64String(deriveBytes.GetBytes(32)); } }

迭代次数不是越大越好，要考虑目标机器的性能。我一般取10000到100000之间，既要拖慢暴力破解，又不能让自己接口响应慢得离谱。实际项目中，用户登录接口控制在200毫秒内比较合适。

HMAC也是容易混淆的点。HMAC与普通哈希的区别在于它掺入了密钥，用于校验消息在传输过程中是否被篡改，比如Webhook签名。工具集里专门封装了ComputeHmac方法，密钥和消息都通过字节数组传入，避免字符串编码差异。

2.2 对称加密：AES为主力

对称加密是业务系统里用得最多的。工具集以AES为核心，密钥长度支持128、192、256位。我见过很多半路出家的代码，直接把密码字符串用Encoding.UTF8.GetBytes截断成密钥，这很危险。AES要求密钥必须是精确的16/24/32字节，并且为了安全，更推荐使用密钥派生函数从口令生成。工具集的做法是：

public static byte[] GenerateKeyFromPassword(string password, byte[] salt, int keySizeInBits = 256) { using (var deriveBytes = new Rfc2898DeriveBytes(password, salt, 10000, HashAlgorithmName.SHA256)) { return deriveBytes.GetBytes(keySizeInBits / 8); } }

对称加密的模式选择，我默认用CBC模式搭配随机IV。CBC需要填充，.NET默认PKCS7即可。CBC模式有个经典问题是“雪崩效应”不明显？其实CBC的缺点是加密不能并行，而且如果IV固定，相同明文会得到相同密文，容易被观察规律。所以IV必须每次随机生成，并随密文一起存储。工具集的实现里，密文格式统一为“IV + Cipher”，解密时自动去前16字节作为IV。

还有一个是ECB模式。我强烈建议新项目不要用ECB，因为它会导致相同明文块产生相同密文块，图形数据加密后仍能看出轮廓。工具集里保留ECB纯粹是为了解密历史遗留数据，并会在调用时输出警告。

public static byte[] AesEncrypt(byte[] plainBytes, byte[] key, byte[] iv, CipherMode mode = CipherMode.CBC) { using (var aes = Aes.Create()) { aes.Key = key; aes.IV = iv; aes.Mode = mode; aes.Padding = PaddingMode.PKCS7; using (var encryptor = aes.CreateEncryptor()) { return encryptor.TransformFinalBlock(plainBytes, 0, plainBytes.Length); } } }

这里特别提醒：TransformFinalBlock可以处理一次性数据，但如果数据很大，需要分块调用TransformBlock。工具集里对小于1GB的字节数组直接用前者，更大的数据走文件分段模块。

2.3 非对称加密：RSA签名与少量数据加密

RSA不是用来加密大块数据的。它运算慢，密文长度受密钥位数限制，2048位密钥最多加密245字节（去掉填充开销）。所以实际应用中，RSA常用来加密AES的密钥，这就是“混合加密”。工具集里单独提供RsaEncrypt和RsaDecrypt，注释里写清楚适用范围。

RSA密钥格式是个容易踩坑的地方。.NET里可以用ToXmlString导出XML格式，也可以导出PEM。现代跨平台场景更通用的是PEM和DER。工具集支持从PEM字符串导入私钥/公钥，这样方便与其他语言互通。

签名验签模块同样重要。接口请求方用私钥签名，接收方用公钥验签。这里要注意签名算法推荐使用RS256（SHA256withRSA），不要再使用SHA1。示例：

public static string SignData(string data, string privateKeyPem) { using (var rsa = RSA.Create()) { rsa.ImportFromPem(privateKeyPem.ToCharArray()); byte[] dataBytes = Encoding.UTF8.GetBytes(data); byte[] signature = rsa.SignData(dataBytes, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1); return Convert.ToBase64String(signature); } }

签名时有个细节：签名是对“原文”的哈希做加密，但绝不是“加密原文摘要”这么简单，标准填充很重要。别自己去实现“取哈希后调用RSA加密”，那会破坏ASN.1结构和填充格式，导致其他语言验签失败。必须用SignData/VerifyData这类标准API。

2.4 编码转换：连接字符串和文件的桥梁

Base64和Hex是加密场景中最基础的编码。密文、密钥、签名结果都是二进制字节，不可能直接存到配置或JSON里，必须转成可打印字符串。工具集提供两个核心方法：

public static string ToBase64(byte[] bytes) { return Convert.ToBase64String(bytes); } public static byte[] FromBase64(string text) { return Convert.FromBase64String(text); }

Base64有个变体叫“URL安全Base64”，它把+替换成-，把/替换成_，去掉末尾的=。这个在GET请求参数、JWT场景里非常有用，工具集里也有对应封装。还要注意Base64字符串长度可能不是4的倍数，某些接口需要填充，处理时不要自己写正则瞎改，标准库方法足够健壮。

Hex编码则用于查看二进制内容、生成文件校验值。以前的BitConverter.ToString(bytes).Replace("-", "")也能用，但.NET 5以上推荐Convert.ToHexString，性能更好，代码也更简洁。

3. 源码组织与类库封装：一套代码两种用法

3.1 项目结构规划

这套工具集采用多项目组织方式。核心库和扩展库分开，便于不同项目按需引用。

CryptoToolkit/ ├── CryptoToolkit.Core/ // 核心算法，不依赖具体平台 │ ├── Hash/ │ │ ├── HashAlgorithmFactory.cs │ │ ├── HashCalculator.cs │ │ └── PasswordHasher.cs │ ├── Symmetric/ │ │ ├── AesCrypto.cs │ │ ├── DesCrypto.cs │ │ └── SymmetricOptions.cs │ ├── Asymmetric/ │ │ ├── RsaCrypto.cs │ │ └── RsaKeyHelper.cs │ └── Encoding/ │ ├── Base64Helper.cs │ └── HexHelper.cs ├── CryptoToolkit.Extensions/ // 文件、流式处理、配置辅助 │ ├── FileCrypto.cs │ └── StringSecureExtensions.cs └── CryptoToolkit.Tests/ // 单元测试与向量验证

这个结构的好处是：核心层不带任何UI、配置、文件依赖，方便将来写AOT编译或者迁移到其他平台。扩展层专门处理文件和字符串包装，测试工程覆盖所有算法的基础向量测试。

3.2 类库文件的使用方式

编译后生成CryptoToolkit.Core.dll和CryptoToolkit.Extensions.dll。如果目标项目不允许引用DLL，也可以直接把源码文件拖进项目。我这里有两套方案：

方案一：引用类库

在Visual Studio的“添加引用”里选择编译好的DLL，然后在代码中using CryptoToolkit.Core;即可。好处是部署统一，升级工具集时只需替换DLL版本。

方案二：源码嵌入

如果有特殊的安全审计要求，希望所有代码可见、可编译进主程序，就把Core目录下的.cs文件复制进项目。此时需要保留源码文件中的namespace不变。需要注意，如果项目启用了强名称签名，直接编译源码可能需要调整程序集签名属性。

从维护角度看，引DLL更干净。但从审计角度看，源码嵌入更透明。我一般建议团队内部工具用源码嵌入，对外发布的标准产品用DLL引用。

3.3 统一入口reduce调用成本

为了让使用者少记类名，我设计了一个门面类CryptoFacade，把所有静态方法集中管理：

public static class CryptoFacade { public static string HashString(string input, HashAlgorithmType algorithm) => HashCalculator.ComputeHash(input, algorithm); public static byte[] AesEncrypt(byte[] data, byte[] key, byte[] iv) => AesCrypto.Encrypt(data, key, iv); public static byte[] AesDecrypt(byte[] data, byte[] key, byte[] iv) => AesCrypto.Decrypt(data, key, iv); public static string RsaSign(string data, string privateKeyPem) => RsaCrypto.Sign(data, privateKeyPem); public static bool RsaVerify(string data, string signatureBase64, string publicKeyPem) => RsaCrypto.Verify(data, signatureBase64, publicKeyPem); }

门面类减少了学习成本，但也要注意别变成大杂烩。所有方法有明确分组注释，XML文档写在每个方法上，IDE里悬停就能看到用法示例。

4. 实操过程与核心环节实现

4.1 生成AES密钥和IV并加解密字符串

常用的一种场景是“用口令加密配置项”。完整流程如下：

// 1. 生成随机盐，并保存用于后续派生同款密钥 byte[] salt = CryptoToolkit.Core.Helpers.RandomHelper.GenerateRandomBytes(16); // 2. 用口令派生256位密钥 byte[] key = PasswordHasher.DeriveKey("your-password", salt, 256); // 3. 加密 string plainText = "数据库连接字符串"; byte[] plainBytes = Encoding.UTF8.GetBytes(plainText); byte[] iv = RandomHelper.GenerateRandomBytes(16); byte[] cipherBytes = AesCrypto.Encrypt(plainBytes, key, iv); // 4. 组织存储格式：salt + iv + cipher，全部转为Base64 string result = Convert.ToBase64String(salt.Concat(iv).Concat(cipherBytes).ToArray()); // 5. 解密时反向切分 byte[] allBytes = Convert.FromBase64String(result); byte[] saltRecover = allBytes.Take(16).ToArray(); byte[] ivRecover = allBytes.Skip(16).Take(16).ToArray(); byte[] cipherRecover = allBytes.Skip(32).ToArray();

这一步“盐 + IV + 密文”打包一起存储是通用做法。如果不保存盐和IV，解密时根本无法恢复相同密钥或IV组合。很多半吊子代码把盐写死、IV设成全零，安全强度下降一大截。

实操中还有一个细节：口令强度很重要。就算有盐有迭代，如果口令是123456，暴力破解依然很快。工具集只提供技术能力，不约束用户密码策略，但在注释里写了建议：口令最少12位，包含大小写数字符号。

4.2 大文件分段加解密

文件加解密不能像小字符串那样一次性ReadAllBytes，动辄几个GB的文件会直接拖垮内存。工具集的FileCrypto采用分块方案：

const int BufferSize = 81920; // 80KB 缓冲区 public static void EncryptFile(string inputPath, string outputPath, byte[] key, byte[] iv) { using (var inputStream = File.OpenRead(inputPath)) using (var outputStream = File.Create(outputPath)) using (var aes = Aes.Create()) { aes.Key = key; aes.IV = iv; using (var encryptor = aes.CreateEncryptor()) using (var cryptoStream = new CryptoStream(outputStream, encryptor, CryptoStreamMode.Write)) { inputStream.CopyTo(cryptoStream, BufferSize); } } }

CryptoStream会自己处理分块和填充，省心不少。但要注意最后必须关闭CryptoStream，因为尾部填充块是在Dispose时写入的。有人只调用Flush，结果输出文件最后缺一段，怎么都解密失败。这类问题排查起来特别隐蔽。

大文件加密还有个边界问题：AES的CBC模式在解密时，如果密文在传输途中丢了一个字节，从那个位置开始后续数据全部解错。工具集提供“先算SHA256再加密”的推荐流程，解密后校验哈希就知道文件是否完整。

4.3 RSA密钥对生成与PEM导入导出

实际项目中经常要生成密钥对。工具集提供一行调用：

var (publicKeyPem, privateKeyPem) = RsaKeyHelper.GeneratePemKeyPair(2048);

这个方法内部先生成RSA.Create(2048)，然后把公钥导出SubjectPublicKeyInfo格式的PEM，私钥导出PKCS#8格式的PEM。这两个PEM字符串可以存到文件，注意私钥文件必须限制权限。Windows上可以设置ACL，Linux上建议chmod 600。

从PEM加载时有一个坑：某些老库生成的私钥是PKCS#1格式（以BEGIN RSA PRIVATE KEY开头），而ImportFromPem对PKCS#1和PKCS#8都能处理，但如果你手工拼接或截断，很容易破坏换行。推荐的做法是原样保存、原样读取，不要把PEM当成普通字符串替换回车。有些中间件要求PEM内每64个字符换行，工具集的RsaKeyHelper里专门做了ToPem格式化，对外输出统一换行，避免不同平台解析差异。

4.4 单元测试与算法向量验证

密码学改动最怕“看起来能用，换数据就崩”。工具集配套了大量测试用例，重点是使用标准测试向量。比如AES-128-ECB的官方向量，用NIST文档里固定的明文、密钥、密文来验证。如果计算结果不一致，说明实现有问题。测试工程里也包含Base64编解码的边界用例，包括空数组、长度不一的数组、包含非ASCII字符的字符串。

手动测试哈希时，推荐直接拿一个已知文件算一次哈希，再用certutil -hashfile（Windows）或sha256sum（Linux）交叉验证。工具集自己的哈希测试也会内置这些命令得到的结果作为对照。

编写测试的另一个意义是保护重构。算法代码一旦被后人“优化”，很可能无意间改变了填充或字节序。有了自动化验证，每次构建都跑一遍，至少能拦住低级错误。

5. 安全细节与常见问题排查实录

5.1 密钥存储的几种方案

加密算法本身安全，但如果密钥和密文放在一起，等同把保险柜钥匙贴在门上。我总结了几种密钥存储方式，按安全性从低到高排列：

• 放在代码里硬编码：最差，反编译即可看到。
• 放在单独的配置文件：稍微好一点，但配置文件泄露等于密钥泄露。
• 放在环境变量：适合服务器部署，但要注意环境变量在进程内可被读取。
• 使用操作系统的凭据管理器：Windows有DPAPI，Linux有Secret Service，安全性高。
• 使用硬件安全模块或云KMS：企业级方案，成本高。

工具集里对DPAPI做了简单封装，方便桌面程序保护本机密钥：

public static byte[]> ProtectWithCurrentUser(byte[] plainBytes) { return ProtectedData.Protect(plainBytes, null, DataProtectionScope.CurrentUser); } public static byte[]> UnprotectWithCurrentUser(byte[] encryptedBytes) { return ProtectedData.Unprotect(encryptedBytes, null, DataProtectionScope.CurrentUser); }

注意DPAPI加密的字节只能在同一用户账户下解密，不能跨机器迁移。如果要做多机部署，就需要换KMS方案。

5.2 常见问题排查速查表

这里最容易被忽视的是“填充无效”这个异常。它不光指数据不对，也可能是密钥错误。比如AES-CBC解密时，padding字段解密出来不是合法PKCS7，就会抛异常。有些人看到异常就怀疑算法，其实很可能密钥或IV错了。

5.3 审计与升级：如何平稳替换旧算法

历史系统里大量使用DES或MD5，不能一刀切全改。我采用“双算法过渡”模式：

• 解密保留旧算法，加密切换到新算法。
• 数据里增加版本标识前缀，比如v2:开头表示新格式，v1:表示旧格式。
• 迁移数据时批量读取老数据，用旧算法解密后重新用新算法加密。

工具集的CryptoFacade里预留了EncryptWithVersion和DecryptAutoDetect，后者自动根据前缀分派算法。这样老数据能继续用，新数据不再产生弱算法。等老数据消耗完，再彻底移除DES支持。

5.4 需要注意的几个“反直觉”问题

第一，RandomHelper.GenerateRandomBytes必须使用RandomNumberGenerator，不能用System.Random。Random不是密码学安全的随机数，用于生成密钥和IV会造成可预测。工具集底层统一使用RandomNumberGenerator.Fill。

第二，时间攻击。在做字符串比较时，如果是校验签名或口令摘要，不要用==，因为遇到第一个不同字符就返回，理论上可通过耗时差异推断逐字符信息。推荐使用CryptographicOperations.FixedTimeEquals。工具集里统一实现了SafeEquals：

public static bool SafeEquals(byte[] left, byte[] right) { return CryptographicOperations.FixedTimeEquals(left, right); }

第三，不要自己发明“异或加密”或“自定义乱序”算法。就算别人看不懂，也更容易被破解。标准算法经过了全世界密码学家的长期检验，自己造的轮子通常是负优化。

6. 工具集使用心得与后续扩展建议

6.1 多个项目实际应用后的体会

这套工具集在我参与的几个模拟项目里反复使用过。一个内部数据交换系统，接口签名从原来的Base64+MD5换成RSA-SHA256后，调用方一开始不太适应，因为需要单独管理公钥。但随后规范签名、密钥保管后，整体安全性提升明显。另一个桌面工具软件，用AES-GCM替代了原来的AES-CBC，虽然改动不大，但GCM自带完整性校验，省掉额外算哈希的步骤。建议新项目优先考虑AES-GCM，.NET的AesGcm类可用，但它只支持一次性操作，大文件需要外部实现分块，这点和CryptoStream不太一样，封装时需要留意。

我还发现一个通病：很多开发者给自己项目集成工具集时，喜欢额外包一层“静态工具类”，加一些花哨的字符串处理。这本身没问题，但一旦包装层里出现偷偷替换编码、拼接IV的方式，就可能破坏兼容性。所以工具集的边界一定要清晰，提供的方法参数要充分文档化，调用方不要随意魔改。

6.2 类库的使用成本和收益

有人可能会问，为了几个加解密方法搞一个类库是不是太小题大做？我的看法是：如果只是临时脚本，确实不用。但凡要维护的正式项目，统一封装后的收益非常明显：

• 安全基线和算法选择收敛到一处，审计时只需看工具集代码。
• 新人接手时不需要翻文档，看门面类的XML注释就能开始调用。
• 出问题时排查范围小，不需要从各种怪异的加密代码里找bug。
• 升级算法时只改工具集，而不是改几十个调用点。

当然也要控制成本，不要每个项目都重新发明一套。工具集编译后只有几百KB，不影响主程序启动速度。源码文件也不复杂，核心代码加起来不到两千行，比起引入一个几千文件的大第三方库，维护负担小很多。

6.3 后续扩展的几个方向

这套工具集短期内不打算加太多新功能，但有几个方向可以考虑：

• 增加AES-GCM的流式封装，因为GCM不支持CryptoStream直接分块，需要自己维护nonce和counter，这是比较有挑战的部分。
• 增加RSA-OAEP填充选项，与外部系统对接时遇到非PKCS1填充可以切换。
• 增加统一配置模型，把加密算法、密钥轮换策略、存储格式通过一个Option类传入，减少方法参数数量。
• 增加日志选项，记录“何时、调用了哪个方法、处理了多少字节”，方便排查生产问题，但注意不要泄露明文内容。

我个人在写完这套工具集后的体会是：代码本身不算难，难的是把接口用得顺手、把边界想清楚、把坑提前填平。每次看到“加密工具”四个字，不要只想到算法，更要想密钥从哪来、密文存哪去、出了问题怎么排查。把这些想透了，工具集才能真正成为团队里可靠的底层模块。

最后还是那句话，工具集永远只是辅助，安全的关键在于使用者是否敬畏这些细节。每次加解密前多想一步，把随机数、密钥存储、算法模式都过一遍，比事后补救强得多。