From a0f818150356528375249de7d3a87764112fb14d Mon Sep 17 00:00:00 2001 From: Fu Diwei Date: Thu, 25 Nov 2021 21:15:54 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 12 ++ .../Advanced_EventDataDeserialization.md | 6 +- ...Advanced_EventDataSignatureVerification.md | 2 +- docs/WechatApi/Advanced_Extensions.md | 2 +- docs/WechatApi/Advanced_JSSDK.md | 2 +- .../Advanced_EventDataDecryption.md | 14 +- ...Advanced_EventDataSignatureVerification.md | 36 +++- docs/WechatTenpayV3/Advanced_Extensions.md | 2 +- docs/WechatTenpayV3/Advanced_Payment.md | 2 +- .../Advanced_RequestDataEncryption.md | 161 ++++++++++++++++++ .../Advanced_ResponseDataDecryption.md | 38 ++++- .../Advanced_ResponseSignatureVerification.md | 93 +++------- docs/WechatTenpayV3/README.md | 2 + .../Advanced_EventDataDeserialization.md | 4 +- docs/WechatWork/Advanced_Extensions.md | 2 +- docs/WechatWork/Advanced_JSSDK.md | 2 +- .../WechatTenpayClient.cs | 4 +- 17 files changed, 285 insertions(+), 99 deletions(-) create mode 100644 docs/WechatTenpayV3/Advanced_RequestDataEncryption.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b22596ad..87aefbe2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -180,6 +180,18 @@ [展开查看] SKIT.FlurlHttpClient.Wechat.TenpayV3 模块更新日志 +- Release 2.1.0 + + - **新增**：新增商户平台处置通知相关接口。 + + - **新增**：随官方更新消费者投诉相关接口模型。 + + - **新增**：新增基于反射和特性的自动加密请求中敏感信息字段的功能。 + + - **新增**：新增基于反射和特性的自动解密响应中敏感信息字段的功能。 + + - **变更**：移除原有的解密响应中敏感信息字段的扩展方法。 + - Release 2.0.3 - **修复**：修复创建代金券批次相关接口的请求模型定义错误。（[Gitee Issue #I4ITW6](https://gitee.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat/issues/I4ITW6)） diff --git a/docs/WechatApi/Advanced_EventDataDeserialization.md b/docs/WechatApi/Advanced_EventDataDeserialization.md index c6cdd74b..f0cc10d8 100644 --- a/docs/WechatApi/Advanced_EventDataDeserialization.md +++ b/docs/WechatApi/Advanced_EventDataDeserialization.md @@ -2,7 +2,7 @@ --- -对于微信推送过来的回调通知事件，本库封装了直接解析成事件模型的扩展方法，下面给出一个示例： +对于微信推送过来的回调通知事件，本库封装了直接解析成事件模型的扩展方法，下面给出一个示例代码： ```csharp /* 如果是 JSON 格式的通知内容，以 wxa_media_check 事件为例 */ @@ -56,7 +56,7 @@ switch (msgType) 开发者可利用本库提供的 `WxBizMsgCryptor` 工具类自行解密相关字段。 -此外，本库还封装了直接解密事件的扩展方法，下面给出一个示例： +此外，本库还封装了直接解密事件的扩展方法，下面给出一个示例代码： ```csharp /* 在初始化客户端时需指定服务器推送的相关参数 */ @@ -80,7 +80,7 @@ var callbackModel = client.DeserializeEventFromXml(call 当用户发送消息给公众号、或某些特定的用户操作引发的事件推送时，开发者可以在响应中返回特定 XML 结构，来对该消息进行响应。 -本库还封装了直接序列化被动回复事件的扩展方法，下面给出一个示例： +本库还封装了直接序列化被动回复事件的扩展方法，下面给出一个示例代码： ```csharp /* 以被动回复文本消息为例 */ diff --git a/docs/WechatApi/Advanced_EventDataSignatureVerification.md b/docs/WechatApi/Advanced_EventDataSignatureVerification.md index b226c15c..5ec7064b 100644 --- a/docs/WechatApi/Advanced_EventDataSignatureVerification.md +++ b/docs/WechatApi/Advanced_EventDataSignatureVerification.md @@ -6,7 +6,7 @@ > > [《微信官方文档 - 开始开发：接入指南》](https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html) -同样的，你既可以利用本库提供的 `SHA1Utility`、`WxBizMsgCryptor` 工具类自行进行签名验证，也可以通过扩展方法实现： +同样地，你既可以利用本库提供的 `SHA1Utility`、`WxBizMsgCryptor` 工具类自行进行签名验证，也可以通过扩展方法实现： ```csharp /* 验证微信服务器 */ diff --git a/docs/WechatApi/Advanced_Extensions.md b/docs/WechatApi/Advanced_Extensions.md index 329a0546..ab905278 100644 --- a/docs/WechatApi/Advanced_Extensions.md +++ b/docs/WechatApi/Advanced_Extensions.md @@ -38,7 +38,7 @@ public static class MyFakeClientExtensions } ``` -同样的，你也可自行扩展回调通知事件模型： +同样地，你也可自行扩展回调通知事件模型： ```csharp /* 继承 WechatApiEvent 实现自定义的 JSON 格式的回调通知事件 */ diff --git a/docs/WechatApi/Advanced_JSSDK.md b/docs/WechatApi/Advanced_JSSDK.md index a0e103f6..e6d3f8cc 100644 --- a/docs/WechatApi/Advanced_JSSDK.md +++ b/docs/WechatApi/Advanced_JSSDK.md @@ -8,7 +8,7 @@ 你可根据官方文档的规则利用本库提供的 `SHA1Utility` 工具类自行进行签名生成。 -此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例： +此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例代码： ```csharp /* 以生成 wx.config() 所需参数为例 */ diff --git a/docs/WechatTenpayV3/Advanced_EventDataDecryption.md b/docs/WechatTenpayV3/Advanced_EventDataDecryption.md index dce45d39..c6390c2a 100644 --- a/docs/WechatTenpayV3/Advanced_EventDataDecryption.md +++ b/docs/WechatTenpayV3/Advanced_EventDataDecryption.md @@ -6,11 +6,23 @@ > > [《微信支付开发者文档 - 开发指南：证书和回调报文解密》](https://pay.weixin.qq.com/wiki/doc/apiv3_partner/wechatpay/wechatpay4_2.shtml) +--- + +### 密钥文件格式说明： + +需要注意的是，平台为商户提供的是 PEM 格式的密钥文件，需区分文件格式之间的不同。 + +有关密钥文件格式的更多介绍，请参阅本文档[《高级技巧 - 如何加密请求中的敏感数据？》](./Advanced_RequestDataEncryption.md)的有关章节。 + +--- + + + 对于回调通知事件的敏感信息，微信商户平台使用了商户公钥基于 RSA 算法加密。 开发者可利用本库提供的 `RSAUtility` 工具类自行解密相关字段。 -此外，本库还封装了直接解密事件的扩展方法，下面给出一个示例： +此外，本库还封装了直接解密事件的扩展方法，下面给出一个示例代码： ```csharp /* 微信商户平台发来的通知内容 */ diff --git a/docs/WechatTenpayV3/Advanced_EventDataSignatureVerification.md b/docs/WechatTenpayV3/Advanced_EventDataSignatureVerification.md index 39a05f26..6332f00e 100644 --- a/docs/WechatTenpayV3/Advanced_EventDataSignatureVerification.md +++ b/docs/WechatTenpayV3/Advanced_EventDataSignatureVerification.md @@ -2,11 +2,25 @@ --- -验证回调通知事件签名的方法与验证响应签名的类似，请参阅[相关文档](./Advanced_ResponseSignatureVerification.md)。 +> 请先自行阅读： +> +> [《微信支付开发者文档 - 开发指南：签名验证》](https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay4_1.shtml) -同样的，你既可以利用本库提供的 `RSAUtility` 工具类自行进行签名验证，也可以通过 `CertificateManager` 尝试自动完成签名验证： +--- -请注意，有关 `CertificateManager` 的具体用法、及相关证书或公钥格式的说明，请务必先阅读上方给出的相关文档。 +### 密钥文件格式说明： + +需要注意的是，平台为商户提供的是 PEM 格式的密钥文件，需注意文件格式之间的不同。 + +有关密钥文件格式的更多介绍，请参阅本文档[《高级技巧 - 如何加密请求中的敏感数据？》](./Advanced_RequestDataEncryption.md)的有关章节。 + +--- + +### 验签流程 + +验证回调通知事件签名的方法与验证响应签名的类似，请参阅本文档[《高级技巧 - 如何验证响应签名？》](./Advanced_ResponseSignatureVerification.md)的有关章节。 + +同样地，你既可以利用本库提供的 `RSAUtility` 工具类自行进行签名验证，也可以通过 `CertificateManager` 尝试自动完成签名验证： ```csharp bool ret = client.VerifyEventSignature( @@ -17,3 +31,19 @@ bool ret = client.VerifyEventSignature( callbackSerialNumber: "微信回调通知中的 Wechatpay-Serial 字段" ); ``` + +需要注意的是，使用该扩展方法前需先下载好平台证书，并存入全局的 `CertificateManager`。有关 `CertificateManager` 的更多介绍，请参阅本文档[《高级技巧 - 如何加密请求中的敏感数据？》](./Advanced_RequestDataEncryption.md)的有关章节。 + +--- + +### 调试验签错误： + +由于 `VerifyEventSignature()` 方法内部会 `try-catch` 做所有异常情况，并直接返回 `false`。为方便开发者在调试阶段排查验签的错误信息，你可以在验证回调通知事件签名时指定接收最后一个 `out` 返回参数，该参数中包含了一些异常的原因和相关堆栈信息。 + +```csharp +bool ret = client.VerifyEventSignature(timestamp, nonce, body, signature, serialNumber, out Exception error); +if (!ret) { + Console.WriteLine(error); + Console.WriteLine(error.InnerException); +} +``` \ No newline at end of file diff --git a/docs/WechatTenpayV3/Advanced_Extensions.md b/docs/WechatTenpayV3/Advanced_Extensions.md index 5c1ad576..85d949d7 100644 --- a/docs/WechatTenpayV3/Advanced_Extensions.md +++ b/docs/WechatTenpayV3/Advanced_Extensions.md @@ -38,7 +38,7 @@ public static class MyFakeClientExtensions } ``` -同样的，你也可自行扩展回调通知事件的敏感数据模型： +同样地，你也可自行扩展回调通知事件的敏感数据模型： ```csharp /* 实现自定义的 JSON 格式的回调通知事件敏感数据 */ diff --git a/docs/WechatTenpayV3/Advanced_Payment.md b/docs/WechatTenpayV3/Advanced_Payment.md index c84e2f70..8a7ec718 100644 --- a/docs/WechatTenpayV3/Advanced_Payment.md +++ b/docs/WechatTenpayV3/Advanced_Payment.md @@ -12,7 +12,7 @@ 你可根据官方文档的规则利用本库提供的 `RSAUtility` 工具类自行进行签名生成。 -此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例： +此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例代码： ```csharp /* 以生成 JSAPI 调起支付所需参数为例 */ diff --git a/docs/WechatTenpayV3/Advanced_RequestDataEncryption.md b/docs/WechatTenpayV3/Advanced_RequestDataEncryption.md new file mode 100644 index 00000000..c8e86b7d --- /dev/null +++ b/docs/WechatTenpayV3/Advanced_RequestDataEncryption.md @@ -0,0 +1,161 @@ +## 如何加密请求中的敏感数据？ + +--- + +> 请先自行阅读： +> +> [《微信支付开发者文档 - 平台证书：获取平台证书列表》](https://pay.weixin.qq.com/wiki/doc/apiv3_partner/wechatpay/wechatpay5_1.shtml) +> +> [《微信支付开发者文档 - 开发指南：敏感信息加解密》](https://pay.weixin.qq.com/wiki/doc/apiv3_partner/wechatpay/wechatpay4_3.shtml) + +--- + +### 重要须知 + +请在开发过程中注意区分**商户证书**和**平台证书**： + +- **商户证书**与请求中的敏感数据加密无关； +- **平台证书**用于加密请求中的敏感信息字段，需要通过接口获取（即 `QueryCertificatesAsync` 方法，注意证书内容需先经 AES-GCM 解密一次）。 + +如果你在请求过程中出现请求加密失败、服务器响应私钥解密失败的情况，请先检查是否混淆了这两个证书。 + +关于证书的更多注意事项，请参阅[《微信支付开发者文档 - 常见问题：证书相关》](https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay7_0.shtml) + +--- + +### 证书文件格式说明及加密示例： + +需要注意的是，`QueryCertificatesAsync` 方法返回的是 CER 格式的证书文件（需先经 AES-GCM 解密一次），需区分文件格式之间的不同： + +- 以 `-----BEGIN PRIVATE KEY-----` 开头、 `-----END PRIVATE KEY-----` 结尾的是 **PKCS#8 私钥**文件。 + +- 以 `-----BEGIN PUBLIC KEY-----` 开头、 `-----END PUBLIC KEY-----` 结尾的是 **PKCS#8 公钥**文件。 + +- 以 `-----BEGIN CERTIFICATE--- --` 开头、 `-----END CERTIFICATE-----` 结尾的是 **CER 证书**文件，可从中导出 PKCS#8 公钥。 + +谨记，`QueryCertificatesAsync()` 方法返回的结果是 CER 证书，需要先通过 `RSAUtility` 工具类导出 PKCS#8 公钥，再进行数据加密；当然，`RSAUtility` 也封装了直接通过 CER 证书加密的方法。 + +--- + +### 加密流程 + +对于部分接口请求传递的敏感信息，微信商户平台可能会需要使用以下方式进行加密： + +- 使用平台证书/公钥基于 RSA 算法加密。 + +开发者利用本库提供的 `RSAUtility` 工具类自行加密相关字段。下面给出一个使用 `RSAUtility` 工具类加密数据的示例代码： + +```csharp +string plainText = "待加密的数据"; +string certificate = "CER 证书内容"; +/* 通过证书加密数据 */ +string cipherText = RSAUtility.EncryptWithECBByCertificate(certificate, plainText); +/* 通过公钥加密数据 */ +string publicKey = RSAUtility.ExportPublicKey(certificate); +string cipherText = RSAUtility.EncryptWithECB(publicKey, plainText); +``` + +此外，本库还封装了直接加密请求中敏感信息字段的扩展方法。下面给出一个手动调用的示例： + +```csharp +var request = new Models.AddProfitSharingReceiverRequest() +{ + AppId = "AppId", + Type = "PERSONAL_OPENID", + Account = "OpenId", + Name = "姓名明文", + RelationType = "PARTNER" +}; + +string temp = request.Name; // 此时仍是明文 +client.EncryptRequestSensitiveProperty(request); +string temp = request.Name; // 此时已是密文 + +var response = await client.ExecuteAddProfitSharingReceiverAsync(request); +``` + +如果你希望本库在请求前能自动完成这项操作，你可以在构造得到 `WechatApiClient` 对象时指定自动化参数： + +```csharp +var options = new WechatTenpayClientOptions() { AutoEncryptRequestSensitiveProperty = true }; +var client = new WechatTenpayClient(options); +``` + +这样，本库会在实际发出请求前自动为你调用 `EncryptRequestSensitiveProperty()` 方法。 + +需要注意的是，使用该扩展方法前需先下载好平台证书，并存入全局的 `CertificateManager`。有关 `CertificateManager` 的更多介绍，请参阅下一小节。 + +此外，该扩展方法使用反射、并依赖 `WechatTenpaySensitivePropertyAttribute` 特性，相比较手动加密，可能会存在一定的性能开销。 + +--- + +### 通过 `CertificateManager` 管理平台证书信息： + +微信商户平台证书需要通过 API 的方式获取、且可能同时存在多个有效证书，本库提供了一个 `CertificateManager` 类型可用于管理证书信息。 + +你可以在构造得到 `WechatApiClient` 对象时指定证书管理器： + +```csharp +var manager = new InMemoryCertificateManager(); // 为便于后续使用，该对象可使用全局单例的方式声明 +var options = new WechatTenpayClientOptions() { CertificateManager = certManager }; +var client = new WechatTenpayClient(options); +``` + +> 注：`InMemoryCertificateManager` 是本库内置的基于内存实现的证书管理器；你也可自行继承并实现一个 `CertificateManager`，例如利用数据库或 Redis 等方式存取证书信息。 + +你应在后台周期性地调用 `QueryCertificatesAsync()` 方法，并在解密得到证书内容后，记录到证书管理器中： + +```csharp +/* 注意：QueryCertificatesAsync() 接口返回值需解密后再存入 */ +/* 　　　存入的证书式请参考上一小节给出的 CER 证书文件示例 */ +/* 　　　示例项目中也包含一段关于此的演示程序 */ +certManager.SetCertificate(new CertificateEntry("CER 证书序列号", "CER 证书内容", "证书生效时间", "证书过期时间")); +``` + +当然，现在的平台证书离过期还有很久，你也可以选择“偷懒”：提前下载好平台证书，在程序启动时记录一次即可。 + +每个请求模型对象会包含一个名为 `WechatpayCertSerialNumber` 的公共字段，本库会根据该字段的值自动尝试在证书管理器中读取证书内容，并完成请求中敏感信息字段加密： + +```csharp +request.WechatpayCertSerialNumber = "平台证书序列号"; +client.EncryptRequestSensitiveProperty(request); +``` + +对于存在待加密敏感信息字段的请求模型对象而言，如果你不指定 `WechatpayCertSerialNumber` 字段的值，本库会自动从 `CertificateManager` 挑选一个离过期时间最远的证书。 + +--- + +### 自定义 `CertificateManager` 实现 + +上一小节提到，你可自行继承并实现一个 `CertificateManager`，例如利用数据库或 Redis 等方式存取证书信息。 + +下面给出一个利用 Redis 存储的示例代码： + +```csharp +using StackExchange.Redis; + +public class RedisCertificateManager : CertificateManager +{ + private readonly ConnectionMultiplexer _connection; + + public RedisCertificateManager(string connectionString) + { + _connection = ConnectionMultiplexer.Connect(connectionString); + } + + private string GenerateRedisKey(string serialNumber) + { + return string.Format("wxpaypc-{0}", serialNumber); + } + + public override string GetCertificate(string serialNumber) + { + return _connection.StringGet(GenerateRedisKey(serialNumber)); + } + + public override void SetCertificate(string serialNumber, string certificate) + { + _connection.StringSet(GenerateRedisKey(serialNumber), certificate, TimeSpan.FromDays(90)); + } +} +``` \ No newline at end of file diff --git a/docs/WechatTenpayV3/Advanced_ResponseDataDecryption.md b/docs/WechatTenpayV3/Advanced_ResponseDataDecryption.md index 0070f841..8717f126 100644 --- a/docs/WechatTenpayV3/Advanced_ResponseDataDecryption.md +++ b/docs/WechatTenpayV3/Advanced_ResponseDataDecryption.md @@ -8,21 +8,43 @@ > > [《微信支付开发者文档 - 开发指南：敏感信息加解密》](https://pay.weixin.qq.com/wiki/doc/apiv3_partner/wechatpay/wechatpay4_3.shtml) -对于部分接口返回的敏感信息，微信商户平台可能会使用两种方式进行加密： +--- -- 使用商户公钥基于 RSA 算法加密。 +### 解密流程 -- 使用商户 API v3 密钥基于 AEAD-AES-GCM 算法加密。 +对于部分接口响应返回的敏感信息，微信商户平台可能会需要使用以下方式进行解密： -开发者利用本库提供的 `RSAUtility`、`AESUtility` 工具类自行解密相关字段。 +- 使用商户私钥基于 RSA 算法解密。 -此外，本库还封装了直接解密响应的扩展方法，下面给出一个示例： +- 使用商户 API v3 密钥基于 AEAD-AES-GCM 算法解密。 + +开发者利用本库提供的 `RSAUtility`、`AESUtility` 工具类自行解密相关字段。下面给出一个使用 `RSAUtility` 工具类解密数据的示例代码： + +```csharp +string chiperText = "待解密的数据"; +string privateKey = "PKCS#8 私钥内容"; +/* 通过私钥解密数据 */ +string plainText = RSAUtility.DecryptWithECB(privateKey, chiperText); +``` + +此外，本库还封装了直接解密响应中敏感信息字段的扩展方法，下面给出一个示例代码： ```csharp var request = new Models.QueryCertificatesRequest(); var response = await client.ExecuteQueryCertificatesAsync(request); -string cert = response.CertificateList.First().EncryptCertificate.CipherText; // 此时仍是密文 -client.DecryptResponseEncryptedData(ref response); -string cert = response.CertificateList.First().EncryptCertificate.CipherText; // 此时已是明文 +string temp = response.CertificateList.First().EncryptCertificate.CipherText; // 此时仍是密文 +client.DecryptResponseSensitiveProperty(response); +string temp = response.CertificateList.First().EncryptCertificate.CipherText; // 此时已是明文 ``` + +如果你希望本库在响应后能自动完成这项操作，你可以在构造得到 `WechatApiClient` 对象时指定自动化参数： + +```csharp +var options = new WechatTenpayClientOptions() { AutoDecryptResponseSensitiveProperty = true }; +var client = new WechatTenpayClient(options); +``` + +这样，本库会在实际收到响应后自动为你调用 `DecryptResponseSensitiveProperty()` 方法。 + +此外，该扩展方法使用反射、并依赖 `WechatTenpaySensitivePropertyAttribute` 特性，相比较手动解密，可能会存在一定的性能开销。 diff --git a/docs/WechatTenpayV3/Advanced_ResponseSignatureVerification.md b/docs/WechatTenpayV3/Advanced_ResponseSignatureVerification.md index 76ab50a4..47de6e8d 100644 --- a/docs/WechatTenpayV3/Advanced_ResponseSignatureVerification.md +++ b/docs/WechatTenpayV3/Advanced_ResponseSignatureVerification.md @@ -5,25 +5,17 @@ > 请先自行阅读： > > [《微信支付开发者文档 - 开发指南：签名验证》](https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay4_1.shtml) -> -> [《微信支付开发者文档 - 平台证书：更新指引》](https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay5_0.shtml) - -验签过程中需要使用的平台证书，开发者可通过本库封装的 `QueryCertificatesAsync()` 方法来获取。 - -每个响应对象均包含名为 `WechatpayTimestamp`、`WechatpayNonce`、`WechatpaySignature` 的几个公共字段，你可根据官方文档的规则利用本库提供的 `RSAUtility` 工具类自行进行签名验证。 - -具体用法可以参考项目目录下的 _test/SKIT.FlurlHttpClient.Wechat.TenpayV3.UnitTests/WechatTenpayResponseVerificationTests.cs_ 文件给出的测试用例。 --- -### 重要说明 +### 重要须知： 请在开发过程中注意区分**商户证书**和**平台证书**： - **商户证书**用于生成请求的签名，需要在构建客户端配置项时指定（即 `WechatTenpayClientOptions` 对象中的证书序列号和公钥）； - **平台证书**用于验证响应或回调的签名，需要通过接口获取（即 `QueryCertificatesAsync` 方法，注意证书内容需要解密）。 -如果你在后面的验签过程出现验签不通过的情况，请先检查是否混淆了这两个证书。 +如果你在验签过程出现验签不通过的情况，请先检查是否混淆了这两个证书。 关于证书的更多注意事项，请参阅[《微信支付开发者文档 - 常见问题：证书相关》](https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay7_0.shtml) @@ -31,20 +23,22 @@ ### 密钥文件格式说明： -需要注意的是，微信商户平台提供的是 PEM 格式的密钥文件，分为以下几种： +需要注意的是，平台为商户提供的是 PEM 格式的密钥文件，需注意文件格式之间的不同。 -- 以 `-----BEGIN PRIVATE KEY-----` 开头、 `-----END PRIVATE KEY-----` 结尾的是 **PKCS#8 私钥**文件。 +有关密钥文件格式的更多介绍，请参阅本文档[《高级技巧 - 如何加密请求中的敏感数据？》](./Advanced_RequestDataEncryption.md)的有关章节。 -- 以 `-----BEGIN PUBLIC KEY-----` 开头、 `-----END PUBLIC KEY-----` 结尾的是 **PKCS#8 公钥**文件。 +--- -- 以 `-----BEGIN CERTIFICATE--- --` 开头、 `-----END CERTIFICATE-----` 结尾的是 **CER 证书**文件。 +### 验签流程 -谨记，`QueryCertificatesAsync()` 方法返回的结果是 CER 证书，需要先通过 `RSAUtility` 工具类导出 PKCS#8 公钥，再进行签名验证；当然，`RSAUtility` 也封装了直接通过 CER 证书验证签名的方法。 +每个响应对象均包含名为 `WechatpayTimestamp`、`WechatpayNonce`、`WechatpaySignature` 的几个公共字段，你可根据官方文档的规则利用本库提供的 `RSAUtility` 工具类自行进行签名验证。 -下面给出一个示例代码： +具体用法可以参考项目目录下的 _test/SKIT.FlurlHttpClient.Wechat.TenpayV3.UnitTests/WechatTenpayResponseVerificationTests.cs_ 文件给出的测试用例。 + +下面给出一个使用 `RSAUtility` 工具类验证签名的示例代码： ```csharp -string data = "待验签的数据"; +string data = "拼接好的验签数据"; string sign = "待验证的签名"; string certificate = "CER 证书内容"; /* 通过证书验证签名 */ @@ -54,71 +48,24 @@ string publicKey = RSAUtility.ExportPublicKey(certificate); bool ret = RSAUtility.VerifyWithSHA256(publicKey, data, sign); ``` ---- - -### 通过 `CertificateManager` 管理平台证书信息： - -微信商户平台证书需要通过 API 的方式获取、且可能同时存在多个有效证书，本库提供了一个 `CertificateManager` 类型可用于管理证书信息。 - -你可以在构造得到 `WechatApiClient` 对象时指定证书管理器： - -```csharp -var certManager = new InMemoryCertificateManager(); // 为便于后续使用，该对象可使用全局单例的方式声明 -var options = new WechatTenpayClientOptions() { CertificateManager = certManager }; -var client = new WechatTenpayClient(options); -``` - -> 注：`InMemoryCertificateManager` 是本库内置的基于内存实现的证书管理器；你也可自行继承并实现一个 `CertificateManager`，例如利用数据库或 Redis 等方式存取证书信息。 - -你应在后台周期性地调用 `QueryCertificatesAsync()` 方法，并在解密得到证书内容后，记录到证书管理器中： - -```csharp -/* 注意：QueryCertificatesAsync() 接口返回值需解密后再存入 */ -/* 强调：存入的证书式请参考上一小节给出的 CER 证书文件示例 */ -certManager.SetCertificate("CER 证书序列号", "CER 证书内容"); -``` - -当然，现在的平台证书离过期还有很久，你也可以选择“偷懒”：提前下载好平台证书，在程序启动时记录一次即可。 - -每个响应对象会包含一个名为 `WechatpayCertSerialNumber` 的公共字段，本库会根据该字段的值自动尝试在证书管理器中读取证书内容，并完成响应签名的验证： +此外，本库还封装了直接验证响应签名的扩展方法，下面给出一个示例代码： ```csharp bool ret = client.VerifyResponseSignature(response); ``` +需要注意的是，使用该扩展方法前需先下载好平台证书，并存入全局的 `CertificateManager`。有关 `CertificateManager` 的更多介绍，请参阅本文档[《高级技巧 - 如何加密请求中的敏感数据？》](./Advanced_RequestDataEncryption.md)的有关章节。 + --- -### 自定义 `CertificateManager` 实现 +### 调试验签错误： -上一小节提到，你可自行继承并实现一个 `CertificateManager`，例如利用数据库或 Redis 等方式存取证书信息。 - -下面给出一个利用 Redis 存储的示例代码： +由于 `VerifyResponseSignature()` 方法内部会 `try-catch` 做所有异常情况，并直接返回 `false`。为方便开发者在调试阶段排查验签的错误信息，你可以在验证响应签名时指定接收最后一个 `out` 返回参数，该参数中包含了一些异常的原因和相关堆栈信息。 ```csharp -using StackExchange.Redis; - -public class RedisCertificateManager : CertificateManager -{ - private readonly ConnectionMultiplexer _connection; - - public RedisCertificateManager(string connectionString) - { - _connection = ConnectionMultiplexer.Connect(connectionString); - } - - private string GenerateRedisKey(string serialNumber) - { - return string.Format("wxpaypc-{0}", serialNumber); - } - - public override string GetCertificate(string serialNumber) - { - return _connection.StringGet(GenerateRedisKey(serialNumber)); - } - - public override void SetCertificate(string serialNumber, string certificate) - { - _connection.StringSet(GenerateRedisKey(serialNumber), certificate, TimeSpan.FromDays(90)); - } +bool ret = client.VerifyResponseSignature(response, out Exception error); +if (!ret) { + Console.WriteLine(error); + Console.WriteLine(error.InnerException); } ``` \ No newline at end of file diff --git a/docs/WechatTenpayV3/README.md b/docs/WechatTenpayV3/README.md index 424654a1..9c5a9cfe 100644 --- a/docs/WechatTenpayV3/README.md +++ b/docs/WechatTenpayV3/README.md @@ -102,6 +102,8 @@ else - [如何验证响应签名？](./Advanced_ResponseSignatureVerification.md) +- [如何加密请求中的敏感数据？](./Advanced_RequestDataEncryption.md) + - [如何解密响应中的敏感数据？](./Advanced_ResponseDataDecryption.md) - [如何验证回调通知事件签名？](./Advanced_EventDataSignatureVerification.md) diff --git a/docs/WechatWork/Advanced_EventDataDeserialization.md b/docs/WechatWork/Advanced_EventDataDeserialization.md index 203906c9..08f964a3 100644 --- a/docs/WechatWork/Advanced_EventDataDeserialization.md +++ b/docs/WechatWork/Advanced_EventDataDeserialization.md @@ -2,7 +2,7 @@ --- -对于企业微信推送过来的回调通知事件，本库封装了直接解析成事件模型的扩展方法，下面给出一个示例： +对于企业微信推送过来的回调通知事件，本库封装了直接解析成事件模型的扩展方法，下面给出一个示例代码： ```csharp /* 如果是 JSON 格式的通知内容，以 add_schedule 事件为例 */ @@ -55,7 +55,7 @@ switch (msgType) 当用户发送消息给企业微信应用、或某些特定的用户操作引发的事件推送时，开发者可以在响应中返回特定 XML 结构，来对该消息进行响应。 -本库还封装了直接序列化被动回复事件的扩展方法，下面给出一个示例： +本库还封装了直接序列化被动回复事件的扩展方法，下面给出一个示例代码： ```csharp /* 以被动回复文本消息为例 */ diff --git a/docs/WechatWork/Advanced_Extensions.md b/docs/WechatWork/Advanced_Extensions.md index c070f7a9..33e14de6 100644 --- a/docs/WechatWork/Advanced_Extensions.md +++ b/docs/WechatWork/Advanced_Extensions.md @@ -38,7 +38,7 @@ public static class MyFakeClientExtensions } ``` -同样的，你也可自行扩展回调通知事件模型： +同样地，你也可自行扩展回调通知事件模型： ```csharp /* 继承 WechatWorkEvent 实现自定义的 JSON 格式的回调通知事件 */ diff --git a/docs/WechatWork/Advanced_JSSDK.md b/docs/WechatWork/Advanced_JSSDK.md index 6999b2aa..27fab731 100644 --- a/docs/WechatWork/Advanced_JSSDK.md +++ b/docs/WechatWork/Advanced_JSSDK.md @@ -8,7 +8,7 @@ 你可根据官方文档的规则利用本库提供的 `SHA1Utility` 工具类自行进行签名生成。 -此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例： +此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例代码： ```csharp /* 以生成 wx.config() 所需参数为例 */ diff --git a/src/SKIT.FlurlHttpClient.Wechat.TenpayV3/WechatTenpayClient.cs b/src/SKIT.FlurlHttpClient.Wechat.TenpayV3/WechatTenpayClient.cs index 0e04ff2b..35d74d3c 100644 --- a/src/SKIT.FlurlHttpClient.Wechat.TenpayV3/WechatTenpayClient.cs +++ b/src/SKIT.FlurlHttpClient.Wechat.TenpayV3/WechatTenpayClient.cs @@ -26,12 +26,12 @@ namespace SKIT.FlurlHttpClient.Wechat.TenpayV3 public Settings.CertificateManager CertificateManager { get; } /// - /// 获取是否自动加密请求中的敏感字段数据。 + /// 获取是否自动加密请求中的敏感信息字段。 /// protected bool AutoEncryptRequestSensitiveProperty { get; } /// - /// 获取是否自动解密请求中的敏感字段数据。 + /// 获取是否自动解密请求中的敏感信息字段。 /// protected bool AutoDecryptResponseSensitiveProperty { get; }