# Getting Started

Before getting started, you have to acquire a license. Please check out the pricing

# Dependency

JCloak requires annotations to describe the wanted characteristics. With the release of 2.0, only selected classes are hidden and a modified copy of the jar will be created. This eases the usage of JCloak and reduces file size compared to the 1.x branch. The 1.x branch is not accessible anymore and has been removed from the documentation.

maven {
    url "https://artifacts.micartey.dev/public"
}

...

compileOnly "me.micartey.jcloak:annotations:1.1.1"

<repository>
  <id>artifacts</id>
  <name>micartey</name>
  <url>https://artifacts.micartey.dev/public</url>
</repository>

...

<dependency>
  <groupId>me.micartey.jcloak</groupId>
  <artifactId>annotations</artifactId>
  <version>1.1.1</version>
  <scope>provided</scope>
</dependency>

Alternatively you can download the annotation package and add it localy. Both Maven and Gradle can add local jar files.

annotations-1.1.1.jar

# Annotations

The following panels contain examples and explanations for the annotations that are used to controll the behavior of the class. Make sure to check out all annotations and their effects.

Example

Explanation

@JCloakLoaded
public class TestClass {

    public TestClass() {
        System.out.println("Hello World");
    }
}

Classes annotated with JCloakLoaded will be removed from the jar file and hidden to ensure its safty.

Example

Explanation

@JCloakEntrypoint
public class Main {

    public static void main(String[] args) {
        new TestClass();
    }
}

Tells JCloak that this class is the entrypoint. Normaly the main class. Multiple classes can be annotated with this method, but only one should be loaded. This can be usefull for multi-platform applications.

Versions newer than 5.X support CLI arguments to process jar files that do not contain these annotations. You can archive this by using the following arguments:

entrypoint

includeAll

exclude

# Command line interface

To be able to use JCloak, you need docker/podman and run the following command. Make sure to edit the LICENSE variable before running the command.

After purchase, you will receive an access token to login with docker and be able to pull the image. For more information, read the instructions on docker here

$ docker run -v ./:/opt/jcloak/bin/files -e LICENSE=<license> --rm jcloak/cli:latest

usage: jCloak
 -input <file>                Input file (required)
 -output <file>               Output file (required)
 -address <ip>                Required ip address to execute the output
 -allowAgent                  Allow Java agents at runtime
 -allowUnsafe                 Allow access to the Unsafe class
 -dependencies <deps>         Folder with dependencies
 -entrypoint <classes>        Entrypoints seperated with comma
 -exclude <packages>          Exclude packages seperated with comma
 -expiration <days>           Expiration in days
 -exportKey <file>            Export encryption key to file
 -hideExclusions              Hide exclusions from std out
 -hideKey                     Hide Encryption key from std out
 -hideProgress                Hide processed classes from std out
 -includeAll                  Include all classes except the entrypoint
 -includeKey                  Include Encryption key
 -key <key>                   Encryption key
 -killswitch <url>            URL which returns true when killswitched
 -native                      Fake native implementations
 -noLoader                    Do not bundle the loader into the output jar
 -skipChecksums               Skip checksums and allow modification
 -urlLoader <url>             Load the loader dynamically during runtime
                              from an url

The input file is the jar file you want to encrypt and hide. The output file is the modified jar containing the necessary files and modifications. The other options are not mandatory. By not providing a key, jcloak will generate a one-time-pad encryption key.

# Provide an Encryption Key

To execute the jar file that doesn't include the key, you need to set an environment variable named JCLOAK_KEY which will be retrived at runtime to be able to decrypt the class files. This can be archived by editing the startup script or by trying a workaround such as mentioned here.

$ export JCLOAK_KEY=<yoursecret>

Alternatively you can add the includeKey option to include the encryption key inside the jar file. Keep in mind that this will come at the expense of security as they key is now included "somewhere" inside the jar file.

# Using the URL Loader

The JCloak loader is with roughly 1.1 MiB not small. There are reasons why you want to reduce the file size or hide the jcloak package. Therefore, you can load the loader via an URLClassLoader. The URL has to be provided during build time. You can either provide your own url or use the public one.

-urlLoader https://micartey.github.io/jCloak/static/files/loader-014d880a9b7.jar

Please verify that the sha256sum of the jar file and its name start with the same characters.

# Build with gradle

Gradle thankfully makes it fairly simple to incorporate the cli into your toolchain. Simply register a new task and specify after which task it should run. This is required by newer gradle versions.

tasks.register('jcloak', Exec) {
    mustRunAfter '...'
    workingDir project.rootDir
    commandLine 'bash', '-c', "docker run -v ./:/opt/jcloak/bin/files -e LICENSE=<license> jcloak/cli:latest -input ${buildDir}/libs/${project.name}.jar -output ${project.name}-final.jar -includeKey"
}

tasks.register('jcloak', Exec) {
    mustRunAfter '...'
    workingDir project.rootDir
    commandLine 'cmd', '/c', "docker run -v ./:/opt/jcloak/bin/files -e LICENSE=<license> jcloak/cli:latest -input ${buildDir}/libs/${project.name}.jar -output ${project.name}-final.jar -includeKey"
}

Make sure to edit the LICENSE variable to be able to execute jcloak

After creating a new task, make sure to edit your build command and add the task jcloak. You can run jcloak as the last task on your toolchain right after additional obfuscations.

# Troubleshooting

When running into any problems, consider checking out the JCloak Troubleshooting guide, a dedicated resource designed to assist you in resolving any issues you may encounter while using JCloak. The troubleshooting guide addresses common problems, providing a clear understanding of their causes and practical solutions to get you back on track.

getting started