README.md · tts2/class-winter

# 代码混淆之class-winter

- [代码混淆之class-winter](#代码混淆之class-winter)
  - [环境要求](#环境要求)
  - [功能与特性](#功能与特性)
  - [加密](#加密)
  - [加密参数](#加密参数)
  - [解密(启动)](#解密启动)
  - [解密参数](#解密参数)
  - [对class-winter本身进行加密](#对class-winter本身进行加密)
  - [将已加密的包提供给客户使用](#将已加密的包提供给客户使用)
    - [方案](#方案)
    - [示例](#示例)
  - [QQ群](#QQ群)

---

**郑重声明**

[**class-winter**](https://gitee.com/JustryDeng/class-winter) 是本人在学习完 [**class-final(v1.1.9)**](https://gitee.com/roseboy/classfinal) 后，仿照class-final进行编写的，部分思路与class-final一致

## 环境要求

- 支持jdk8语法的环境即可

> **本人构建class-winter时，用的jdk版本为：`1.8.0_281`**

注：tomcat版本不能低于8（部分小版本低的tomcat8可能也不行），否则可能报错
  
  ```bash
  org.apache.catalina.LifecycleException: Failed to start component [StandardEngine[Catalina].StandardHost...
  ```

注：如果有兼容低版本jdk的需求，可以自己下载master分支代码，进行对应修改

## 功能与特性

- 支持war（普通war+可执行war）加密
- 支持jar（普通jar+可执行jar）加密
- 支持xml加密（掩耳盗铃版）

## 加密

- #### **方式一**：通过maven插件自动加密
 ```xml
 
 <plugin>
 <groupId>com.idea-aedi</groupId>
 <artifactId>class-winter-maven-plugin</artifactId>
 <version>2.7.9</version>
 
 <configuration>
 
 <includePrefix>加密范围</includePrefix>
 
 
 
 
 
 
 
 
 
 
 
 
 
 </configuration>
 <executions>
 <execution>
 <phase>package</phase>
 <goals>
 <goal>class-winter</goal>
 </goals>
 </execution>
 </executions>
 </plugin>
 ```
 注：不必担心信息泄漏问题，使用此方式生成混淆的jar包时，会擦除pom.xml中关于class-winter-plugin的信息。
 
- #### **方式二**：通过 [**class-winter-core.jar**](https://gitee.com/JustryDeng/class-winter/raw/master/class-winter-core/src/test/resources/class-winter-core-2.7.9.jar) 主动加密

```bash
  java -jar class-winter-core-2.7.9.jar originJarOrWar=${要加密的项目.jar或.war包} includePrefix=${加密范围} [k3=v3 k4=v4 ...]
  # 对于复杂的参数值，可以使用引号引起来
  # linux
  java -jar class-winter-core-2.7.9.jar k1='v1' k2='v2'
  # windows
  java -jar class-winter-core-2.7.9.jar k1="v1" k2="v2"
  ```

## 加密参数

<table>
 <tr align="center">
 <td>参数</td>
 <td>是否必填</td>
 <td>说明</td>
 <td>示例</td>
 </tr>
 <tr align="center">
 <td>originJarOrWar</td>
 <td>是</td>
 <td>指定要加密的jar/war文件
 注：当使用maven插件进行自动加密时，此参数非必填，不填则自动获取。
 注：当使用maven插件进行自动加密时，可结合maven相关占位符进行相对定位。如：${project.basedir}/../../your-project.jar</td>
 <td>originJarOrWar=/my-project.jar</td>
 </tr>
 <tr align="center">
 <td>includePrefix</td>
 <td>是</td>
 <td>通过前缀匹配的形式定位要加密的class
 
注：多个通过逗号分割。</td>
 <td>includePrefix=com
 
includePrefix=com,org</td>
 </tr>
 <tr align="center">
 <td>excludePrefix</td>
 <td>否</td>
 <td>通过前缀匹配的形式排除class，不对其加密
 
注：多个通过逗号分割。
 
注:excludePrefix优先级高于includePrefix。</td>
 <td>excludePrefix=com.example.service,com.example.util.StrUtil.class</td>
 </tr>
 </tr>
 <tr align="center">
 <td>includeXmlPrefix</td>
 <td>否</td>
 <td>通过打出来的包中条目的entryName前缀匹配的形式定位要加密的xml
 
注：多个通过逗号分割。 
 
注：如果您打出来的加密包是准备作为一个lib包提供给第三方使用的，那么请不要使用此参数，因为解密时是不会解密项目所依赖的lib包中的xml的。</td>
 <td>includeXmlPrefix=BOOT-INF/classes/
 
includeXmlPrefix=BOOT-INF/classes/com/demo/mapper/,BOOT-INF/classes/com/demo/dao/</td>
 </tr>
 </tr>
 <tr align="center">
 <td>excludeXmlPrefix</td>
 <td>否</td>
 <td>通过打出来的包中条目的entryName前缀匹配的形式排除xml，不对其加密
 
注：多个通过逗号分割。</td>
 <td>excludeXmlPrefix=BOOT-INF/classes/com/demo/mapper/
 
excludeXmlPrefix=BOOT-INF/classes/com/demo/mapper/,BOOT-INF/classes/com/demo/dao/UserDao.xml</td>
 </tr>
 </tr>
 <tr align="center">
 <td>toCleanXmlChildElementName</td>
 <td>否</td>
 <td>加密xml中的哪些一级元素
 
注：默认值为resultMap,sql,insert,update,delete,select
 
注：多个通过逗号分割。</td>
 <td>toCleanXmlChildElementName=select,delete,resultMap</td>
 </tr>
 <tr align="center">
 <td>finalName</td>
 <td>否</td>
 <td>指定加密后生成的jar包名
 
注：若finalName与加密的包一致，那么生成的加密后的包会覆盖原来的包。 
注：支持相对路径。 比如:../../tmp/my-project 就会在相对目录../../tmp下生成加密包my-project.jar。</td>
 <td>finalName=mine-project</td>
 </tr>
 <tr align="center">
 <td>password</td>
 <td>否</td>
 <td>主动指定密码
 
注：密码不能包含空格和逗号。</td>
 <td>password=123456</td>
 </tr>
 <tr align="center">
 <td>includeLibs</td>
 <td>否</td>
 <td>指定将lib包也纳入加密范围内
 
注:多个通过逗号分割。
 
注：lib中的class是否会被加密，还得由includePrefix和excludePrefix决定。</td>
 <td>includeLibs=a.jar,b.jar</td>
 </tr>
 <tr align="center">
 <td>alreadyProtectedRootDir</td>
 <td>否</td>
 <td>指明已加密lib包所在根目录(，可为空，为空时自动根据当前是jar还是war，去包内对应找lib)
 
注：当指定此参数时，也会优先去jar/war内部找对应的lib包，找不到时，才会去此参数指定的根目录下找lib包。
 
注：在一些外置lib的项目中，可能需要用到此参数；如果是内置lib，忽略此参数即可。
 注：此参数由2.7.0版本开始支持</td>
 <td>alreadyProtectedRootDir=/lib</td>
 </tr>
 <tr align="center">
 <td>alreadyProtectedLibs</td>
 <td>否</td>
 <td>指明项目所依赖的lib中，哪些lib本身就已经是被class-winter加密了的
 
注：多个通过逗号分割。
 
注:主要用于处理第三方提供的由class-winter加密了的依赖包的场景。
 
注：若lib需要密码，那么需要在指定lib的同时通过冒号接上密码。
 
注：如果lib有密码，那么密码不能包含逗号。</td>
 <td>alreadyProtectedLibs=a.jar,b-1.0.0.jar
 
alreadyProtectedLibs=a.jar,b-1.0.0.jar:pwd123
 
alreadyProtectedLibs=a.jar:pwd1,b-1.0.0.jar:pwd2</td>
 </tr>
 <tr align="center">
 <td>supportFile</td>
 <td>否</td>
 <td>指定一个加密辅助jar文件（或jar文件所在的目录）
 
注：当为目录时，该目录(含子孙目录)下的所有jar都会被采集作为辅助文件。
 
注:主要用于解决因ClassNotFound导致的加密失败问题。</td>
 <td>supportFile=/abc.jar
 
supportFile=/libs</td>
 </tr>
 <tr align="center">
 <td>jvmArgCheck</td>
 <td>否</td>
 <td>设置当启动混淆包时，必须要有的jvm参数
 
注：多个通过逗号分割。
 
注：大小写不敏感。
 
如:通过设置-XX:+DisableAttachMechanism防止运行时dump class，以提高安全性。</td>
 <td>jvmArgCheck=-XX:+DisableAttachMechanism,-Xms2048M</td>
 </tr>
 <tr align="center">
 <td>tips</td>
 <td>否</td>
 <td>指定提示语。
 
注：当直接使用加密后的jar/war时，用到了加密了的类后，会先System.err.println输出此tips,然后System.exit退出程序。</td>
 <td>windows示例：tips="请不要直接使用混淆后的jar/war"
 
linux示例：tips='请不要直接使用混淆后的jar/war'</td>
 </tr>
 <tr align="center">
 <td>debug</td>
 <td>否</td>
 <td>是否开启debug模式</td>
 <td>debug=true</td>
 </tr>
</table>

## 解密(启动)

通过-javaagent指定代理进行解密启动。
- #### jar解密(启动)
 ```bash
 # 假设your-project-encrypted.jar是由class-winter加密后的包，那么你可以这么启动
 java -javaagent:/your-project-encrypted.jar -jar /your-project-encrypted.jar
 # 也可以用class-winter-core-2.7.9.jar
 # java -javaagent:/class-winter-core-2.7.9.jar -jar /your-project-encrypted.jar
 # 或者指定参数
 # java -javaagent:/your-project-encrypted.jar=debug=true,password=pwd12345 -jar /your-project-encrypted.jar
 # 参数可以引起来(linux)
 # java -javaagent:/your-project-encrypted.jar='debug=true,password=pwd12345' -jar /your-project-encrypted.jar
 # 参数可以引起来(windows)
 # java -javaagent:/your-project-encrypted.jar="debug=true,password=pwd12345" -jar /your-project-encrypted.jar
 ```

- #### war解密(启动)
 > **以Tomcat9为例**
 - linux方式一

编辑tomcat/bin/catalina.sh文件，在最上面加上

```bash
    # 如果你有参数， 那么 -javaagent:/class-winter-core-2.7.9.jar=k1=v1,k2=v2
    # tomcat启动往往需要通过decryptProjectPathPrefix指定要解密的路径
    CATALINA_OPTS="$CATALINA_OPTS -javaagent:/class-winter-core-2.7.9.jar=debug=true,decryptProjectPathPrefix=/usr/local/xxx/";
    export CATALINA_OPTS;
    ```
  
  - linux方式二
  
    在tomcat/bin目录下创建setenv.sh文件，并写上
  
    ```bash
    # 如果你有参数， 那么 -javaagent:/class-winter-core-2.7.9.jar=k1=v1,k2=v2
    # tomcat启动往往需要通过decryptProjectPathPrefix指定要解密的路径
    JAVA_OPTS="$JAVA_OPTS -javaagent:/class-winter-core-2.7.9.jar=debug=true,decryptProjectPathPrefix=/usr/local/xxx/";
    export JAVA_OPTS;
    ```

- windows方式一

编辑tomcat/bin/catalina.bat文件，在@echo off后加上catalina参数
 
 ```bash
 rem 如果你有参数， 那么 -javaagent:D:/class-winter-core-2.7.9.jar=k1=v1,k2=v2
 rem tomcat启动往往需要通过decryptProjectPathPrefix指定要解密的路径
 set CATALINA_OPTS="-javaagent:D:/class-winter-core-2.7.9.jar=decryptProjectPathPrefix=/D:/tmp/"
 ```
 
 - windows方式二
 
 在tomcat/bin目录下创建setenv.bat文件，并写上
 
 ```bash
 rem 如果你有参数， 那么 -javaagent:D:/class-winter-core-2.7.9.jar=k1=v1,k2=v2
 rem tomcat启动往往需要通过decryptProjectPathPrefix指定要解密的路径
 set JAVA_OPTS="-javaagent:D:/class-winter-core-2.7.9.jar=decryptProjectPathPrefix=/D:/tmp/"
 ```
 
- #### IDE解密(启动)

> 设置`-javaagent`参数指定class-winter-core或者任一加密包。有必要的话，再搭配`skipProjectPathPrefix`或者`decryptProjectPathPrefix`参数启动即可

![示例说明](./file/4.png)

## 解密参数

<table>
 <tr align="center">
 <td>参数</td>
 <td>是否必填</td>
 <td>说明</td>
 <td>示例</td>
 </tr>
 <tr align="center">
 <td>password</td>
 <td>否</td>
 <td>指定解密密码</td>
 <td>password=pwd123</td>
 </tr>
 <tr align="center">
 <td>passwordFromFile</td>
 <td>否</td>
 <td>从指定文件中读取文本作为解密密码 注：此参数由2.4.0版本开始支持</td>
 <td>passwordFromFile=/my-pwd-file.txt</td>
 </tr>
 <tr align="center">
 <td>passwordFromShell</td>
 <td>否</td>
 <td>执行shell文件中的代码，并以其返回值作为解密密码 注：此参数由2.4.0版本开始支持</td>
 <td>passwordFromShell=/my-pwd-file.shell</td>
 </tr>
 <tr align="center">
 <td>skipProjectPathPrefix</td>
 <td>否</td>
 <td>是否跳过指定前缀的项目路径（当class-winter解密逻辑试图解析那些进入premain但是非class-winter加密项目时，会因为获取印章失败Obtain project seal fail而停止，此时如果确认这个项目没有加密文件的话，可以使用此参数跳过） 注：值中的路径分隔符请统一使用/ 注：不知道此值怎么填的，可以把debug代开， 观察日志 Exist projectPath -> xxx 或输出所有的projectPath 注：此参数由2.6.4版本开始支持</td>
 <td>
 skipProjectPathPrefix=/D:/apache-tomcat-9.0.71/bin/
 
 多个通过___符号拼接：skipProjectPathPrefix=/D:/apache-tomcat-9.0.71/bin/___/D:/jd/classpath/lib/</td>
 </tr>
 </tr>
 <tr align="center">
 <td>decryptProjectPathPrefix</td>
 <td>否</td>
 <td>是否仅解密指定前缀的项目路径（优先级低于skipProjectPathPrefix） 注：值中的路径分隔符请统一使用/ 注：不知道此值怎么填的，可以把debug代开， 观察日志 Exist projectPath -> xxx 或输出所有的projectPath 注：此参数由2.6.6版本开始支持</td>
 <td>
 decryptProjectPathPrefix=/D:/apache-tomcat-9.0.71/bin/
 
 多个通过___符号拼接：decryptProjectPathPrefix=/D:/apache-tomcat-9.0.71/bin/___/D:/jd/classpath/lib/</td>
 </tr>
 </tr>
 <tr align="center">
 <td>debug</td>
 <td>否</td>
 <td>是否开启debug模式</td>
 <td>debug=true</td>
 </tr>
</table>

## 对class-winter本身进行加密

> 感谢小伙伴[Mango](https://gitee.com/mango_ye)对class-winter的优质反馈

- 背景说明：我们利用class-winter混淆项目时，项目是被混淆了，但是class-winter本身还是明文的，这就留下了一些安全隐患（即：那些不指定密码的混淆，可能会被反向破解）
- 增强支持：我们可以对class-winter本身进行加密，你可以切换至`enhance-*`分支，在首页下载被混淆的class-winter进行测试，或者clone代码，install后进行测试
- **声明**：因为在`enhance-*`分支里对class-winter本身进行加密时用到了名义上的收费工具allatori（实际上有破解版之类的），所以`enhance-*`分支的代码，本人并未发布至maven官方仓库

## 将已加密的包提供给客户使用

### 方案

- 方案一（适用于encrypted-A依赖于encrypted-B.jar，启动encrypted-A的情况）

>  提示：此方式也适用于不加密A的情况，在A里的class-winter配置你只需要指定一个不存在的includePrefix即可

class-winter加密时，使用`alreadyProtectedLibs`参数，但是要求客户的项目也需要使用class-winter加密（，哪怕客户的项目什么也不需要加密，也要求客户有使用class-winter这个动作）

- 方案二（适用于A依赖于encrypted-B.jar，启动A的情况）

利用`-Dloader.path`或其它方案，将encrypted-B.jar外置，并通过`decryptProjectPathPrefix`或`skipProjectPathPrefix`来定位encrypted-B.jar

### 示例

> 提示：这里以可执行的jar进行的示例，其余的外置方式也是可以的（如：tomcat部署war包解压后，lib包就相当于是外置的）

以`-Dloader.path`实现，将encrypted-B.jar外置到项目包A外

- 假设客户依赖了我们的加密包

![客户项目](./file/1.png)

- 客户使用maven插件，打包时将项目代码和依赖的lib分开

完整pom示例：

```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>2.7.9</version>
 <relativePath/> 
 </parent>
 <groupId>com.example</groupId>
 <artifactId>demo</artifactId>
 <version>0.0.1-SNAPSHOT</version>
 <name>demo</name>
 <description>Demo project for Spring Boot</description>
 <properties>
 <java.version>1.8</java.version>
 </properties>
 <dependencies>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
 </dependency>
 
 <dependency>
 <groupId>org.projectlombok</groupId>
 <artifactId>lombok</artifactId>
 <optional>true</optional>
 </dependency>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-test</artifactId>
 <scope>test</scope>
 </dependency>
 
 <dependency>
 <groupId>com.demo</groupId>
 <artifactId>encrypted-lib-no-pwd</artifactId>
 <scope>system</scope>
 <version>1.0.0</version>
 <systemPath>${pom.basedir}/src/main/resources/lib/encrypted-lib-no-pwd-1.0.0.jar</systemPath>
 </dependency>
 </dependencies>
 
 <build>
 <plugins>
 <plugin>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-maven-plugin</artifactId>
 <configuration>
 
 <mainClass>com.ideaaedi.demo.DemoApplication</mainClass>
 
 <includeSystemScope>true</includeSystemScope>
 <fork>true</fork>
 
 <layout>ZIP</layout>
 <includes>
 <include>
 <groupId>nothing</groupId>
 <artifactId>nothing</artifactId>
 </include>
 </includes>
 </configuration>
 <executions>
 <execution>
 <goals>
 <goal>repackage</goal>
 </goals>
 </execution>
 </executions>
 </plugin>
 
 
 <plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-dependency-plugin</artifactId>
 <version>3.2.0</version>
 <executions>
 <execution>
 <id>copy-dependencies</id>
 <phase>prepare-package</phase>
 <goals>
 <goal>copy-dependencies</goal>
 </goals>
 <configuration>
 <outputDirectory>${project.build.directory}/lib</outputDirectory>
 <overWriteReleases>false</overWriteReleases>
 <overWriteSnapshots>false</overWriteSnapshots>
 <overWriteIfNewer>true</overWriteIfNewer>
 <includeScope>compile</includeScope>
 </configuration>
 </execution>
 </executions>
 </plugin>
 </plugins>
 </build>
 
 </project>
 ```

打出来的包：

![打出来的包](./file/2.png)

- 客户可以这样启动项目

> `java -Dloader.path=./lib/ -javaagent:./{class-winter.jar} -jar {客户项目.jar}`

![使用loader.path引入依赖](./file/3.png)

## 功能扩展案例

> 感谢以下小伙伴们的优秀扩展案例

| 序号 | 扩展功能 | 作者 | 代码&文档 |
| ------ | ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 1 | 机器码支持 | qq号：`85546017` 当前（2023-06-11）状态： &emsp;qq名：`╮(╯_╰)╭` &emsp;是否在class-winter QQ群：是 | |
| ...... | ...... | ...... | ...... |

## QQ群

> 群号：727930548

![qq群](./file/5.png)

tts2/class-winter

简介

发行版 (1)

贡献者

近期动态

tts2/class-winter .gitee-modal { width: 500px !important; }

简介

发行版 (1)

贡献者

近期动态

搜索帮助

tts2/class-winter