DOCSEARCHbyAlgolia
Submit Docs

ClassFinal Documentation

repository·master·Indexed 19 days ago

https://github.com/roseboy/classfinal

A Java security tool designed to encrypt JAR and WAR files to prevent source code leakage and bytecode decompilation. It clears method bodies while preserving metadata for compatibility with frameworks like Spring and Swagger. The tool includes a core encryption module, a FatJar CLI for manual encryption and runtime decryption via javaagent, and a Maven plugin for build automation. It also supports machine binding to restrict execution to specific hardware.

Tokens
2.2K
Snippets
7
Records
9
Agent score
16%

What's inside ClassFinal

  1. Overview of ClassFinal

    master

    ClassFinal is a security tool for encrypting Java .class files. It supports encrypting entire .jar or .war packages without requiring any modifications to the original project source code. It is compatible with the Spring Framework and prevents source code leakage or bytecode decompilation by clearing method bodies while preserving annotations and parameters (ensuring compatibility with frameworks like Swagger that scan annotations).

    Core Modules:

    • classfinal-core: The core encryption logic.
    • classfinal-fatjar: A standalone executable JAR used for encryption and as a javaagent for decryption.
    • classfinal-maven-plugin: A Maven plugin to automate encryption during the build process.

  2. How machine binding works

    master

    Machine binding restricts an encrypted project so that it can only run on a specific machine.

    1. Generate Machine Code: On the target machine where the project must run, execute:
      java -jar classfinal-fatjar.jar -C
    2. Encrypt with Code: During the encryption process, use the -code parameter with the generated machine code.

    You can combine machine binding with a password for enhanced security.

    java -jar classfinal-fatjar.jar -C

  3. Encrypt JAR/WAR files using the FatJar CLI

    master

    You can encrypt your project using the classfinal-fatjar.jar. This process generates a new file named [original-name]-encrypted.jar (or .war).

    Command Syntax:

    java -jar classfinal-fatjar.jar -file <path> -packages <pkg1,pkg2> -libjars <jar1,jar2> -cfgfiles <file1,file2> -exclude <pkg1> -classpath <dir1> -pwd <password> -code <code> -Y

    CLI Arguments Reference:

    ArgumentDescription
    -fileFull path to the JAR/WAR file to encrypt.
    -packagesPackage names to encrypt (comma-separated, can be empty).
    -libjarsSpecific JAR files within the lib directory to encrypt (comma-separated).
    -cfgfilesConfiguration files to encrypt (e.g., .yml or .properties in classes/).
    -excludeClass names or packages to exclude from encryption (comma-separated).
    -classpathExternal dependency directories (e.g., /tomcat/lib).
    -pwdEncryption password. Use # for passwordless mode.
    -codeMachine code for machine binding (prevents running on other machines).
    -YNon-interactive mode (skips confirmation prompts).

    Note: The encrypted file cannot be run directly; it requires a javaagent to decrypt in memory at runtime.

    java -jar classfinal-fatjar.jar -file yourpaoject.jar -libjars a.jar,b.jar -packages com.yourpackage,com.yourpackage2 -exclude com.yourpackage.Main -pwd 123456 -Y

  4. Automate encryption with the Maven Plugin

    master

    Add the classfinal-maven-plugin to your pom.xml to automatically encrypt your project during the package phase.

    Configuration Example:

    <plugin>
    <groupId>net.roseboy</groupId>
    <artifactId>classfinal-maven-plugin</artifactId>
    <version>1.2.1</version>
    <configuration>
        <password>000000</password>
        <packages>com.yourpackage,com.yourpackage2</packages>
        <cfgfiles>application.yml</cfgfiles>
        <excludes>org.spring</excludes>
        <libjars>a.jar,b.jar</libjars>
    </configuration>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>classFinal</goal>
            </goals>
        </execution>
    </executions>
