5.3 C# SDK

# Allinpay Shopoint OCPay SDK for .NET

通联支付一码付开放接口SDK的C#实现版本。

## 依赖库

- **.NET 8.0** 或更高版本
- **BouncyCastle.Cryptography 2.4.0** - 提供真正的SM2算法实现
- 秘钥长度：2048位及以上（RSA）
- 秘钥格式：PKCS#8（私钥）、X509（公钥）

## 功能特性

- **多种签名算法支持**：RSA、SM2、MD5
- **真正的SM2算法**：集成BouncyCastle.Cryptography库，支持真实的国密SM2算法
- **灵活的请求接口**：支持所有一码付API
- **自动签名和验签**：根据配置自动选择算法
- **多种配置方式**：支持配置文件和环境变量配置
- **调试日志输出**：便于开发调试
- **响应数据辅助处理**：提供便捷的数据访问方法
- **密钥对生成**：支持生成真实的SM2密钥对用于测试

## 支持的签名算法

### RSA算法
- 使用SHA1WithRSA签名算法
- 支持PKCS#8格式私钥
- 与Java版本完全兼容

### SM2算法 (国密算法) - 真实实现
- **真正的SM2算法**：使用BouncyCastle.Cryptography库实现
- 使用SM3WithSM2签名算法
- 支持国产密码算法标准
- **简化配置**：直接使用AppId作为证书ID，无需额外配置
- 支持PKCS#8格式私钥和X509格式公钥
- 完全符合国密标准规范

### MD5算法
- 简单的MD5哈希签名
- 适用于低安全要求场景

## 快速开始

### 下载SDK

