support plantuml

pom.xml

@@ -16,13 +16,14 @@
         <maven.compiler.source>8</maven.compiler.source>
         <maven.compiler.target>8</maven.compiler.target>
 
-        <asciidoctor-maven-plugin.version>2.2.4</asciidoctor-maven-plugin.version>
+        <asciidoctor.maven.plugin.version>3.0.0</asciidoctor.maven.plugin.version>
+        <asciidoctorj.version>2.5.13</asciidoctorj.version>
+        <asciidoctorj.diagram.version>2.3.1</asciidoctorj.diagram.version>
+        <jruby.version>9.4.6.0</jruby.version>
 
-        <!--        <asciidoctorj.version>2023.26</asciidoctorj.version>-->
-        <!--        <asciidoctorj-diagram.version>2.2.10</asciidoctorj-diagram.version>-->
         <!--        <asciidoctorj-pdf.version>2.3.9</asciidoctorj-pdf.version>-->
         <spring-asciidoctor-backends.version>0.0.7</spring-asciidoctor-backends.version>
-<!--        <jruby.version>9.4.3.0</jruby.version>-->
+
 
     </properties>
 
@@ -77,12 +78,41 @@
             <plugin>
                 <groupId>org.asciidoctor</groupId>
                 <artifactId>asciidoctor-maven-plugin</artifactId>
-                <version>${asciidoctor-maven-plugin.version}</version>
+                <version>${asciidoctor.maven.plugin.version}</version>
+                <dependencies>
+                    <dependency>
+                        <groupId>io.spring.asciidoctor.backends</groupId>
+                        <artifactId>spring-asciidoctor-backends</artifactId>
+                        <version>0.0.7</version>
+                    </dependency>
+                    <!-- Comment this section to use the default jruby artifact provided by the plugin -->
+                    <dependency>
+                        <groupId>org.jruby</groupId>
+                        <artifactId>jruby</artifactId>
+                        <version>${jruby.version}</version>
+                    </dependency>
+                    <!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
+                    <dependency>
+                        <groupId>org.asciidoctor</groupId>
+                        <artifactId>asciidoctorj</artifactId>
+                        <version>${asciidoctorj.version}</version>
+                    </dependency>
+                    <dependency>
+                        <groupId>org.asciidoctor</groupId>
+                        <artifactId>asciidoctorj-diagram</artifactId>
+                        <version>${asciidoctorj.diagram.version}</version>
+                    </dependency>
+                </dependencies>
                 <configuration>
                     <sourceDirectory>src/docs/asciidoc</sourceDirectory>
                     <!-- Attributes common to all output formats -->
+                    <requires>
+<!--                        <require>asciidoctor-bibliography</require>-->
+<!--                        <require>plantuml</require>-->
+                        <require>asciidoctor-diagram</require>
+                    </requires>
                     <attributes>
-                        <sourcedir>${project.build.sourceDirectory}</sourcedir>
+<!--                        <sourcedir>${project.build.sourceDirectory}</sourcedir>-->
 <!--                        <relative-basedir>true</relative-basedir>-->
                         <lang>zh-CN</lang>
                         <base-url>https://doc.itlym.cn/</base-url>
@@ -93,10 +123,6 @@
 <!--                            <require>${project.basedir}/src/main/resources/nofollow_processor.rb</require>-->
 <!--                        </requires>-->
 <!--                        引用 -->
-                        <requires>
-                            <require>asciidoctor-bibliography</require>
-                            <require>plantuml</require>
-                        </requires>
                         <doctype>article</doctype>
                         <docdir>.</docdir>
                     </attributes>
@@ -110,49 +136,18 @@
                         </goals>
                         <configuration>
                             <backend>spring-html</backend>
+                            <attributes>
+                                <imagesdir>./images</imagesdir>
+                                <toc>left</toc>
+                                <icons>font</icons>
+                                <sectanchors>true</sectanchors>
+                                <idprefix/>
+                                <idseparator>-</idseparator>
+                            </attributes>
                         </configuration>
                     </execution>
                 </executions>
-                <dependencies>
-                    <dependency>
-                        <groupId>io.spring.asciidoctor.backends</groupId>
-                        <artifactId>spring-asciidoctor-backends</artifactId>
-                        <version>${spring-asciidoctor-backends.version}</version>
-                    </dependency>
-<!--                    <dependency>-->
-<!--                        <groupId>org.jruby</groupId>-->
-<!--                        <artifactId>jruby-complete</artifactId>-->
-<!--                        <version>${jruby.version}</version>-->
-<!--                    </dependency>-->
-                </dependencies>
             </plugin>
