3.0.0 文档

src/index.jsx

@@ -5,7 +5,7 @@ banner:
   btns: 
     - { name: '开 始', href: '/docs/quickstart.html', primary: true }
     - { name: 'Github >', href: 'https://github.com/buession/buession-security' }
-  caption: '当前版本: v2.3.2'
+  caption: '当前版本: v3.0.0'
 features: 
   - { name: '优雅', desc: '经过精雕细琢，我们带给大家一个精心设计的、标准的、高内聚低耦合的通用类库' }
   - { name: '灵活', desc: '非重复造车轮，我们是整合市面上开源的类库，以标准的接口暴露给上层用户，用户可替换或自行封装同类组件。在此基础上，封装了大量的常用的类库。' }

src/manual/3.0/captcha/index.md

@@ -0,0 +1,127 @@
+# buession-security-captcha 参考手册
+
+
+随着互联网的发展，对应用的安全要求越来越高，在安全的前提下，也需要更加注重用户体验。行为式验证码的诞生，避免了用户去读懂扭曲的图片文字，且行为式验证码背景图片采用多种图像加密技术，采用多种字体，且添加了很多随机效果，能有效防止 OCR 文字识别和暴力破解。
+
+`buession-security-captcha` 目前集成了极验行为验证第三代和第四代、阿里云验证码、腾讯云验证码，屏蔽了各行为验证厂商的调用细节。后续会根据实际情况，接入更多厂商的行为验证码，欢迎各位大神可以提供其它厂商的 key 用于开发测试。
+
+
+---
+
+
+### 安装
+
+```xml
+<dependency>
+    <groupId>com.buession.security</groupId>
+    <artifactId>buession-security-captcha</artifactId>
+    <version>x.x.x</version>
+</dependency>
+```
+
+
+我们通过实现接口 `com.buession.security.captcha.core.RequestData` 定义不同厂商行为验证码需要的请求参数。
+
+* AliYunRequestData：阿里云验证码请求数据
+* GeetestV3RequestData：极验第三代行为验证码请求数据
+* GeetestV4RequestData：极验第四代行为验证码请求数据
+* TencentRequestData：腾讯云验证码请求数据
+
+
+### 阿里云
+
+```java
+import com.buession.security.captcha.CaptchaClient;
+import com.buession.security.captcha.aliyun.AliYunCaptchaClient;
+import com.buession.security.captcha.aliyun.AliYunRequestData;
+import com.buession.security.captcha.core.RequestData;
+import com.buession.httpclient.HttpClient;
+
+HttpClient httpClient;
+CaptchaClient captchaClient = new AliYunCaptchaClient("Your accessKeyId", "Your accessKeySecret", "Your appKey", httpClient);
+
+RequestData request = new AliYunRequestData();
+request.setToken("token");
+request.setSig("sig");
+request.setSessionId("session id");
+request.setScene("ecene");
+request.setRemoteIp("User client ip");
+captchaClient.validate(request);
+```
+
+
+### 极验
+
+```java
+import com.buession.security.captcha.CaptchaClient;
+import com.buession.security.captcha.geetest.GeetestCaptchaClient;
+import com.buession.security.captcha.geetest.api.v4.GeetestV4RequestData;
+import com.buession.security.captcha.core.RequestData;
+import com.buession.httpclient.HttpClient;
+
+HttpClient httpClient;
+CaptchaClient captchaClient = new GeetestCaptchaClient("Your appId", "Your secretKey", "version", httpClient);
+
+RequestData request = new GeetestV4RequestData();
+request.setLotNumber("lot number");
+request.setCaptchaOutput("captcha Output");
+request.setPassToken("pass token");
+request.setGenTime("gen time");
+captchaClient.validate(request);
+```
+
+
+### 腾讯云
+
+```java
+import com.buession.security.captcha.CaptchaClient;
+import com.buession.security.captcha.tencent.TencentCaptchaClient;
+import com.buession.security.captcha.tencent.TencentRequestData;
+import com.buession.security.captcha.core.RequestData;
+import com.buession.httpclient.HttpClient;
+
+HttpClient httpClient;
+CaptchaClient captchaClient = new TencentCaptchaClient("Your secretId", "Your secretKey", httpClient);
+
+RequestData request = new TencentRequestData();
+request.setRandstr("rand str");
+request.setTicket("ticket");
+request.setUserIp("User client ip");
+captchaClient.validate(request);
+```
+
+当然，在您的应用中您可不必这么麻烦的使用，我们已经为您封装好了前端提交参数到 `RequestData` 的转换，您可不必这么麻烦的一个一个的去设置参数值。
+
+在您的 controller 中您可以这么用。
+
+
+```java
+import com.buession.lang.Status;
+import com.buession.web.mvc.Response;
+import com.buession.security.captcha.CaptchaClient;
+import com.buession.security.captcha.aliyun.AliyunParameter;
+import com.buession.security.captcha.validator.servlet.ServletAliYunCaptchaValidator;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping(path = "/captcha")
+public class CaptchamentController {
+
+    @Autowired
+    private CaptchaClient captchaClient;
+
+    @RequestMapping(path = "/validate", method = RequestMethod.GET)
+    public Status validate(HttpServletRequest request){
+        ServletAliYunCaptchaValidator captchaValidator = new ServletAliYunCaptchaValidator(captchaClient, new AliyunParameter());
+        return captchaValidator.validate(request);
+    }
+
+}
+```
+
+以上是基于 servlet 的一个简单实例，`buession-security-captcha` 基于上述模式也可以用于 webflux 环境。`CaptchaValidator` 的每个最终实现，均通过构造函数设置 `com.buession.security.captcha.CaptchaClient` 和 `com.buession.security.captcha.core.Parameter`。通过 `com.buession.security.captcha.core.Parameter` 的实现配置，用户提交的参数名称，也就是说，您可以自定义行为验证码前端提交到后端的参数名称，每一个 `com.buession.security.captcha.core.Parameter` 均设置了默认值。
+
+
+### [API 参考手册>>](https://javadoc.io/doc/com.buession.security/buession-security-captcha/3.0.0/index.html)

