Skip to content

Commit 5f7f3c2

Browse files
gmf520gmf520
committed
doc: add Crypto.Readme.md
1 parent af07cf7 commit 5f7f3c2

File tree

2 files changed

+234
-173
lines changed

2 files changed

+234
-173
lines changed

‎src/OSharp.Utils/Security/Crypto.Readme.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Crypto 加密解密工具类
2+
3+
`Crypto` 是一个功能完整的加密解密工具类，提供了 AES、RSA 以及混合加密等多种加密方式，支持字符串、字节数组和文件的加密解密操作。
4+
5+
## 功能特性
6+
7+
- **AES 加密解密**：支持 256 位密钥的 AES 加密，使用 CBC 模式和 PKCS7 填充
8+
- **RSA 加密解密**：支持 RSA 公钥加密和私钥解密，使用 OAEP-SHA256 填充
9+
- **RSA 数字签名**：支持数据签名和验证，确保数据完整性和身份认证
10+
- **混合加密**：结合 AES 和 RSA 的优势，提供高性能和高安全性的加密方案
11+
- **文件加密**：支持直接对文件进行加密和解密操作
12+
- **JSON 序列化**：加密数据支持 JSON 格式的序列化和反序列化
13+
14+
## 使用方法
15+
16+
### 1. AES 加密解密
17+
18+
#### 生成 AES 密钥
19+
```csharp
20+
// 生成 32 字节的 AES 密钥
21+
byte[] aesKey = Crypto.GenerateAesKey();
22+
```
23+
24+
#### 加密字节数组
25+
```csharp
26+
// 使用指定密钥加密
27+
byte[] data = Encoding.UTF8.GetBytes("Hello, World!");
28+
byte[] key = Crypto.GenerateAesKey();
29+
var (encryptData, returnedKey) = Crypto.AesEncrypt(data, key);
30+
31+
// 使用随机生成的密钥加密
32+
var (encryptData2, randomKey) = Crypto.AesEncrypt(data, null);
33+
```
34+
35+
#### 解密字节数组
36+
```csharp
37+
byte[] decryptedData = Crypto.AesDecrypt(encryptData, key);
38+
string result = Encoding.UTF8.GetString(decryptedData);
39+
```
40+
41+
#### 加密字符串
42+
```csharp
43+
string data = "Hello, World!";
44+
string base64Key = Convert.ToBase64String(Crypto.GenerateAesKey());
45+
var (encryptData, key) = Crypto.AesEncrypt(data, base64Key);
46+
```
47+
48+
#### 解密字符串
49+
```csharp
50+
string decryptedString = Crypto.AesDecrypt(encryptData, base64Key);
51+
```
52+
53+
#### 文件加密解密
54+
```csharp
55+
// 加密文件
56+
string sourceFile = "source.txt";
57+
string targetFile = "encrypted.txt";
58+
string base64Key = Convert.ToBase64String(Crypto.GenerateAesKey());
59+
var (encryptData, key) = Crypto.AesEncryptFile(sourceFile, targetFile, base64Key);
60+
61+
// 解密文件
62+
string decryptFile = "decrypted.txt";
63+
Crypto.AesDecryptFile(targetFile, decryptFile, base64Key);
64+
```
65+
66+
### 2. RSA 加密解密
67+
68+
#### 生成 RSA 密钥对
69+
```csharp
70+
var (publicKey, privateKey) = Crypto.GenerateRsaKey();
71+
```
72+
73+
#### 加密数据
74+
```csharp
75+
string data = "Hello, World!";
76+
string encryptedData = Crypto.RsaEncrypt(data, publicKey);
77+
```
78+
79+
#### 解密数据
80+
```csharp
81+
string decryptedData = Crypto.RsaDecrypt(encryptedData, privateKey);
82+
```
83+
84+
#### 字节数组加密解密
85+
```csharp
86+
byte[] data = Encoding.UTF8.GetBytes("Hello, World!");
87+
byte[] encryptedBytes = Crypto.RsaEncrypt(data, publicKey);
88+
byte[] decryptedBytes = Crypto.RsaDecrypt(encryptedBytes, privateKey);
89+
```
90+
91+
### 3. RSA 数字签名
92+
93+
#### 数据签名
94+
```csharp
95+
string data = "Hello, World!";
96+
string signature = Crypto.RsaSignData(data, privateKey);
97+
```
98+
99+
#### 验证签名
100+
```csharp
101+
bool isValid = Crypto.RsaVerifyData(data, signature, publicKey);
102+
```
103+
104+
#### 字节数组签名验证
105+
```csharp
106+
byte[] data = Encoding.UTF8.GetBytes("Hello, World!");
107+
byte[] signature = Crypto.RsaSignData(data, privateKey);
108+
bool isValid = Crypto.RsaVerifyData(data, signature, publicKey);
109+
```
110+
111+
### 4. 混合加密（AES + RSA）
112+
113+
混合加密结合了 AES 的高性能和 RSA 的安全性，适用于需要高性能和高安全性的场景。
114+
115+
#### 加密流程
116+
1. 使用自己的 RSA 私钥对数据进行签名
117+
2. 使用随机生成的 AES 密钥加密数据
118+
3. 使用对方的 RSA 公钥加密 AES 密钥
119+
120+
```csharp
121+
string data = "Hello, World!";
122+
var (ownPublicKey, ownPrivateKey) = Crypto.GenerateRsaKey();
123+
var (facePublicKey, facePrivateKey) = Crypto.GenerateRsaKey();
124+
125+
// 加密
126+
string hybridJson = Crypto.HybridEncrypt(data, ownPrivateKey, facePublicKey);
127+
```
128+
129+
#### 解密流程
130+
1. 使用自己的 RSA 私钥解密 AES 密钥
131+
2. 使用 AES 密钥解密数据
132+
3. 使用对方的 RSA 公钥验证数据签名
133+
134+
```csharp
135+
// 解密
136+
string decryptedData = Crypto.HybridDecrypt(hybridJson, facePrivateKey, ownPublicKey);
137+
```
138+
139+
#### 字节数组混合加密
140+
```csharp
141+
byte[] data = Encoding.UTF8.GetBytes("Hello, World!");
142+
HybridEncryptData hybridData = Crypto.HybridEncrypt(data, ownPrivateKey, facePublicKey);
143+
byte[] decryptedData = Crypto.HybridDecrypt(hybridData, facePrivateKey, ownPublicKey);
144+
```
145+
146+
## 数据结构
147+
148+
### AesEncryptData
149+
AES 加密后的数据结构，包含加密数据和初始化向量（IV）。
150+
151+
```csharp
152+
public class AesEncryptData
153+
{
154+
public byte[] Iv { get; set; } // 初始化向量（16字节）
155+
public byte[] CipherData { get; set; } // 加密后的数据
156+
157+
public string GetIvString() // 获取IV的Base64字符串
158+
public string GetCipherDataString() // 获取加密数据的Base64字符串
159+
public string ToJson() // 序列化为JSON
160+
public static AesEncryptData FromJson(string json) // 从JSON反序列化
161+
}
162+
```
163+
164+
### HybridEncryptData
165+
混合加密后的数据结构，包含 AES 加密数据、签名和 RSA 加密的 AES 密钥。
166+
167+
```csharp
168+
public class HybridEncryptData
169+
{
170+
public AesEncryptData AesEncryptData { get; set; } // AES加密数据
171+
public byte[] Signature { get; set; } // 数据签名
172+
public byte[] RsaEncryptedAesKey { get; set; } // RSA加密的AES密钥
173+
174+
public string ToJson() // 序列化为JSON
175+
public static HybridEncryptData FromJson(string json) // 从JSON反序列化
176+
}
177+
```
178+
179+
## 安全注意事项
180+
181+
1. **密钥管理**：请妥善保管加密密钥，建议使用安全的密钥管理系统
182+
2. **RSA 数据长度限制**：RSA 加密有数据长度限制，对于 2048 位密钥，最大数据长度为 190 字节
183+
3. **混合加密**：对于大数据量，建议使用混合加密方案
184+
4. **签名验证**：混合加密会自动验证数据签名，确保数据完整性和身份认证
185+
5. **异常处理**：加密解密操作可能抛出异常，请做好异常处理
186+
187+
## 异常类型
188+
189+
- `ArgumentNullException`：参数为 null 时抛出
190+
- `ArgumentException`：参数格式不正确时抛出
191+
- `FileNotFoundException`：文件不存在时抛出
192+
- `CryptographicException`：加密解密失败或签名验证失败时抛出
193+
194+
## 示例代码
195+
196+
### 完整的加密解密示例
197+
```csharp
198+
using System;
199+
using System.Text;
200+
using OSharp.Security;
201+
202+
class Program
203+
{
204+
static void Main()
205+
{
206+
// AES 加密示例
207+
string originalText = "这是一个测试数据";
208+
var (encryptData, aesKey) = Crypto.AesEncrypt(originalText, null);
209+
string decryptedText = Crypto.AesDecrypt(encryptData, Convert.ToBase64String(aesKey));
210+
Console.WriteLine($"AES 解密结果: {decryptedText}");
211+
212+
// RSA 加密示例
213+
var (publicKey, privateKey) = Crypto.GenerateRsaKey();
214+
string rsaEncrypted = Crypto.RsaEncrypt(originalText, publicKey);
215+
string rsaDecrypted = Crypto.RsaDecrypt(rsaEncrypted, privateKey);
216+
Console.WriteLine($"RSA 解密结果: {rsaDecrypted}");
217+
218+
// 混合加密示例
219+
var (ownPublicKey, ownPrivateKey) = Crypto.GenerateRsaKey();
220+
var (facePublicKey, facePrivateKey) = Crypto.GenerateRsaKey();
221+
222+
string hybridEncrypted = Crypto.HybridEncrypt(originalText, ownPrivateKey, facePublicKey);
223+
string hybridDecrypted = Crypto.HybridDecrypt(hybridEncrypted, facePrivateKey, ownPublicKey);
224+
Console.WriteLine($"混合加密解密结果: {hybridDecrypted}");
225+
}
226+
}
227+
```
228+
229+
## 版本信息
230+
231+
- **版本**：1.0.0
232+
- **作者**：郭明锋
233+
- **最后更新**：2025-10-18
234+
- **许可证**：Copyright (c) 2025 66SOFT. All rights reserved.

0 commit comments

Comments
 (0)