-
-            <!-- copy resources to be served -->
-            <!--            <plugin>-->
-            <!--                <groupId>org.apache.maven.plugins</groupId>-->
-            <!--                <artifactId>maven-resources-plugin</artifactId>-->
-            <!--                <version>2.6</version>-->
-            <!--                <executions>-->
-            <!--                    <execution>-->
-            <!--                        <id>copy-asciidoc-resources</id>-->
-            <!--                        <phase>process-resources</phase>-->
-            <!--                        <goals>-->
-            <!--                            <goal>copy-resources</goal>-->
-            <!--                        </goals>-->
-            <!--                        <configuration>-->
-            <!--                            <resources>-->
-            <!--                                <resource>-->
-            <!--                                    <directory>target/generated-docs</directory>-->
-            <!--                                    <includes>-->
-            <!--                                        <include>**/*</include>-->
-            <!--                                    </includes>-->
-            <!--                                </resource>-->
-            <!--                            </resources>-->
-            <!--                            <outputDirectory>src/main/resources/static</outputDirectory>-->
-            <!--                        </configuration>-->
-            <!--                    </execution>-->
-            <!--                </executions>-->
-            <!--            </plugin>-->
         </plugins>
     </build>
 

src/main/asciidoc/specs/security/negotiate.adoc

@@ -39,6 +39,116 @@ canonical={canonical}
 
 * 每一次的协商，都会生成一个唯一的 `X-Sid` ，用于双方后续的通信。当服务端发现 `X-Sid` 过期时，需要返回约定好的错误码，让客户端重新发起协商和请求。
 
+=== 普通流程
+
+[plantuml,communication-progress-normal]
+....
+@startuml
+
+participant client
+participant server
+
+title 普通请求
+
+activate client
+client -> server: 请求信息
+
+activate server
+server -> server: 处理业务逻辑....
+client <-- server: 响应信息
+deactivate server
+
+
+client -> client: 处理业务逻辑....
+deactivate client
+@enduml
+....
+
+=== 协商流程
+
+[plantuml,communication-progressnegotiation]
+....
+@startuml
+
+participant client
+participant server
+
+title 安全请求
+
+activate client
+client -> client: 检查缓存：是否已与\nserver建立安全通信
+
+opt 未协商密钥
+client --[#blue]> server: <font color="#blue">协商密钥
+end
+
+client -> client: 根据协商结果，生成随机**数据密钥DK**
+client -> client: 使用**数据密钥DK**加密敏感信息
+client -> client: 使用**协商密钥DK**加密**数据密钥DK**，\n并销毁**数据密钥DK**
+client -> client: 使用client私钥，为以上信息签名
+
+client -> server: 敏感信息、**加密数据密钥DK**、签名
+activate server
+
+server -> server: 使用client公钥校验签名
+server -> server: 使用**协商密钥DK**解密**数据密钥DK**
+server -> server: 使用**数据密钥DK**解密敏感信息
+
+server -> server: <font color="#aaaaaa">处理业务逻辑....
+
+server -> server: 根据协商结果，生成随机**数据密钥DK2**
+server -> server: 使用**数据密钥DK2**加密敏感信息2
+server -> server: 使用**协商密钥DK**加密**数据密钥DK2**，\n并销毁**数据密钥DK2**
+server -> server: 使用server私钥，为以上信息签名2
+
+client <-- server: 响应敏感信息、**加密数据密钥DK2**、签名2
+deactivate server
+
+
+client -> client: 使用server公钥校验签名
+client -> client: 使用**协商密钥DK**解密**数据密钥DK2**
+client -> client: 使用**数据密钥DK2**解密敏感信息2
+client -> client: <font color="#aaaaaa">处理业务逻辑....
+
+deactivate client
+@enduml
+....
+
+=== 协商过程
+
+
+[plantuml,negotiation-progress]
+....
+@startuml
+
+participant client
+participant server
+
+title 密钥协商
+
+activate client
+client -> client: 创建 **Client密钥对** + token
+client -> server: 密钥协商\n(sessionId、**Client公钥**、token)
+
+activate server
+server -> server: 校验token
+server -> server: 创建 **Server密钥对** + token
+server -> server: 使用 DH + ECC 算法，\n根据**Server密钥对** + **Client公钥**\n进行密钥协商，\n得到 **协商密钥**
+server -> server: 根据client支持算法 + server 支持算法，确认双方支持的密钥算法
+server -> server: 根据 server公钥 创建 token
+client <-- server: server、数据密钥算法、token
+deactivate server
+
+client -> client: 校验token
+client -> client: 使用 DH + ECC 算法，\n根据**Client密钥对** + **Server公钥**\n进行密钥协商，\n得到 **协商密钥**
+
+
+deactivate client
+@enduml
+....
+
+== 密钥协商流程明细
+
 === 客户端-发起协商请求
 
 . 生成 `ECDH` 的公私钥对（公钥 `ClientPublicKey` 和私钥 `ClientPrivateKey`）
@@ -106,6 +216,8 @@ canonical={canonical}
 至此，协商阶段结束。为了保证客户端发起时，服务端信息未失效，故设计中客户端缓存需提前过期。如 `expireTime /= 2` 或减少固定时间等。
 ====
 
+== 数据传输明细流程
+
 === 客户端-发起数据传输请求
 
 . 查找是否已与目标服务有进行协商且未过期
@@ -132,13 +244,11 @@ canonical={canonical}
 为了避免客户请求前未过期，收到服务端响应时缓存意外过期情况。可以在请求前通过快照机制处理，不推荐判断是否 `即将过期` （过期时间小于接口最大超时时间）。
 ====
 
-=== 服务端-数据传输处理
-
-==== 处理前解密
+=== 服务端-处理前解密
 
 业务处理前先进行 <<_解密流程>>
 
-==== 业务处理后响应前加密
+=== 服务端-业务处理后响应前加密
 
 TIP: 见 <<_加密流程>>
 
@@ -146,9 +256,6 @@ TIP: 见 <<_加密流程>>
 
 TIP: 见 <<_加密流程>>
 
-
-// end::main[]
-
 == 加解密流程说明
 
 === 加密流程