src/manual/3.0/captcha/parameter.md

@@ -0,0 +1,44 @@
+# buession-security-captcha 参考手册
+
+
+本文档用于说明 `com.buession.security.captcha.core.Parameter` 和官方参数的对应关系。
+
+
+### 阿里云
+
+|  参数名        | 官方参数名   | 默认值        | 说明           |
+|  ----         | ----        | ----         | ----           |
+|  sessionId    | SessionId   | sessionId    | 会话 ID        |
+|  sig          | Sig         | sig          | 签名串         |
+|  token        | Token       | token        | 请求唯一标识    |
+|  scene        | Scene       | scene        | 场景标识        |
+
+
+### 极验
+
+第三代
+
+|  参数名        | 官方参数名   | 默认值        | 说明                                        |
+|  ----         | ----        | ----         | ----                                        |
+|  challenge    | challenge   | challenge    | 流水号                                       |
+|  seccode      | seccode     | seccode      | 核心校验数据                                  |
+|  validate     | validate    | validate     | 核心校验数据                                  |
+|  userId       | user_id     | user_id      | user_id作为终端用户的唯一标识，确定用户的唯一性   |
+|  clientType   | client_type | client_type  | 客户端类型                                    |
+
+第四代
+
+|  参数名           | 官方参数名          | 默认值            | 说明            |
+|  ----            | ----               | ----             | ----           |
+|  lotNumber       | lot_number         | lot_number       | 验证流水号       |
+|  captchaOutput   | captcha_output     | captcha_output   | 验证输出信息     |
+|  passToken       | pass_token         | pass_token       | 验证通过标识     |
+|  genTime         | gen_time           | gen_time         | 验证通过时间戳   |
+
+
+### 腾讯云
+
+|  参数名        | 官方参数名   | 默认值        | 说明                       |
+|  ----         | ----        | ----         | ----                       |
+|  randStr      | Randstr     | Randstr      | 客户端验证回调的随机串        |
+|  ticket       | Ticket      | Ticket       | 票据                        |

