readme更新

(cherry picked from commit b00c7db9e119451a087915e7b701a6c1acca8ec3)

README.md

@@ -2,6 +2,7 @@
 # 代码混淆之class-winter
 
 - [代码混淆之class-winter](#代码混淆之class-winter)
+  - [仓库最新版本](#仓库最新版本)
   - [环境要求](#环境要求)
   - [功能与特性](#功能与特性)
   - [加密](#加密)
@@ -12,7 +13,9 @@
   - [将已加密的包提供给客户使用](#将已加密的包提供给客户使用)
     - [方案](#方案)
     - [示例](#示例)
-  - [QQ群](#QQ群)
+  - [功能扩展案例](#功能扩展案例)
+  - [**FAQ**](#faq)
+  - [QQ群](#qq群)
 
 ---
 
@@ -22,15 +25,15 @@
     <img alt="maven" src="https://img.shields.io/maven-central/v/com.idea-aedi/class-winter-maven-plugin?style=flat-square">
   </a>
 
-<font face="幼圆"  color = "#F53B45">**郑重声明**</font>
+**郑重声明**
 
 [**class-winter**](https://gitee.com/JustryDeng/class-winter) 是本人在学习完 [**class-final(v1.1.9)**](https://gitee.com/roseboy/classfinal) 后，仿照class-final进行编写的，部分思路与class-final一致
 
-## <font  face="幼圆" color = "#3399EA" >环境要求</font>
+## 环境要求
 
-- 支持jdk8语法的环境即可
+- 支持jdk8（8、11、17、21等）语法环境
 
-  > **<font face="幼圆"  color = "#F53B45">本人构建class-winter时，用的jdk版本为：`1.8.0_281`</font>**
+  > **本人构建class-winter时，用的jdk版本为：`1.8.0_281`**
 
   注：tomcat版本不能低于8（部分小版本低的tomcat8可能也不行），否则可能报错
   
@@ -41,18 +44,18 @@
   注：如果有兼容低版本jdk的需求，可以自己下载master分支代码，进行对应修改
   
 
-## <font  face="幼圆" color = "#3399EA" >功能与特性</font>
+## 功能与特性
 
 - 支持war（普通war+可执行war）加密
 - 支持jar（普通jar+可执行jar）加密
 - 支持xml加密（掩耳盗铃版）
 
-## <font  face="幼圆" color = "#3399EA" >加密</font>
+## 加密
 
-- #### <font face="幼圆" ><font face="幼圆"  color = "#86CA5E">**方式一**</font>：通过maven插件自动加密</font>
+- #### **方式一**：通过maven插件自动加密
   ```xml
   <!--
-      class-winter插件``
+      class-winter插件
       注:自Maven3.0.3起, 绑定到同一phase的Maven插件将按照pom.xml中声明的顺序执行
       注:此插件最好放置在同一phase的最后执行。
       注:此插件不具备打包功能，需要在此插件前有打包插件进行项目打包，否则加密不会生效。
@@ -60,7 +63,7 @@
   <plugin>
       <groupId>com.idea-aedi</groupId>
       <artifactId>class-winter-maven-plugin</artifactId>
-      <version>enhance-2.9.5</version>
+      <version>2.9.5</version>
       <!-- 相关配置 -->
       <configuration>
           <!-- <finalName></finalName>-->
@@ -91,20 +94,20 @@
   ```
   注：不必担心信息泄漏问题，使用此方式生成混淆的jar包时，会擦除pom.xml中关于class-winter-plugin的信息。
   
-- #### <font face="幼圆" ><font face="幼圆"  color = "#86CA5E">**方式二**</font>：通过 [**class-winter-core.jar**](https://gitee.com/JustryDeng/class-winter/raw/master/class-winter-core/src/test/resources/class-winter-core-enhance-2.9.5.jar) 主动加密</font>
+- #### **方式二**：通过[**class-winter-core.jar**](https://gitee.com/JustryDeng/class-winter/raw/master/class-winter-core/src/test/resources/class-winter-core-2.9.5.jar) 主动加密
 
   ```bash
-  java -jar class-winter-core-enhance-2.9.5.jar originJarOrWar=${要加密的项目.jar或.war包} includePrefix=${加密范围} [k3=v3 k4=v4 ...]
+  java -jar class-winter-core-2.9.5.jar originJarOrWar=${要加密的项目.jar或.war包} includePrefix=${加密范围} [k3=v3 k4=v4 ...]
   # 对于复杂的参数值，可以使用引号引起来
   # linux
-  java -jar class-winter-core-enhance-2.9.5.jar k1='v1' k2='v2'
+  java -jar class-winter-core-2.9.5.jar k1='v1' k2='v2'
   # windows
-  java -jar class-winter-core-enhance-2.9.5.jar k1="v1" k2="v2"
+  java -jar class-winter-core-2.9.5.jar k1="v1" k2="v2"
   ```
 
-## <font  face="幼圆" color = "#3399EA" >加密参数</font>
+## 加密参数
 
-> <font  face="幼圆" color = "#F53B45">**提示：**</font>慎用`cca（尤其）`、`cma`、`cfa`参数，如果要用，请做好充分测试。
+> **提示：** 慎用`cca（尤其）`、`cma`、`cfa`参数，如果要用，请做好充分测试。
 >
 > 原因说明：部分框架在获取某些元数据时，并不全都从已被premain处理后的类中读取，而是直接去对应位置读取资源文件本身（如：spring的`SimpleMetadataReader implements MetadataReader`直接去读取.class文件本身，以知道是否需要将类注册进容器等），因为class-winter会对该位置的资源进行加密（如：使用cca、cma、cfa时会擦除类、方法、字段上的注解信息），因此此时如果直接去.class文件本身获取元信息的话，可能会丢失部分信息（如：被class-winter擦除了的类的注解信息就读取不到）
 >
@@ -128,14 +131,13 @@
     <tr align="center">
     <td>includePrefix</td>
     <td>是</td>
-    <td>通过前缀匹配的形式定位要加密的class，支持正则匹配
-    <br/>
-注：多个通过逗号分割。</td>
+    <td>通过前缀匹配的形式定位要加密的class
+      <br/> 注：也支持正则匹配（使用【.*】匹配所有而不用【*】）
+      <br/> 注：多个通过逗号分割。
+    </td>
     <td>includePrefix=com
-    <br/>
-includePrefix=com,org
- <br/>
-includePrefix=com.*.dao,org
+    <br/>includePrefix=com,org
+    <br/>includePrefix=com.*.dao,org
 </td>
   </tr>
  <tr align="center">
@@ -159,31 +161,30 @@ includePrefix=com.*.dao,org
 <tr align="center">
     <td>caPrefix（依托于cca、cma、cfa开关）</td>
     <td>否</td>
-    <td>作为includePrefi``x的附加设置，依托于cca、cma、cfa开关，清空类、方法、字段上的指定注解（写法同url后面设置参数）
-      <br/>
-注：多个通过|分割，注解请写完全路径例如：com.xx.anno.MyAnnotation  
+    <td>作为includePrefix的附加设置，依托于cca、cma、cfa开关，清空类、方法、字段上的指定注解（写法同url后面设置参数）
+      <br/> 注：多个通过|分割，注解请写完全路径例如：com.xx.anno.MyAnnotation  
     </td>
     <td>includePrefix=com?cca=true&cma=true&cfa=true&caPrefix=com.xx.anno.MyAnnotation|com.bb.anno.MyAnnotation</td>
   </tr>
     <tr align="center">
     <td>excludePrefix</td>
     <td>否</td>
-    <td>通过前缀匹配的形式排除class，不对其加密，支持正则匹配
-    <br/>
-注：多个通过逗号分割。
-<br/>
-注:excludePrefix优先级高于includePrefix。</td>
+        <td>通过前缀匹配的形式排除class，不对其加密
+             <br/> 注：也支持正则匹配（使用【.*】匹配所有而不用【*】）
+             <br/> 注：多个通过逗号分割。
+             <br/> 注：excludePrefix优先级高于includePrefix。
+        </td>
     <td>excludePrefix=com.example.service,com.example.util.*.class</td>
   </tr>
       </tr>
     <tr align="center">
     <td>includeXmlPrefix</td>
     <td>否</td>
-    <td>通过打出来的包中条目的entryName前缀匹配的形式定位要加密的xml，支持正则匹配
-    <br/>
-注：多个通过逗号分割。    
-    <br/>
-注：如果您打出来的加密包是准备作为一个lib包提供给第三方使用的，那么请不要使用此参数，因为解密时是不会解密项目所依赖的lib包中的xml的。</td>
+    <td>通过打出来的包中条目的entryName前缀匹配的形式定位要加密的xml
+        <br/> 注：也支持正则匹配（使用【.*】匹配所有而不用【*】）
+        <br/> 注：多个通过逗号分割。    
+        <br/> 注：如果您打出来的加密包是准备作为一个lib包提供给第三方使用的，那么请不要使用此参数，因为解密时是不会解密项目所依赖的lib包中的xml的。
+    </td>
     <td>includeXmlPrefix=BOOT-INF/classes/
     <br/>
 includeXmlPrefix=BOOT-INF/classes/com/demo/mapper/,BOOT-INF/classes/com/*/dao/</td>
@@ -192,7 +193,8 @@ includeXmlPrefix=BOOT-INF/classes/com/demo/mapper/,BOOT-INF/classes/com/*/dao/</
     <tr align="center">
     <td>excludeXmlPrefix</td>
     <td>否</td>
-    <td>通过打出来的包中条目的entryName前缀匹配的形式排除xml，不对其加密，支持正则匹配
+    <td>通过打出来的包中条目的entryName前缀匹配的形式排除xml，不对其加密
+       <br/> 注：也支持正则匹配（使用【.*】匹配所有而不用【*】）
     <br/>
 注：多个通过逗号分割。</td>
     <td>excludeXmlPrefix=BOOT-INF/classes/com/demo/mapper/
@@ -230,11 +232,11 @@ excludeXmlPrefix=BOOT-INF/classes/com/demo/mapper/,BOOT-INF/classes/com/demo/*/U
     <tr align="center">
     <td>includeLibs</td>
     <td>否</td>
-    <td>指定将lib包也纳入加密范围内，支持正则匹配
-    <br/>
-注:多个通过逗号分割。
-<br/>
-注：lib中的class是否会被加密，还得由includePrefix和excludePrefix决定。</td>
+    <td>指定将lib包也纳入加密范围内
+      <br/> 注：也支持正则匹配（使用【.*】匹配所有而不用【*】）
+      <br/> 注：多个通过逗号分割。
+      <br/> 注：lib中的class是否会被加密，还得由includePrefix和excludePrefix决定。
+    </td>
     <td>includeLibs=a.jar,b.jar,c-.*.jar</td>
   </tr>
     <tr align="center">
@@ -255,7 +257,7 @@ excludeXmlPrefix=BOOT-INF/classes/com/demo/mapper/,BOOT-INF/classes/com/demo/*/U
     <br/>
 注：多个通过逗号分割。
 <br/>
-注:主要用于处理第三方提供的由class-winter加密了的依赖包的场景。
+注：主要用于处理第三方提供的由class-winter加密了的依赖包的场景。
 <br/>
 注：若lib需要密码，那么需要在指定lib的同时通过冒号接上密码。
 <br/>
@@ -273,7 +275,7 @@ alreadyProtectedLibs=a.jar:pwd1,b-1.0.0.jar:pwd2</td>
     <br/>
 注：当为目录时，该目录(含子孙目录)下的所有jar都会被采集作为辅助文件。
 <br/>
-注:主要用于解决因ClassNotFound导致的加密失败问题。</td>
+注：主要用于解决因ClassNotFound导致的加密失败问题。</td>
     <td>supportFile=/abc.jar
     <br/>
 supportFile=/libs</td>
@@ -310,22 +312,17 @@ linux示例：tips='请不要直接使用混淆后的jar/war'</td>
 
 
 
-
-
-
-
-
-## <font  face="幼圆" color = "#3399EA" >解密(启动)</font>
+## 解密(启动)
 
 > `class-winter`支持`JVM`参数校验，通过在JVM参数中加入`-XX:+DisableAttachMechanism`来防止其他工具连接到你的Java程序。这样可以阻止运行至dump class。
 > 
-> 但是有些高级开发者可能会想要使用`sa-jdi` 的 `HSDB` 来 `dump` 字节码。从`enhance-2.8.8`版本开始，支持在启动Java解密时禁用了gHotSpotVMStructs函数，避免使用sa-jdi HSDB 来dump class，提高代码安全性。
-- #### <font  face="幼圆" color = "#86CA5E" >jar解密(启动)</font>
+> 但是有些高级开发者可能会想要使用`sa-jdi` 的 `HSDB` 来 `dump` 字节码。从`2.8.8`版本开始，支持在启动Java解密时禁用了gHotSpotVMStructs函数，避免使用sa-jdi HSDB 来dump class，提高代码安全性。
+- #### jar解密(启动)
   ```bash
   # 假设your-project-encrypted.jar是由class-winter加密后的包，那么你可以这么启动
   java -javaagent:/your-project-encrypted.jar -jar /your-project-encrypted.jar
-  # 也可以用class-winter-core-enhance-2.9.5.jar
-  # java -javaagent:/class-winter-core-enhance-2.9.5.jar -jar /your-project-encrypted.jar
+  # 也可以用class-winter-core-2.9.5.jar
+  # java -javaagent:/class-winter-core-2.9.5.jar -jar /your-project-encrypted.jar
   # 或者指定参数
   # java -javaagent:/your-project-encrypted.jar=debug=true,password=pwd12345 -jar /your-project-encrypted.jar
   # 参数可以引起来(linux)
@@ -334,16 +331,16 @@ linux示例：tips='请不要直接使用混淆后的jar/war'</td>
   # java -javaagent:/your-project-encrypted.jar="debug=true,password=pwd12345" -jar /your-project-encrypted.jar
   ```
 
-- #### <font  face="幼圆" color = "#86CA5E" >war解密(启动)</font>
+- #### war解密(启动)
   > **以Tomcat9为例**
   - linux方式一
 
     编辑tomcat/bin/catalina.sh文件，在最上面加上
 
     ```bash
-    # 如果你有参数， 那么 -javaagent:/class-winter-core-enhance-2.9.5.jar=k1=v1,k2=v2
+    # 如果你有参数， 那么 -javaagent:/class-winter-core-2.9.5.jar=k1=v1,k2=v2
     # tomcat启动往往需要通过decryptProjectPathPrefix指定要解密的路径
-    CATALINA_OPTS="$CATALINA_OPTS -javaagent:/class-winter-core-enhance-2.9.5.jar=debug=true,decryptProjectPathPrefix=/usr/local/xxx/";
+    CATALINA_OPTS="$CATALINA_OPTS -javaagent:/class-winter-core-2.9.5.jar=debug=true,decryptProjectPathPrefix=/usr/local/xxx/";
     export CATALINA_OPTS;
     ```
   
@@ -352,9 +349,9 @@ linux示例：tips='请不要直接使用混淆后的jar/war'</td>
     在tomcat/bin目录下创建setenv.sh文件，并写上
   
     ```bash
-    # 如果你有参数， 那么 -javaagent:/class-winter-core-enhance-2.9.5.jar=k1=v1,k2=v2
+    # 如果你有参数， 那么 -javaagent:/class-winter-core-2.9.5.jar=k1=v1,k2=v2
     # tomcat启动往往需要通过decryptProjectPathPrefix指定要解密的路径
-    JAVA_OPTS="$JAVA_OPTS -javaagent:/class-winter-core-enhance-2.9.5.jar=debug=true,decryptProjectPathPrefix=/usr/local/xxx/";
+    JAVA_OPTS="$JAVA_OPTS -javaagent:/class-winter-core-2.9.5.jar=debug=true,decryptProjectPathPrefix=/usr/local/xxx/";
     export JAVA_OPTS;
     ```
 
@@ -363,9 +360,9 @@ linux示例：tips='请不要直接使用混淆后的jar/war'</td>
     编辑tomcat/bin/catalina.bat文件，在@echo off后加上catalina参数
   
     ```bash
-    rem 如果你有参数， 那么 -javaagent:D:/class-winter-core-enhance-2.9.5.jar=k1=v1,k2=v2
+    rem 如果你有参数， 那么 -javaagent:D:/class-winter-core-2.9.5.jar=k1=v1,k2=v2
     rem tomcat启动往往需要通过decryptProjectPathPrefix指定要解密的路径
-    set CATALINA_OPTS="-javaagent:D:/class-winter-core-enhance-2.9.5.jar=decryptProjectPathPrefix=/D:/tmp/"
+    set CATALINA_OPTS="-javaagent:D:/class-winter-core-2.9.5.jar=decryptProjectPathPrefix=/D:/tmp/"
     ```
   
   - windows方式二
@@ -373,12 +370,12 @@ linux示例：tips='请不要直接使用混淆后的jar/war'</td>
     在tomcat/bin目录下创建setenv.bat文件，并写上
   
     ```bash
-    rem 如果你有参数， 那么 -javaagent:D:/class-winter-core-enhance-2.9.5.jar=k1=v1,k2=v2
+    rem 如果你有参数， 那么 -javaagent:D:/class-winter-core-2.9.5.jar=k1=v1,k2=v2
     rem tomcat启动往往需要通过decryptProjectPathPrefix指定要解密的路径
-    set JAVA_OPTS="-javaagent:D:/class-winter-core-enhance-2.9.5.jar=decryptProjectPathPrefix=/D:/tmp/"
+    set JAVA_OPTS="-javaagent:D:/class-winter-core-2.9.5.jar=decryptProjectPathPrefix=/D:/tmp/"
     ```
   
-- #### <font  face="幼圆" color = "#86CA5E" >IDE解密(启动)</font>
+- #### IDE解密(启动)
 
   > 设置`-javaagent`参数指定class-winter-core或者任一加密包。有必要的话，再搭配`skipProjectPathPrefix`或者`decryptProjectPathPrefix`参数启动即可
 
@@ -386,7 +383,7 @@ linux示例：tips='请不要直接使用混淆后的jar/war'</td>
 
 
 
-## <font  face="幼圆" color = "#3399EA" >解密参数</font>
+## 解密参数
 
 <table>
   <tr align="center">
@@ -441,18 +438,18 @@ linux示例：tips='请不要直接使用混淆后的jar/war'</td>
   </tr>
 </table>
 
-## <font  face="幼圆" color = "#3399EA" >对class-winter本身进行加密</font>
+## 对class-winter本身进行加密
 
 > 感谢小伙伴[Mango](https://gitee.com/mango_ye)对class-winter的优质反馈
 
 - 背景说明：我们利用class-winter混淆项目时，项目是被混淆了，但是class-winter本身还是明文的，这就留下了一些安全隐患（即：那些不指定密码的混淆，可能会被反向破解）
 - 增强支持：我们可以对class-winter本身进行加密，你可以切换至`enhance-*`分支，在首页下载被混淆的class-winter进行测试，或者clone代码，install后进行测试
-- <font face="幼圆"  color = "#F53B45">**声明**</font>：因为在`enhance-*`分支里对class-winter本身进行加密时用到了收费工具allatori（实际上有供学习使用的破解版之类的），所以`enhance-*`分支的代码，本人并未发布至maven官方仓库
+- **声明**：因为在`enhance-*`分支里对class-winter本身进行加密时用到了收费工具allatori（实际上有供学习使用的破解版之类的），所以`enhance-*`分支的代码，本人并未发布至maven官方仓库
 
 
-## <font  face="幼圆" color = "#3399EA" >将已加密的包提供给客户使用</font>
+## 将已加密的包提供给客户使用
 
-### <font  face="幼圆" color = "#86CA5E" >方案</font>
+### 方案
 
 - 方案一（适用于encrypted-A依赖于encrypted-B.jar，启动encrypted-A的情况）
 
@@ -464,7 +461,7 @@ linux示例：tips='请不要直接使用混淆后的jar/war'</td>
 
   利用`-Dloader.path`或其它方案，将encrypted-B.jar外置，并通过`decryptProjectPathPrefix`或`skipProjectPathPrefix`来定位encrypted-B.jar
 
-### <font  face="幼圆" color = "#86CA5E" >示例</font>
+### 示例
 
 > 提示：这里以可执行的jar进行的示例，其余的外置方式也是可以的（如：tomcat部署war包解压后，lib包就相当于是外置的）
 
@@ -601,6 +598,80 @@ linux示例：tips='请不要直接使用混淆后的jar/war'</td>
 | 1      | 机器码支持 | qq号：`85546017`<br /><br />当前（2023-06-11）状态：<br />&emsp;qq名：`╮(╯_╰)╭`<br />&emsp;是否在class-winter QQ群：是 | [点击跳转](https://gitee.com/tts2/class-winter/tree/master) |
 | ...... | ......     | ......                                                       | ......                                                      |
 
+
+
+## **FAQ**
+
+> class-winter初始能力设计理念是，只做通用能力支持，如果没法做到通用，那就干脆不做，需要的话使用者自行扩展
+
+- **1. 加密失败并伴有` Ignore clear-method-body for className [xxx], Cannot find 'yyy'`提示**
+
+  - 原因：类`xxx`中使用到了类`yyy`，但是被加密包中不存在`yyy`类
+
+  - 解决方案1：在`xxx`中引入`yyy类`（或引入`yyy所在包`）
+
+  - 解决方案2：通过加密参数supportFile指定`yyy`所在包为加密辅助包
+
+    注：使用supportFile时，尽量控制指定范围，如果指定的范围太大（如无脑指定整个依赖仓库），引入的相关包太多，可能导致一些意料外的加密问题。如：[issues I9VTG9](https://gitee.com/JustryDeng/class-winter/issues/I9VTG9)
+
+- **2. 是否支持yml等配置文件加密？**
+
+  **不支持。**
+
+  不同的框架加载配置文件的方式不一样，没法写一个通用的加密逻辑，需要的话自行根据所用技术框架自行实现
+
+- **3. 是否支持对lib包里的xml加密？**
+
+  **不支持。**
+
+  首先实现起来相对麻烦，其次即便是（通用）加密也是伪加密。除非自己根据框架进行扩展进行定制加密
+
+- **4. 部分版本spring-boot为啥加密后，启动时读取配置文件内容失败？**
+
+  **配置文件使用.yaml或.properties无此问题；部分版本的spring-boot使用.yml配置文件可能出现部分配置读取失败。**
+
+- **5. 启动时明明按要求指定了JVM参数，为啥还是提示Miss jvm arg？**
+
+  **JVM参数位置不对，要放在-jar xxx.jar之前**
+
+  ```bash
+  # 错误案例
+  java -javaagent:cc-encrypted.jar -jar cc-encrypted.jar -XX:+DisableAttachMechanism
+  # 正确案例
+  java -javaagent:cc-encrypted.jar -XX:+DisableAttachMechanism -jar cc-encrypted.jar 
+  ```
+
+- **6. class-winter是否支持对类名、字段名、方法名等进行混淆？**
+
+  **不支持。**
+
+  需要的话，可结合其它混淆工具（如：allatori等）一起加密，可参考enhance分支
+
+- **7. includeLibs指定了要加密的lib包，为啥没生效？**
+
+  - **如果配置时使用的前缀匹配：** 首先检查指定的前缀是否包含住了指定了lib名，然后检查includePrefix匹配范围是否包含lib中的class
+
+  - **如果配置时使用的模糊匹配：**首先检查正则语法是否配置正确（见：FAQ-8），然后检查includePrefix匹配范围是否包含lib中的class
+
+- **8. 模糊匹配，正则未生效？**
+
+  **如果用正则的话，使用【`.*`】匹配所有而不用【`*`】**
+
+  你可以这么验证自己的正则是否配置对
+  ```java
+  System.err.println(java.util.regex.Pattern.compile("aab.*bcc").matcher("aabXYZbcc").find()); // 输出true则说明正则写法无误
+  ```
+
+- **9. decryptProjectPathPrefix值如何指定？**
+
+  > 请确保先看过了上面【解密参数】里对此参数的说明及示例
+
+  decryptProjectPathPrefix指定的值，将以前缀匹配的形式匹配要解密的文件。
+  
+  - 如果你是war包，那么你可以指定war包解压后对应的war目录
+  - 如果你是jar包，那么直接指定对应的jar文件路径即可
+  - 如果你没有任何头绪，那么你可以先不指定decryptProjectPathPrefix，直接debug启动项目，当因解密失败启动报错时，会debug输出形如**Exist projectPath -> xxx**的信息，该`xxx`即为当前解密失败的文件路径，你可以根据这个路径去反推你的decryptProjectPathPrefix值，然后配置该decryptProjectPathPrefix值再启动即可
+
 ## QQ群
 
 > 群号：727930548