Smart.Security 4.1.5

Smart.Security

English | 中文

<a name="english"></a>

English

Smart.Security is a comprehensive .NET security component library built on BouncyCastle.Cryptography, providing core functionalities for data encryption/decryption, signature verification, hash computation, random generation, and more. It supports .NET 8, 9 and 10 platforms.

Features

• Symmetric Encryption: AES (128/256-bit), SM4 (128-bit block encryption)
• Asymmetric Encryption: RSA (public key encryption/private key decryption), SM2 (elliptic curve encryption)
• Hash Algorithms: MD5/SHA series (SHA1/256/384/512), HMAC series, SM3
• Password Security: Password verification, salted hashing, salt generation
• Random Generation: Cryptographically secure random bytes/strings/Chinese characters
• File Integrity: Multi-algorithm file hash verification

Installation

Install the package via NuGet:

dotnet add package Smart.Security

Usage Examples

1. SmartAESCipher (AES Symmetric Encryption)

AES symmetric encryption/decryption in CBC mode with support for 128/256-bit key lengths.

using Smart.Security;

var cipher = new SmartAESCipher();

// Encrypt data
byte[] key = new byte[32]; // 256-bit key
byte[] iv = new byte[16];  // 128-bit IV
byte[] plainData = Encoding.UTF8.GetBytes("Hello World");

byte[] encrypted = cipher.Encrypt(plainData, key, iv);

// Decrypt data
byte[] decrypted = cipher.Decrypt(encrypted, key, iv);

2. SmartRSACipher (RSA Asymmetric Encryption)

RSA public key encryption/private key decryption with signature verification support.

using Smart.Security;

var cipher = new SmartRSACipher();

// Generate key pair
var (publicKey, privateKey) = cipher.GenerateKeyPair(2048);

// Encrypt with public key
byte[] plainData = Encoding.UTF8.GetBytes("Secret Message");
byte[] encrypted = cipher.Encrypt(plainData, publicKey);

// Decrypt with private key
byte[] decrypted = cipher.Decrypt(encrypted, privateKey);

// Sign with private key
byte[] signature = cipher.Sign(plainData, privateKey, HashType.SHA256);

// Verify with public key
bool isValid = cipher.Verify(plainData, signature, publicKey, HashType.SHA256);

3. SmartSM2Cipher (SM2 Elliptic Curve Encryption)

Chinese national standard SM2 asymmetric encryption with SM3-based signature verification.

using Smart.Security;

var cipher = new SmartSM2Cipher();

// Generate key pair
var (publicKey, privateKey) = cipher.GenerateKeyPair();

// Encrypt with public key
byte[] plainData = Encoding.UTF8.GetBytes("SM2 Encrypted Message");
byte[] encrypted = cipher.Encrypt(plainData, publicKey);

// Decrypt with private key
byte[] decrypted = cipher.Decrypt(encrypted, privateKey);

// Sign with private key
byte[] signature = cipher.Sign(plainData, privateKey);

// Verify with public key
bool isValid = cipher.Verify(plainData, signature, publicKey);

4. SmartSM4Cipher (SM4 Symmetric Encryption)

Chinese national standard SM4 symmetric encryption in ECB/CBC mode with fixed 128-bit key and block length.

using Smart.Security;

var cipher = new SmartSM4Cipher();

// Encrypt in CBC mode
byte[] key = new byte[16]; // 128-bit key
byte[] iv = new byte[16];  // 128-bit IV
byte[] plainData = Encoding.UTF8.GetBytes("SM4 Encrypted Message");

byte[] encrypted = cipher.EncryptCBC(plainData, key, iv);

// Decrypt in CBC mode
byte[] decrypted = cipher.DecryptCBC(encrypted, key, iv);

5. SmartHash (Hash Algorithms)

Support for MD5/SHA1/SHA256/SHA384/SHA512 and HMAC series algorithms.

using Smart.Security;

// Compute hash
byte[] data = Encoding.UTF8.GetBytes("Data to hash");

byte[] md5Hash = SmartHash.ComputeHash(data, HashType.MD5);
byte[] sha256Hash = SmartHash.ComputeHash(data, HashType.SHA256);
byte[] sha512Hash = SmartHash.ComputeHash(data, HashType.SHA512);

// Compute HMAC
byte[] key = Encoding.UTF8.GetBytes("secret-key");
byte[] hmacSha256 = SmartHash.ComputeHMAC(data, key, HashType.SHA256);

6. SmartSM3Hash (SM3 Hash Algorithm)

Chinese national standard SM3 hash algorithm with security strength equivalent to SHA-256.

using Smart.Security;

byte[] data = Encoding.UTF8.GetBytes("Data to hash");