src/manual/3.0/core/index.md

@@ -0,0 +1,30 @@
+# buession-security-core 参考手册
+
+
+该类库为核心包，目前仅实现了 `SameSite` 枚举的定义和数据脱敏工具 `Desensitization`。
+
+
+---
+
+
+### 安装
+
+```xml
+<dependency>
+    <groupId>com.buession.security</groupId>
+    <artifactId>buession-security-core</artifactId>
+    <version>x.x.x</version>
+</dependency>
+```
+
+
+数据脱敏：
+
+```java
+import com.buession.security.core.Desensitization;
+
+String str = Desensitization.encode("13800138000", 3); // 1380***8000
+```
+
+
+### [API 参考手册>>](https://javadoc.io/doc/com.buession.security/buession-security-core/3.0.0/index.html)

src/manual/3.0/crypto/index.md

@@ -0,0 +1,24 @@
+# buession-security-crypto 参考手册
+
+
+数据加密、解密类库，支持：MD5、SHA1、SHA256、SHA512、BASE64 以及 Discuz 加密算法等等接口。
+
+
+---
+
+
+### 安装
+
+```xml
+<dependency>
+    <groupId>com.buession.security</groupId>
+    <artifactId>buession-security-crypto</artifactId>
+    <version>x.x.x</version>
+</dependency>
+```
+
+
+随着互联网的发展，对应用的安全要求越来越高，需要通过各种不同的加密算法，对铭感数据加密，包括可逆的（如：手机号码、身份证号码）和不可逆的（如：密码）。`buession-security-crypto` 基于此背景封装了大量的加解密、散列/哈希等算法，尚未囊括市面上主流的加密算法，会在后续的版本中继续添加。
+
+
+### [API 参考手册>>](https://javadoc.io/doc/com.buession.security/buession-security-crypto/3.0.0/index.html)

src/manual/3.0/index.md

