From 42272049e50e462b2b7d70a3d2c0bdf0eb65972a Mon Sep 17 00:00:00 2001 From: Fu Diwei Date: Wed, 22 May 2024 17:55:59 +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 --- docs/WechatApi/Basic_SecurityAPI.md | 61 +++++++++++++++++++ docs/WechatApi/README.md | 3 + src/SKIT.FlurlHttpClient.Wechat.Api/README.md | 1 + 3 files changed, 65 insertions(+) create mode 100644 docs/WechatApi/Basic_SecurityAPI.md diff --git a/docs/WechatApi/Basic_SecurityAPI.md b/docs/WechatApi/Basic_SecurityAPI.md new file mode 100644 index 00000000..4658eb4f --- /dev/null +++ b/docs/WechatApi/Basic_SecurityAPI.md @@ -0,0 +1,61 @@ +## 如何接入安全鉴权模式？ + +--- + +> 请先自行阅读： +> +> [《微信官方文档 - 开发前必读：安全鉴权模式介绍》](https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/getting_started/signature-verify.html) + +自 v3.2.0 版本起，本库支持接入微信安全鉴权模式。 + +--- + +### 接入指引 + +在微信公众平台或微信开放平台启用 API 加密及签名校验后，你需要在原有的项目代码基础上做出如下两点调整。 + +首先，构造得到 `WechatApiClient` 对象的方式与原有方式基本一致，只需额外指定与安全鉴权模式相关的参数： + +```csharp +var options = new WechatApiClientOptions() +{ + // 其他配置项略 + SecurityApiEnabled = true, + SecurityApiSymmetricAlgorithm = Constants.SecurityApiSymmetricAlgorithms.AES, + SecurityApiSymmetricNumber = "AES/SM4 对称加密密钥编号", + SecurityApiSymmetricKey = "AES/SM4 对称加密密钥", + SecurityApiAsymmetricAlgorithm = Constants.SecurityApiAsymmetricAlgorithms.RSA, + SecurityApiAsymmetricNumber = "RSA/SM2 非对称加密私钥编号", + SecurityApiAsymmetricPrivateKey = "RSA/SM2 非对称加密私钥" +}; +var client = WechatApiClientBuilder.Create(options).Build(); +``` + +这样，就已经完成了接入安全鉴权模式的全部流程。相关 API 的调用方式与原有方式完全一致。 + +--- + +### 全部 API 加密及签名 + +默认情况下，启用安全鉴权模式后本库也只会对部分关键 API 自动加密及签名。 + +完整的关键 API 清单可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Api/Interceptors/WechatApiSecurityApiInterceptor_ 文件的 `SIGN_REQUIRED_URLS` 的常量。 + +如果你需要开启全部 API 加密及签名，请在上文的基础上额外设置： + +```csharp +var options = new WechatApiClientOptions() +{ + // 其他配置项略 + SecurityApiCustomRequestPathMatcher = (url) => + { + if (url == "/sns/auth") + return true; + else if (url == "/sns/userinfo") + return true; + + return false; + } +}; +var client = WechatApiClientBuilder.Create(options).Build(); +``` diff --git a/docs/WechatApi/README.md b/docs/WechatApi/README.md index 72ec134e..208d0793 100644 --- a/docs/WechatApi/README.md +++ b/docs/WechatApi/README.md @@ -9,6 +9,7 @@ - 基于微信公众平台 & 微信开放平台 API 封装。 - 提供了微信公众平台 & 微信开放平台所需的 AES、SHA-1、HMAC-SHA-256 等算法工具类。 - 提供了 JS-SDK 签名、解析回调通知事件等扩展方法。 +- 支持 API 安全鉴权模式（支持接入 AES+RSA 和 SM4+SM2 两种算法），自动加密并签名请求，自动解密响应。 --- @@ -91,6 +92,8 @@ else - [如何自定义额外的 API 接口？](./Basic_Extensions.md) +- [如何接入安全鉴权模式？](./Basic_SecurityAPI.md) + --- ## 高级技巧 diff --git a/src/SKIT.FlurlHttpClient.Wechat.Api/README.md b/src/SKIT.FlurlHttpClient.Wechat.Api/README.md index 5d2f3fb9..1f8c6651 100644 --- a/src/SKIT.FlurlHttpClient.Wechat.Api/README.md +++ b/src/SKIT.FlurlHttpClient.Wechat.Api/README.md @@ -11,6 +11,7 @@ - 基于微信公众平台 & 微信开放平台 API 封装。 - 提供了微信公众平台 & 微信开放平台所需的 AES、SHA-1、HMAC-SHA-256 等算法工具类。 - 提供了 JS-SDK 签名、解析回调通知事件等扩展方法。 +- 支持 API 安全鉴权模式（支持接入 AES+RSA 和 SM4+SM2 两种算法），自动加密并签名请求，自动解密响应。 ---