// Compute SM3 hash (32-byte output)
byte[] sm3Hash = SmartSM3Hash.ComputeHash(data);

// Get hash as hex string
string hexHash = SmartSM3Hash.ComputeHashString(data);

7. SmartFileHash (File Hash Verification)

File hash computation with streaming optimization for large files.

using Smart.Security;

string filePath = @"C:\path\to\file.txt";

// Compute file hash
byte[] md5Hash = SmartFileHash.ComputeFileHash(filePath, HashType.MD5);
byte[] sha256Hash = SmartFileHash.ComputeFileHash(filePath, HashType.SHA256);

// Verify file integrity
bool isValid = SmartFileHash.VerifyFileHash(filePath, expectedHash, HashType.SHA256);

8. SmartPassword (Password Security)

PBKDF2 password hashing with automatic salt generation and verification.

using Smart.Security;

// Hash password with salt
string password = "user_password";
string hashedPassword = SmartPassword.HashPassword(password);

// Verify password
bool isValid = SmartPassword.VerifyPassword(password, hashedPassword);

// Hash with custom iterations
string customHashed = SmartPassword.HashPassword(password, iterations: 20000);

9. SmartRandom (Secure Random Generation)

Cryptographically secure random number generation for bytes, hex strings, base64 strings, and Chinese characters.

using Smart.Security;

// Generate random bytes
byte[] randomBytes = SmartRandom.GetBytes(32);

// Generate random hex string
string hexString = SmartRandom.GetHexString(64);

// Generate random base64 string
string base64String = SmartRandom.GetBase64String(32);

// Generate random Chinese characters
string chineseChars = SmartRandom.GetChineseString(10);

// Generate random alphanumeric string
string alnumString = SmartRandom.GetAlphanumericString(16);

Platform Compatibility

Security Recommendations

1. National Standard Algorithms: SM2/SM3/SM4 algorithms require BouncyCastle extensions.
2. RSA Key Length: Recommended to use RSA keys with length ≥ 2048 bits.
3. Hash Algorithm Selection: Prioritize SHA256/384/512 over MD5/SHA1 for better security.
4. Key Storage: Keys should be stored in secure media such as HSM (Hardware Security Module).
5. Password Hashing: Always use salted hashing for password storage with sufficient iterations.
6. IV/Nonce: Always use unique initialization vectors for each encryption operation.

<a name="chinese"></a>

中文

Smart.Security 是一个基于 BouncyCastle.Cryptography 实现的 .NET 安全组件库，支持数据加解密、签名验签、哈希计算、随机生成等核心功能，兼容 .NET 8/9/10 平台。

功能特性

• 对称加密: AES（128/256位）、国密SM4（128位分组加密）
• 非对称加密: RSA（公钥加密/私钥解密）、国密SM2（椭圆曲线加密）
• 哈希算法: MD5/SHA系列（SHA1/256/384/512）、HMAC系列、国密SM3
• 密码安全: 密码校验、加盐哈希、盐值生成
• 随机数生成: 安全随机字节/字符串/随机汉字
• 文件完整性: 多算法文件哈希校验

安装

通过 NuGet 安装：

dotnet add package Smart.Security

使用示例

1. SmartAESCipher (AES 对称加密)

AES 对称加密/解密（CBC 模式），支持 128/256 位密钥长度。

using Smart.Security;

var cipher = new SmartAESCipher();

// 加密数据
byte[] key = new byte[32]; // 256位密钥
byte[] iv = new byte[16];  // 128位IV
byte[] plainData = Encoding.UTF8.GetBytes("Hello World");

byte[] encrypted = cipher.Encrypt(plainData, key, iv);

// 解密数据
byte[] decrypted = cipher.Decrypt(encrypted, key, iv);

2. SmartRSACipher (RSA 非对称加密)

RSA 公钥加密/私钥解密，支持签名验签功能。

using Smart.Security;

var cipher = new SmartRSACipher();

// 生成密钥对
var (publicKey, privateKey) = cipher.GenerateKeyPair(2048);

// 使用公钥加密
byte[] plainData = Encoding.UTF8.GetBytes("Secret Message");
byte[] encrypted = cipher.Encrypt(plainData, publicKey);

// 使用私钥解密
byte[] decrypted = cipher.Decrypt(encrypted, privateKey);

// 使用私钥签名
byte[] signature = cipher.Sign(plainData, privateKey, HashType.SHA256);

// 使用公钥验签
bool isValid = cipher.Verify(plainData, signature, publicKey, HashType.SHA256);

3. SmartSM2Cipher (SM2 椭圆曲线加密)

国密 SM2 非对称加密，基于 SM3 哈希的签名验签。

using Smart.Security;

