解决MySql布尔型新旧版本兼容问题，采用枚举来表示布尔型的数据表。由正向工程赋值
|
# 安全扩展 SecurityHelper
## 概述
`SecurityHelper` 是 NewLife.Core ä¸çš„安全算法工具类，æ供常用的哈希算法ã€å¯¹ç§°åŠ 密ã€éžå¯¹ç§°åŠ 密ç‰åŠŸèƒ½çš„æ‰©å±•æ–¹æ³•ã€‚æ”¯æŒ MD5ã€SHA 系列ã€CRCã€AESã€DESã€RSA ç‰ä¸»æµåŠ 密算法。
**命å空间**：`NewLife`
**文档地å€**：https://newlifex.com/core/security_helper
## æ ¸å¿ƒç‰¹æ€§
- **哈希算法**：MD5ã€SHA1ã€SHA256ã€SHA384ã€SHA512ã€CRC16ã€CRC32ã€Murmur128
- **å¯¹ç§°åŠ å¯†**：AESã€DESã€3DESã€RC4ã€SM4
- **éžå¯¹ç§°åŠ 密**：RSAã€DSA
- **高性能**：使用线程é™æ€å˜é‡ç¼“å˜ç®—法实例，é¿å…é‡å¤åˆ›å»º
- **易用性**：所有算法都以扩展方法形å¼æä¾›
## 快速开始
```csharp
using NewLife;
// MD5 哈希
var hash = "password".MD5(); // 32ä½åå…进制å—符串
var hash16 = "password".MD5_16(); // 16ä½åå…进制å—符串
// SHA256 哈希
var sha = data.SHA256(); // 返回å—节数组
var shaHex = data.SHA256().ToHex(); // 转为åå…进制å—符串
// AES åŠ å¯†
var encrypted = data.Encrypt(Aes.Create(), key);
var decrypted = encrypted.Decrypt(Aes.Create(), key);
// CRC æ ¡éªŒ
var crc32 = data.Crc();
var crc16 = data.Crc16();
```
## API å‚考
### 哈希算法
#### MD5
```csharp
public static Byte[] MD5(this Byte[] data)
public static String MD5(this String data, Encoding? encoding = null)
public static String MD5_16(this String data, Encoding? encoding = null)
public static Byte[] MD5(this FileInfo file)
```
计算 MD5 散列值。
**示例**：
```csharp
// å—符串 MD5（32ä½ï¼‰
"password".MD5() // "5F4DCC3B5AA765D61D8327DEB882CF99"
// å—符串 MD5（16ä½ï¼Œå–ä¸é—´8å—节）
"password".MD5_16() // "5AA765D61D8327DE"
// å—节数组 MD5
var data = Encoding.UTF8.GetBytes("hello");
var hash = data.MD5(); // 返回 16 å—节数组
// 文件 MD5
var fileHash = "large-file.zip".AsFile().MD5().ToHex();
```
#### SHA 系列
```csharp
public static Byte[] SHA1(this Byte[] data, Byte[]? key)
public static Byte[] SHA256(this Byte[] data, Byte[]? key = null)
public static Byte[] SHA384(this Byte[] data, Byte[]? key)
public static Byte[] SHA512(this Byte[] data, Byte[]? key)
```
计算 SHA 系列散列值，å¯é€‰ HMAC 密钥。
**示例**：
```csharp
var data = Encoding.UTF8.GetBytes("hello");
// 普通哈希
var sha256 = data.SHA256(); // 32 å—节
var sha512 = data.SHA512(null); // 64 å—节
// HMAC 哈希（带密钥）
var key = Encoding.UTF8.GetBytes("secret");
var hmac256 = data.SHA256(key);
var hmac512 = data.SHA512(key);
```
#### CRC æ ¡éªŒ
```csharp
public static UInt32 Crc(this Byte[] data)
public static UInt16 Crc16(this Byte[] data)
```
计算 CRC æ ¡éªŒå€¼ã€‚
**示例**：
```csharp
var data = new Byte[] { 1, 2, 3, 4, 5 };
var crc32 = data.Crc(); // UInt32 æ ¡éªŒå€¼
var crc16 = data.Crc16(); // UInt16 æ ¡éªŒå€¼
```
#### Murmur128
```csharp
public static Byte[] Murmur128(this Byte[] data, UInt32 seed = 0)
```
计算 Murmur128 éžåŠ 密哈希，适用于哈希表ç‰åœºæ™¯ï¼Œé€Ÿåº¦æ¯” MD5 快很多。
**示例**：
```csharp
var hash = data.Murmur128(); // 默认ç§å
var hashWithSeed = data.Murmur128(12345); // 指定ç§å
```
### å¯¹ç§°åŠ å¯†
#### Encrypt / Decrypt
```csharp
public static Byte[] Encrypt(this SymmetricAlgorithm sa, Byte[] data, Byte[]? pass = null, CipherMode mode = CipherMode.CBC, PaddingMode padding = PaddingMode.PKCS7)
public static Byte[] Decrypt(this SymmetricAlgorithm sa, Byte[] data, Byte[]? pass = null, CipherMode mode = CipherMode.CBC, PaddingMode padding = PaddingMode.PKCS7)
```
å¯¹ç§°åŠ å¯†/解密数æ®ã€‚
**å‚数说明**：
- `pass`：密ç （会自动填充到åˆé€‚的密钥长度）
- `mode`ï¼šåŠ å¯†æ¨¡å¼ï¼ˆCBC/ECB ç‰ï¼‰ï¼Œ.NET 默认 CBC，Java 默认 ECB
- `padding`：填充模å¼ï¼Œé»˜è®¤ PKCS7（ç‰åŒ Java çš„ PKCS5）
**示例**：
```csharp
var data = Encoding.UTF8.GetBytes("Hello World!");
var key = Encoding.UTF8.GetBytes("my-secret-key-16");
// AES åŠ å¯†ï¼ˆCBC 模å¼ï¼‰
var encrypted = Aes.Create().Encrypt(data, key);
// AES 解密
var decrypted = Aes.Create().Decrypt(encrypted, key);
// ECB 模å¼ï¼ˆä¸Ž Java 兼容）
var encryptedEcb = Aes.Create().Encrypt(data, key, CipherMode.ECB);
var decryptedEcb = Aes.Create().Decrypt(encryptedEcb, key, CipherMode.ECB);
// DES åŠ å¯†
var desKey = Encoding.UTF8.GetBytes("12345678");
var desEncrypted = DES.Create().Encrypt(data, desKey);
// 3DES åŠ å¯†
var tripleDesKey = Encoding.UTF8.GetBytes("123456789012345678901234");
var tripleDesEncrypted = TripleDES.Create().Encrypt(data, tripleDesKey);
```
#### æµå¼åŠ 密
```csharp
public static SymmetricAlgorithm Encrypt(this SymmetricAlgorithm sa, Stream instream, Stream outstream)
public static SymmetricAlgorithm Decrypt(this SymmetricAlgorithm sa, Stream instream, Stream outstream)
```
对数æ®æµè¿›è¡ŒåŠ 密/解密，适åˆå¤„ç†å¤§æ–‡ä»¶ã€‚
**示例**：
```csharp
using var input = File.OpenRead("large-file.bin");
using var output = File.Create("large-file.enc");
var aes = Aes.Create();
aes.Key = key;
aes.IV = iv;
aes.Encrypt(input, output);
```
#### Transform
```csharp
public static Byte[] Transform(this ICryptoTransform transform, Byte[] data)
```
使用 `ICryptoTransform` 直接转æ¢æ•°æ®ã€‚
**示例**：
```csharp
var aes = Aes.Create();
aes.Key = key;
aes.IV = iv;
using var encryptor = aes.CreateEncryptor();
var encrypted = encryptor.Transform(data);
using var decryptor = aes.CreateDecryptor();
var decrypted = decryptor.Transform(encrypted);
```
#### RC4
```csharp
public static Byte[] RC4(this Byte[] data, Byte[] pass)
```
RC4 æµå¯†ç åŠ å¯†ã€‚RC4 åŠ å¯†å’Œè§£å¯†ä½¿ç”¨ç›¸åŒçš„方法。
**示例**：
```csharp
var data = Encoding.UTF8.GetBytes("Hello");
var key = Encoding.UTF8.GetBytes("secret");
// åŠ å¯†
var encrypted = data.RC4(key);
// 解密（åŒæ ·çš„方法）
var decrypted = encrypted.RC4(key);
```
## 其他安全类
### RSAHelper
RSA éžå¯¹ç§°åŠ 密辅助类。
```csharp
using NewLife.Security;
// 生æˆå¯†é’¥å¯¹
var (publicKey, privateKey) = RSAHelper.GenerateKey(2048);
// åŠ å¯†
var encrypted = RSAHelper.Encrypt(data, publicKey);
// 解密
var decrypted = RSAHelper.Decrypt(encrypted, privateKey);
// ç¾å
var signature = RSAHelper.Sign(data, privateKey, "SHA256");
// 验ç¾
var isValid = RSAHelper.Verify(data, signature, publicKey, "SHA256");
```
### DSAHelper
DSA æ•°å—ç¾å辅助类。
```csharp
using NewLife.Security;
// ç¾å
var signature = DSAHelper.Sign(data, privateKey);
// 验ç¾
var isValid = DSAHelper.Verify(data, signature, publicKey);
```
### Rand
éšæœºæ•°ç”Ÿæˆå™¨ã€‚
```csharp
using NewLife.Security;
// 生æˆéšæœºå—节
var bytes = Rand.NextBytes(16);
// 生æˆéšæœºæ•´æ•°
var num = Rand.Next(1, 100);
// 生æˆéšæœºå—符串
var str = Rand.NextString(16); // 包å«æ•°å—å’Œå—æ¯
var strWithSpecial = Rand.NextString(16, true); // 包å«ç‰¹æ®Šå—符
```
## 使用场景
### 1. 密ç 哈希å˜å‚¨
```csharp
public class PasswordHelper
{
public String HashPassword(String password, String salt)
{
// 使用 SHA256 + ç›å€¼
var data = Encoding.UTF8.GetBytes(password + salt);
return data.SHA256().ToHex();
}
public Boolean VerifyPassword(String password, String salt, String hash)
{
return HashPassword(password, salt).EqualIgnoreCase(hash);
}
}
```
### 2. API ç¾å验è¯
```csharp
public class ApiSignature
{
public String Sign(String data, String secret)
{
var key = Encoding.UTF8.GetBytes(secret);
var content = Encoding.UTF8.GetBytes(data);
return content.SHA256(key).ToHex();
}
public Boolean Verify(String data, String signature, String secret)
{
return Sign(data, secret).EqualIgnoreCase(signature);
}
}
```
### 3. æ•°æ®åŠ å¯†ä¼ è¾“
```csharp
public class SecureTransport
{
private readonly Byte[] _key;
public SecureTransport(String password)
{
// 使用密ç 派生密钥
_key = password.MD5().ToHex().GetBytes()[..16];
}
public Byte[] Encrypt(Byte[] data)
{
return Aes.Create().Encrypt(data, _key);
}
public Byte[] Decrypt(Byte[] data)
{
return Aes.Create().Decrypt(data, _key);
}
}
```
### 4. æ–‡ä»¶å®Œæ•´æ€§æ ¡éªŒ
```csharp
public class FileVerifier
{
public String ComputeHash(String filePath)
{
return filePath.AsFile().MD5().ToHex();
}
public Boolean Verify(String filePath, String expectedHash)
{
var actualHash = ComputeHash(filePath);
return actualHash.EqualIgnoreCase(expectedHash);
}
}
```
## 最佳实践
### 1. 选择åˆé€‚的算法
```csharp
// 密ç 哈希：使用 SHA256 或更强的算法
var passwordHash = (password + salt).GetBytes().SHA256().ToHex();
// æ•°æ®å®Œæ•´æ€§ï¼šMD5 足够快速
var checksum = data.MD5().ToHex();
// 高性能哈希表：使用 Murmur128
var hash = data.Murmur128();
```
### 2. 注æ„åŠ å¯†æ¨¡å¼å…¼å®¹æ€§
```csharp
// 与 Java 系统交互时使用 ECB 模å¼
var encrypted = Aes.Create().Encrypt(data, key, CipherMode.ECB);
// 安全性è¦æ±‚高时使用 CBC 模å¼ï¼ˆé»˜è®¤ï¼‰
var encrypted = Aes.Create().Encrypt(data, key, CipherMode.CBC);
```
### 3. 密钥管ç†
```csharp
// ä¸è¦ç¡¬ç¼–ç 密钥
var key = Environment.GetEnvironmentVariable("ENCRYPTION_KEY")?.ToHex();
// 使用安全的éšæœºæ•°ç”Ÿæˆå¯†é’¥
var randomKey = Rand.NextBytes(32);
```
## 算法对比
| 算法 | 输出长度 | 速度 | 安全性 | 用途 |
|------|---------|------|--------|------|
| MD5 | 16å—节 | 很快 | 低 | æ ¡éªŒå’Œã€éžå®‰å…¨å“ˆå¸Œ |
| SHA1 | 20å—节 | å¿« | ä¸ | 兼容旧系统 |
| SHA256 | 32å—节 | ä¸ | 高 | 通用安全哈希 |
| SHA512 | 64å—节 | 较慢 | 很高 | 高安全è¦æ±‚ |
| CRC32 | 4å—节 | æžå¿« | æ— | æ•°æ®æ ¡éªŒ |
| Murmur128 | 16å—节 | æžå¿« | æ— | 哈希表 |
## 相关链接
- [ç±»åž‹è½¬æ¢ Utility](/NewLife/X/Blob/master/Doc/utility-类型转æ¢Utility.md)
- [æ•°æ®æ‰©å±• IOHelper](/NewLife/X/Blob/master/Doc/io_helper-æ•°æ®æ‰©å±•IOHelper.md)
- [Web通用令牌 JwtBuilder](/NewLife/X/Blob/master/Doc/jwt-Web通用令牌JwtBuilder.md)
- [分布å¼æ•°å—ç¾å令牌 TokenProvider](/NewLife/X/Blob/master/Doc/token_provider-分布å¼æ•°å—ç¾å令牌TokenProvider.md)
|