@@ -0,0 +1,16 @@
+# API 参考手册
+
+
+Buession Security API 包含以下目录：
+
+
+|  模块                       | 使用帮助                      | 手册                                                                         |
+|  ----                      | ----                         | ----                                 										   |
+| buession-security-core     | [使用帮助](core/index.md)     | [API 手册](https://javadoc.io/doc/com.buession.security/buession-security-core/3.0.0/)        |
+| buession-security-captcha  | [使用帮助](beans/captcha.md)  | [API 手册](https://javadoc.io/doc/com.buession.security/buession-security-captcha/3.0.0/)       |
+| buession-security-crypto   | [使用帮助](crypto/index.md)   | [API 手册](https://javadoc.io/doc/com.buession.security/buession-security-crypto/3.0.0/)       |
+| buession-security-mcrypt   | [使用帮助](mcrypt/index.md)   | [API 手册](https://javadoc.io/doc/com.buession.security/buession-security-mcrypt/3.0.0/)       |
+| buession-security-pac4j    | [使用帮助](pac4j/index.md)    | [API 手册](https://javadoc.io/doc/com.buession.security/buession-security-pac4j/3.0.0/)       |
+| buession-security-shiro    | [使用帮助](shiro/index.md)    | [API 手册](https://javadoc.io/doc/com.buession.security/buession-security-shiro/3.0.0/)        |
+| buession-security-spring   | [使用帮助](spring/index.md)   | [API 手册](https://javadoc.io/doc/com.buession.security/buession-security-spring/3.0.0/)      |
+| buession-security-web      | [使用帮助](web/index.md)      | [API 手册](https://javadoc.io/doc/com.buession.security/buession-security-web/3.0.0/) |

src/manual/3.0/pac4j/ajaxrequestresolver.md

@@ -0,0 +1,24 @@
+# buession-security-pac4j 参考手册
+
+
+## AjaxRequestResolver
+
+
+pac4j 原生的 AJAX 请求解析器 `AjaxRequestResolver` 的实现 `DefaultAjaxRequestResolver`，以 XML 的形式响应 pac4j 重定向。
+
+```xml
+<?xml version='1.0' encoding='UTF-8'?>
+<partial-response>
+    <redirect url="redirect_url"></redirect>
+</partial-response>
+```
+
+此种，场景增加了响应数据的大小和前端 Ajax 解析的成本和难度。为此，我们扩展了 `JsonAjaxRequestResolver` 和 `TextAjaxRequestResolver` 以 JSON 和文本的形式响应重定向地址，以简化前端 JavaScript 的解析成本和难度。
+
+```json
+{"redirect": {"url": "redirect_url"}}
+```
+
+```text
+redirect_url
+```

src/manual/3.0/pac4j/annotation.md

@@ -0,0 +1,37 @@
+# buession-security-pac4j 参考手册
+
+
+## 注解
+
+
+我们通过注解的形式封装了获取当前登录用户信息的 API。
+
+
+### 注解
+
+|  注解               | 作用域             | 说明                                                            |
+|  ----              | ----              | ----                                                            |
+| @Principal         | 方法参数           | 获取当前登录用户信息，并可以以任何实体类、Map 对象的形式返回            |
+
+
+#### 获取当前登录用户
+
+```java
+@Controller
+@RequestMapping(path = "/test")
+public class TestController {
+
+    @RequestMapping(path = "/principal1")
+    @ResponseBody
+    public User principal1(@Principal User user, ServerHttpResponse response){
+        return user;
+    }
+
+    @RequestMapping(path = "/principal2")
+    @ResponseBody
+    public Map<String, Object> principal2(@Principal Map<String, Object> user, ServerHttpResponse response){
+        return user;
+    }
+
+}
+```

src/manual/3.0/pac4j/index.md

@@ -0,0 +1,21 @@
+# buession-security-pac4j 参考手册
+
+
+对 pac4j 二次封装，集成了 pac4j 和 buji-pac4j。
+
+
+---
+
+
+### 安装
+
+```xml
+<dependency>
+    <groupId>com.buession.security</groupId>
+    <artifactId>buession-security-pac4j</artifactId>
+    <version>x.x.x</version>
+</dependency>
+```
+
+
+### [API 参考手册>>](https://javadoc.io/doc/com.buession.security/buession-security-pac4j/3.0.0/index.html)

src/manual/3.0/shiro/index.md

@@ -0,0 +1,21 @@
+# buession-security-shiro 参考手册
+
+
+apache shiro 二次封装，增加 redis 对 session 和 cache 的管理。
+
+
+---
+
+
+### 安装
+
+```xml
+<dependency>
+    <groupId>com.buession.security</groupId>
+    <artifactId>buession-security-shiro</artifactId>
+    <version>x.x.x</version>
+</dependency>
+```
+
+
+### [API 参考手册>>](https://javadoc.io/doc/com.buession.security/buession-security-shiro/3.0.0/index.html)

src/manual/3.0/spring/index.md

@@ -0,0 +1,23 @@
+# buession-security-spring 参考手册
+
+
+集成 spring security 框架。
+
+
+---
+
+
+### 安装
+
+```xml
+<dependency>
+    <groupId>com.buession.security</groupId>
+    <artifactId>buession-security-spring</artifactId>
+    <version>x.x.x</version>
+</dependency>
+```
+
+该模块无功能，仅仅整合把 spring security 的依赖整合进来了。
+
+
+### [API 参考手册>>](https://javadoc.io/doc/com.buession.security/buession-security-spring/3.0.0/index.html)