</plugin>

    Running mvn package will generate yourpaoject-encrypted.jar in the target directory. The plugin arguments match the CLI arguments used by the FatJar.

  5. Run an encrypted JAR using javaagent

    master

    Encrypted JARs must be started with the -javaagent parameter. The decryption logic is embedded within the encrypted JAR itself, so no external decryption JAR is required.

    Option 1: Pass password via command line argument

    java -javaagent:yourpaoject-encrypted.jar='-pwd 0000000' -jar yourpaoject-encrypted.jar

    Option 2: Interactive password entry (Recommended) Run the command without the -pwd argument, and enter the password in the console when prompted:

    java -javaagent:yourpaoject-encrypted.jar -jar yourpaoject-encrypted.jar

    Password Retrieval Order:

    1. Command line argument (-pwd)
    2. Environment variable (specified via -pwdname)
    3. Password file (classfinal.txt or [project]-encrypted.classfinal.txt in the current directory)
    4. Console input
    5. GUI input

    Security Best Practice: To ensure runtime security, add the following JVM parameter: -XX:+DisableAttachMechanism.

    java -javaagent:yourpaoject-encrypted.jar='-pwd 0000000' -jar yourpaoject-encrypted.jar

  6. Run an encrypted WAR in Tomcat

    master

    To run an encrypted WAR file in Tomcat, add the javaagent configuration to the Tomcat startup scripts.

    Linux (catalina.sh):

    CATALINA_OPTS="$CATALINA_OPTS -javaagent:classfinal-fatjar.jar='-pwd 0000000'";
export CATALINA_OPTS;

    Windows (catalina.bat):

    set JAVA_OPTS="-javaagent:classfinal-fatjar.jar='-pwd 000000'"

    Note: If you used passwordless encryption (-pwd #), add the -nopwd parameter to the agent configuration to skip the password prompt during startup.

    # Linux example
CATALINA_OPTS="$CATALINA_OPTS -javaagent:classfinal-fatjar.jar='-pwd 0000000'";
export CATALINA_OPTS;

  7. Reference: ClassFinal CLI Options

    master

    The following options are available for the Main entrypoint:

    • packages: Encrypted package names (comma-separated, can be empty).
    • pwd: Encryption password.
    • code: Machine code (for hardware binding).
    • exclude: Excluded class names (comma-separated, can be empty).
    • file: Path to the JAR/WAR file to encrypt.
    • libjars: JAR files under the target's lib folder (comma-separated, can be empty).
    • classpath: Dependency JAR directories (comma-separated, can be empty).
    • cfgfiles: Configuration files that need encryption (comma-separated, can be empty).
    • Y: Skip confirmation.
    • debug: Debug mode.
    • C: Generate machine code.

  8. Encrypt JAR/WAR files via CLI

    master

    ClassFinal provides a command-line interface to encrypt standard JARs, Spring Boot JARs, and Spring Web WAR files. You can run the tool by passing arguments directly or by running it without arguments to enter an interactive mode where you will be prompted for configuration details.

    CLI Arguments

    OptionRequiredDescription
    -fileYesPath to the JAR/WAR file to be encrypted
    -pwdYesEncryption password
    -packagesNoPackage names to encrypt (comma-separated)
    -libjarsNoJAR files within the lib directory of the target (comma-separated)
    -excludeNoClass names to exclude from encryption (comma-separated)
    -classpathNoDirectory containing dependency JARs (comma-separated)
    -cfgfilesNoConfiguration files to encrypt (comma-separated)
    -codeNoMachine code for hardware binding
    -YNoSkip confirmation prompt
    -debugNoEnable debug mode
    -CNoGenerate machine code (replaces encryption task)

    Usage Example

    To encrypt a Spring Boot JAR with specific packages and a password:

    java -jar classfinal.jar -file springboot.jar -libjars a.jar,b.jar -packages net.roseboy,yiyon.com -exclude org.spring -pwd 995800 -Y
    java -jar classfinal.jar -file springboot.jar -libjars a.jar,b.jar -packages net.roseboy,yiyon.com -exclude org.spring -pwd 995800 -Y

  9. Generate machine code for hardware binding

    master

    Use the -C flag to generate a unique machine code for the current server. This code can be used with the -code option during encryption to bind the encrypted JAR to a specific machine, preventing it from running on unauthorized hardware.

    The generated code is printed to the console and saved to a file named classfinal-code.txt in the root directory of the application.

    Command

    java -jar classfinal.jar -C
    java -jar classfinal.jar -C