var cipher = new SmartSM2Cipher();

// 生成密钥对
var (publicKey, privateKey) = cipher.GenerateKeyPair();

// 使用公钥加密
byte[] plainData = Encoding.UTF8.GetBytes("SM2 加密消息");
byte[] encrypted = cipher.Encrypt(plainData, publicKey);

// 使用私钥解密
byte[] decrypted = cipher.Decrypt(encrypted, privateKey);

// 使用私钥签名
byte[] signature = cipher.Sign(plainData, privateKey);

// 使用公钥验签
bool isValid = cipher.Verify(plainData, signature, publicKey);

4. SmartSM4Cipher (SM4 对称加密)

国密 SM4 对称加密（ECB/CBC 模式），固定 128 位密钥和分组长度。

using Smart.Security;

var cipher = new SmartSM4Cipher();

// CBC 模式加密
byte[] key = new byte[16]; // 128位密钥
byte[] iv = new byte[16];  // 128位IV
byte[] plainData = Encoding.UTF8.GetBytes("SM4 加密消息");

byte[] encrypted = cipher.EncryptCBC(plainData, key, iv);

// CBC 模式解密
byte[] decrypted = cipher.DecryptCBC(encrypted, key, iv);

5. SmartHash (哈希算法)

支持 MD5/SHA1/SHA256/SHA384/SHA512 和 HMAC 系列算法。

using Smart.Security;

// 计算哈希
byte[] data = Encoding.UTF8.GetBytes("待哈希数据");

byte[] md5Hash = SmartHash.ComputeHash(data, HashType.MD5);
byte[] sha256Hash = SmartHash.ComputeHash(data, HashType.SHA256);
byte[] sha512Hash = SmartHash.ComputeHash(data, HashType.SHA512);

// 计算 HMAC
byte[] key = Encoding.UTF8.GetBytes("secret-key");
byte[] hmacSha256 = SmartHash.ComputeHMAC(data, key, HashType.SHA256);

6. SmartSM3Hash (SM3 哈希算法)

国密 SM3 哈希算法，安全强度等效于 SHA-256，输出 32 字节哈希值。

using Smart.Security;

byte[] data = Encoding.UTF8.GetBytes("待哈希数据");

// 计算 SM3 哈希（32字节输出）
byte[] sm3Hash = SmartSM3Hash.ComputeHash(data);

// 获取十六进制字符串格式
string hexHash = SmartSM3Hash.ComputeHashString(data);

7. SmartFileHash (文件哈希校验)

文件哈希计算，针对大文件进行流式处理优化。

using Smart.Security;

string filePath = @"C:\path\to\file.txt";

// 计算文件哈希
byte[] md5Hash = SmartFileHash.ComputeFileHash(filePath, HashType.MD5);
byte[] sha256Hash = SmartFileHash.ComputeFileHash(filePath, HashType.SHA256);

// 验证文件完整性
bool isValid = SmartFileHash.VerifyFileHash(filePath, expectedHash, HashType.SHA256);

8. SmartPassword (密码安全)

PBKDF2 密码哈希，自动盐值生成与验证。

using Smart.Security;

// 使用盐值哈希密码
string password = "user_password";
string hashedPassword = SmartPassword.HashPassword(password);

// 验证密码
bool isValid = SmartPassword.VerifyPassword(password, hashedPassword);

// 使用自定义迭代次数
string customHashed = SmartPassword.HashPassword(password, iterations: 20000);

9. SmartRandom (安全随机数生成)

密码学安全的随机数生成，支持字节数组、十六进制字符串、Base64 字符串和随机汉字。

using Smart.Security;

// 生成随机字节
byte[] randomBytes = SmartRandom.GetBytes(32);

// 生成随机十六进制字符串
string hexString = SmartRandom.GetHexString(64);

// 生成随机 Base64 字符串
string base64String = SmartRandom.GetBase64String(32);

// 生成随机汉字
string chineseChars = SmartRandom.GetChineseString(10);

// 生成随机字母数字字符串
string alnumString = SmartRandom.GetAlphanumericString(16);

平台兼容

安全建议

1. 国密算法: SM2/SM3/SM4 算法需配合 BouncyCastle 扩展使用。
2. RSA 密钥长度: 建议使用长度 ≥ 2048 位的 RSA 密钥。
3. 哈希算法选择: 优先使用 SHA256/384/512 替代 MD5/SHA1 以获得更好的安全性。
4. 密钥存储: 密钥应存储于安全介质，如 HSM（硬件安全模块）。
5. 密码哈希: 密码存储应始终使用加盐哈希，并使用足够的迭代次数。
6. IV/Nonce: 每次加密操作都应使用唯一的初始化向量。

Developed by zenglei