[点击下载](https://dms.shopoint.cn/openapis/sdk/csharp-ocpay-sdk.zip)

### 1. 配置SDK参数

#### RSA算法配置

**方式一：使用配置文件**

复制 `config.template.json` 为 `config.json` 并填入你的配置：

```json
{
  "appId": "your_app_id_here",
  "signType": "RSA",
  "privateKey": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----",
  "publicKey": "-----BEGIN PUBLIC KEY-----\nYOUR_PUBLIC_KEY_HERE\n-----END PUBLIC KEY-----",
  "certId": "",
  "debugEnabled": true
}
```

**方式二：使用环境变量**

```bash
export OCPAY_APP_ID="your_app_id"
export OCPAY_SIGN_TYPE="RSA"
export OCPAY_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----"
export OCPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nYOUR_PUBLIC_KEY_HERE\n-----END PUBLIC KEY-----"
export OCPAY_DEBUG="true"
```

#### SM2算法配置

**使用配置文件：**

```json
{
  "appId": "your_app_id_here",
  "signType": "SM2",
  "privateKey": "MIGHAgEAMBMGByqGSM49AgEGCCqBHM9VAYItBG0wawIBAQQg...",
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAE...",
  "debugEnabled": true
}
```

**使用环境变量：**

```bash
export OCPAY_APP_ID="your_app_id"
export OCPAY_SIGN_TYPE="SM2"
export OCPAY_PRIVATE_KEY="MIGHAgEAMBMGByqGSM49AgEGCCqBHM9VAYItBG0wawIBAQQg..."
export OCPAY_PUBLIC_KEY="MFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAE..."
export OCPAY_DEBUG="true"
```

**注意：** SM2算法直接使用AppId作为证书ID，无需额外配置。

### 2. 使用SDK

```csharp
using AllinpayShopointOCPaySDK;

// 创建SDK实例
var sdk = new AllinpayShopointOCPaySdk();

// 加载配置
var config = Config.LoadFromFile("config.json");
// 或者从环境变量加载: var config = Config.LoadFromEnv();
sdk.SetConfig(config);

// 准备请求参数
var parameters = new Dictionary<string, object>
{
    ["cusid"] = "266649",
    ["reqsn"] = "202509108000002",
    ["randomstr"] = Utils.GenerateRandomString(16)
};

// 发起请求
var endpoint = "https://dms-api-test.shopoint.cn/shopoint-openapis-web/szyx/apiweb/tranx/query";
var response = await sdk.RequestAsync(endpoint, parameters);

// 处理响应
if (response.IsSuccess())
{
    Console.WriteLine($"查询成功，交易状态: {response.GetTrxStatus()}");
    Console.WriteLine($"交易金额: {response.GetTrxAmt()}");
}
else
{
    Console.WriteLine($"查询失败: {response.GetErrorMessage()}");
}
```

## 主要类说明

### AllinpayShopointOCPaySdk
主要的SDK类，提供接口调用功能。

**主要方法：**
- `SetConfig(Config config)` - 设置SDK配置
- `RequestAsync(string endpoint, Dictionary<string, object> parameters)` - 发起API请求

### Config
配置类，支持从文件或环境变量加载配置。

**主要方法：**
- `LoadFromFile(string filename)` - 从JSON文件加载配置
- `LoadFromEnv()` - 从环境变量加载配置
- `Validate()` - 验证配置有效性

### ResponseHelper
响应处理辅助类，提供便捷的数据访问方法。

**主要方法：**
- `IsSuccess()` - 判断请求是否成功
- `IsPaid()` - 判断是否已支付
- `GetString(string key)` - 获取字符串值
- `GetInt(string key)` - 获取整数值
- `GetRetCode()` - 获取返回码
- `GetTrxStatus()` - 获取交易状态
- `GetErrorMessage()` - 获取错误信息

### CryptoUtils
加密工具类，提供多种签名算法支持。

**主要方法：**
- `RsaPrivateSign(string data, string privateKey)` - RSA私钥签名
- `RsaPublicVerify(string data, string sign, string publicKey)` - RSA公钥验签
- `Sm2PrivateSign(string data, string privateKey, string appId)` - SM2私钥签名
- `Sm2PublicVerify(string data, string sign, string publicKey, string appId)` - SM2公钥验签
- `Sign(string data, string privateKey, string signType, string appId)` - 通用签名方法
- `Verify(string data, string sign, string publicKey, string signType, string appId)` - 通用验签方法

### SM2Utils
SM2算法专用工具类，提供真正的国密算法支持。

**主要方法：**
- `SignSM3SM2RetBase64(string privateKey, string certId, byte[] data)` - SM2签名并返回Base64
- `VerifySM3SM2(string publicKey, string certId, byte[] signData, byte[] srcData)` - SM2验签
- `PrivKeySM2FromBase64Str(string keystr)` - 从Base64解析SM2私钥
- `PubKeySM2FromBase64Str(string keystr)` - 从Base64解析SM2公钥
- `GenerateSM2KeyPair()` - 生成SM2密钥对
- `ValidateKeyPair(string privateKey, string publicKey)` - 验证密钥对匹配性

### Utils
工具类，提供随机字符串生成、签名字符串构建等功能。

## 运行项目

```bash
dotnet run
```

## 构建项目

```bash
dotnet build
```

## 注意事项

1. 请确保正确配置AppId、公钥和私钥
2. 私钥格式需要符合PKCS#8标准
3. 建议在生产环境中关闭调试模式
4. 所有接口调用都是异步的，请使用async/await模式
5. SDK会自动处理签名和验签，无需手动处理
6. 支持所有一码付开放接口，只需提供正确的endpoint和参数

## 错误处理

SDK会在以下情况抛出异常：
- 配置验证失败
- 签名失败
- 网络请求失败
- 验签失败（可选，通过ResponseHelper判断）

建议使用try-catch块处理异常：

```csharp
try
{
    var response = await sdk.RequestAsync(endpoint, parameters);
    // 处理响应
}
catch (Exception ex)
{
    Console.WriteLine($"请求失败: {ex.Message}");
}
```

## 示例

### RSA算法示例

项目包含完整的RSA交易查询示例，演示了如何：
- 加载配置
- 创建SDK实例
- 发起API请求
- 处理响应数据

运行RSA示例：
```bash
dotnet run
```

### SM2算法示例

项目包含完整的SM2算法示例，演示了如何：
- 生成真实的SM2密钥对
- 配置SM2算法参数
- 使用真正的BouncyCastle库进行签名和验签
- 发起SM2算法的API请求

运行真实SM2示例：
```bash
dotnet run --project SM2RealExample.cs
```

运行框架SM2示例：
```bash
dotnet run --project SM2Example.cs
```

### SM2密钥对生成

SDK提供了真实的SM2密钥对生成功能：

```csharp
// 生成SM2密钥对
var (privateKey, publicKey) = SM2Utils.GenerateSM2KeyPair();

// 验证密钥对是否匹配
var isValid = SM2Utils.ValidateKeyPair(privateKey, publicKey);

Console.WriteLine($"私钥: {privateKey}");
Console.WriteLine($"公钥: {publicKey}");
Console.WriteLine($"密钥对验证: {(isValid ? "匹配" : "不匹配")}");
```

### 算法切换示例

```csharp
// 创建配置
var config = new Config
{
    AppId = "your_app_id",
    SignType = "SM2", // 可以是 "RSA", "SM2", "MD5"
    PrivateKey = "your_private_key",
    PublicKey = "your_public_key"
    // SM2算法直接使用AppId作为证书ID，无需额外配置
};

// SDK会根据SignType自动选择对应的算法
var sdk = new AllinpayShopointOCPaySdk();
sdk.SetConfig(config);

// 发起请求，SDK内部会自动使用配置的算法进行签名
var response = await sdk.RequestAsync(endpoint, parameters);
```

## 重要说明

### SM2算法实现

**真正的SM2算法**：当前版本集成了BouncyCastle.Cryptography库，提供真正的SM2算法实现：

1. **真实的密码学算法**：使用BouncyCastle库的SM2实现，符合国密标准
2. **完整的密钥支持**：支持真实的SM2密钥对生成、解析和使用
3. **标准的ASN1编码**：使用标准的ASN1编码格式处理签名数据
4. **生产环境就绪**：可以直接用于生产环境

### 安装依赖

项目已经配置了BouncyCastle.Cryptography依赖，运行以下命令安装：

```bash
dotnet restore
```

### SM2算法注意事项

1. **简化配置**：SM2算法直接使用AppId作为证书ID，无需额外配置
2. **密钥格式**：SM2私钥和公钥需要使用Base64编码格式
3. **算法实现**：使用真正的BouncyCastle SM2算法实现
4. **兼容性**：SM2算法与Java版本的实现保持一致
5. **密钥生成**：可以使用SDK提供的密钥生成功能创建测试密钥对

### 生产环境使用

1. **密钥管理**：妥善保管私钥，不要在代码中硬编码
2. **算法选择**：根据业务需求和安全要求选择合适的签名算法
3. **测试验证**：在生产环境使用前，请充分测试各种算法的兼容性
4. **性能考虑**：SM2算法的性能特征与RSA不同，请根据实际需求选择