OreoObfuscator

What is OreoObfuscator?

OreoObfuscator protects your compiled Java .jar files so that competitors or anyone who gets hold of your file cannot read, copy, or steal your code.

It works at the bytecode level — it modifies the actual .class files inside your JAR without touching your source code. The result is a new JAR that runs exactly the same as the original but looks like total gibberish when decompiled.

Requirements

Installation and the protected distribution

Customers receive one self-contained, already-obfuscated executable JAR. They do not need the OreoObfuscator source tree, Gradle project, clean fat JAR, or private mapping. In this guide the downloaded file is called OreoObfuscator-protected.jar. If your download has a versioned name, either keep that name and substitute it in every command, or rename it to the shorter name.

java -version

java -jar "C:\Tools\OreoObfuscator\OreoObfuscator-protected.jar" --version
java -jar "C:\Tools\OreoObfuscator\OreoObfuscator-protected.jar" help

java -jar "C:\Tools\OreoObfuscator\OreoObfuscator-protected.jar" license --activate "OREO-your-key"

Choose how to use OreoObfuscator

java -jar OreoObfuscator-protected.jar protect input.jar output-protected.jar -c oreo.yml --seed 123456789

java -jar OreoObfuscator-protected.jar

Option 1 - Using the CLI

The CLI is recommended for production because every input is explicit and the command can be reviewed, repeated, logged, and used in CI. The protected executable accepts exactly the same public commands as an unobfuscated build. Supplying a subcommand prevents the GUI from opening.

CLI command structure

java [JVM options] -jar OreoObfuscator-protected.jar COMMAND [command options]

# Correct
java -Xmx2g -jar "C:\Tools\OreoObfuscator\OreoObfuscator-protected.jar" protect "C:\Apps\My App.jar" "C:\Apps\My App-protected.jar" -c "C:\Apps\oreo.yml"

# Display root and command-specific help
java -jar OreoObfuscator-protected.jar help
java -jar OreoObfuscator-protected.jar protect --help

CLI - Complete protection workflow

Step 1: create a reviewed YAML configuration

Production users should pass -c explicitly. This prevents an unrelated oreo.yml in the current directory from changing a build. The YAML controls protection strength, keep rules, shaded-library prefixes, metadata, and mapping output.

java -jar OreoObfuscator-protected.jar analyze "input\MyPlugin.jar" --verbose

Step 2: protect the JAR

The portable one-line form works in PowerShell, Command Prompt, Bash, and most CI runners:

java -Xmx2g -jar OreoObfuscator-protected.jar protect "input\MyPlugin.jar" "output\MyPlugin-protected.jar" -c "oreo.yml" --seed 123456789

PowerShell multiline form:

java -Xmx2g -jar .\OreoObfuscator-protected.jar protect `
  ".\input\MyPlugin.jar" `
  ".\output\MyPlugin-protected.jar" `
  -c ".\oreo.yml" `
  --seed 123456789

Bash/Linux/macOS multiline form:

java -Xmx2g -jar ./OreoObfuscator-protected.jar protect \
  ./input/MyPlugin.jar \
  ./output/MyPlugin-protected.jar \
  -c ./oreo.yml \
  --seed 123456789

Step 3: understand success and failure

A successful run prints the selected mode and license, the absolute input path, each transformer, bytecode-verification results, the absolute output path, and a final summary. Treat any failed transformer as a failed release even if an output file exists.

In PowerShell, inspect the process result immediately with $LASTEXITCODE. In Bash use echo $?. CI must fail the job when the exit code is non-zero.

Step 4: verify the generated JAR independently

# Structural ASM verification
java -jar OreoObfuscator-protected.jar verify "output\MyPlugin-protected.jar"

# JVM verification and real application startup
java -Xverify:all -jar "output\MyPlugin-protected.jar"

verify checks class structure; java -Xverify:all asks the JVM to verify classes as they load. Neither replaces application tests. Test reflection, resources, services, serialization, plugins, database access, network initialization, and GUI startup that matter to your program.

Step 5: retain release evidence

• Archive the exact protected JAR and its SHA-256 checksum.
• Keep the original JAR, YAML, seed, engine version, Java version, and dependency set.
• Store mapping.json privately for stack-trace decoding; never bundle it into the public artifact.
• Keep the full CLI log and test results with the release.

CI example using an environment license

# PowerShell
$env:OREO_LICENSE = $env:CI_OREO_LICENSE
java -jar .\OreoObfuscator-protected.jar protect .\build\app.jar .\dist\app-protected.jar -c .\oreo.yml --seed 123456789
if ($LASTEXITCODE -ne 0) { throw "OreoObfuscator failed with exit code $LASTEXITCODE" }
java -jar .\OreoObfuscator-protected.jar verify .\dist\app-protected.jar
if ($LASTEXITCODE -ne 0) { throw "Protected JAR verification failed" }

CLI - Analyze before protecting

Analysis is read-only and helps confirm that the selected input is the intended JAR.

java -jar OreoObfuscator-protected.jar analyze "input\MyPlugin.jar"
java -jar OreoObfuscator-protected.jar analyze "input\MyPlugin.jar" --verbose

CLI - Verify an output

The command returns zero when all inspected classes are clean, one for verification issues, and two for fatal loading/I/O errors.

java -jar OreoObfuscator-protected.jar verify "output\MyPlugin-protected.jar"

CLI - Inspect a private mapping

The mapping command requires the JSON path as its first argument. With no additional option it prints statistics. Use --lookup with the original internal or binary name recorded in the file.

# Statistics
java -jar OreoObfuscator-protected.jar mapping "output\mapping.json" --stats

# Look up an original class/member name
java -jar OreoObfuscator-protected.jar mapping "output\mapping.json" --lookup "com.example.MyPlugin"
java -jar OreoObfuscator-protected.jar mapping "output\mapping.json" --lookup "com/example/MyPlugin.onEnable ()V"

CLI - Manage the license

# Activate and save a customer key
java -jar OreoObfuscator-protected.jar license --activate "OREO-your-key"

# Show customer, tier, and expiry
java -jar OreoObfuscator-protected.jar license --info

# Remove the locally saved key
java -jar OreoObfuscator-protected.jar license --deactivate

On Windows the saved key is under %USERPROFILE%\.oreo\license.key. On Linux/macOS it is under ~/.oreo/license.key. Deactivation removes the local copy; it does not modify a protected application JAR.

Option 2 - Using the GUI

The GUI is the easiest workflow for occasional manual builds. It uses the same transformation pipeline and license as the CLI. The protected distribution opens the GUI when it receives no command-line arguments.

1. Start the correct executable

On Windows, opening a terminal is more reliable than double-clicking because it proves which Java installation and which OreoObfuscator JAR are being used:

cd /d C:\Tools\OreoObfuscator
java -jar OreoObfuscator-protected.jar

In PowerShell, use Set-Location C:\Tools\OreoObfuscator instead of cd /d. Double-clicking is also supported when Windows associates .jar files with Java 21+.

2. Activate or confirm the license

Open the License tab. Paste the supplied OREO-... key and click Activate, or confirm that the expected customer, tier, and expiry are displayed. The license is saved under %USERPROFILE%\.oreo\license.key and is shared with the CLI.

3. Select the target application JAR

Return to Protect. Drag the application/plugin JAR onto the drop zone or click the zone and browse to it. The green selection panel shows the complete path. Read that path before continuing.

4. Choose a separate output JAR

The GUI proposes a name ending in -protected.jar. Use Browse to choose another location when needed. Confirm that input and output are different files and that the output directory is writable. When changing input files, recheck the output field because a previously typed output path may remain visible.

5. Choose how settings are supplied

For production, click Browse beside Config File and select your reviewed oreo.yml. Keep rules and library prefixes are available only through YAML and are often required for reflection, service loading, shaded dependencies, Spring, and Minecraft plugins.

6. Configure protection

If no YAML file is selected, open Settings and configure renaming, strings, numbers, control flow, virtualization, and Minecraft support. Stronger settings increase transformation time, output size, startup cost, and compatibility risk. Test incrementally before selecting an extreme preset.

7. Keep verification enabled

The control is labelled Skip bytecode verification. For a release build, leave it unchecked so OreoObfuscator verifies generated classes before reporting success. Temporarily skipping verification is a diagnostic measure, not proof that an output is safe to ship.

8. Protect and read the complete log

Click PROTECT JAR. Wait until the button becomes available again. A created file alone does not prove success: check the console for the exact input/output paths, transformer failures, verification issues, and the final success summary. Copy the complete log when requesting support.

9. Test the generated JAR outside the GUI

Close or minimize OreoObfuscator and launch the protected application in a separate terminal:

java -Xverify:all -jar "C:\path\to\MyPlugin-protected.jar"

For a server plugin, place a copy in a clean test server and inspect the full startup log. For a GUI application, verify startup and every important workflow. For libraries, run the consuming project's automated tests. An expected headless-display exception is different from a bytecode, linkage, or class-initialization failure.

GUI tabs

GUI field reference

GUI — Settings Tab

Six sections. Each can be independently enabled or disabled. Changes take effect on the next Protect run. These settings are used only when no Config File is selected in the Protect tab.

See the Config File Reference below for a full explanation of each option — the Settings tab exposes the same controls.

GUI — License Tab

Shows a card with your name, tier, and expiry date. Available actions:

• Activate — paste a OREO-... key and click Activate
• Deactivate — removes the saved key from your machine

The key is saved to %USERPROFILE%\.oreo\license.key and loads automatically every time you open OreoObfuscator.

Config File — Overview

A .yml file that stores all your obfuscation settings. Save it once, reuse it across every build.

• CLI: pass with -c yourfile.yml
• GUI: click Browse in the Config File row on the Protect tab

If you do not specify a config file, OreoObfuscator looks for oreo.yml in the current working directory. If that doesn't exist either, it uses built-in defaults (everything enabled at a moderate level with ASCII name mode).

Config — mode

A global preset that sets sensible defaults for all transformers at once. Individual sections below always override the preset.

mode: STANDARD   # LITE | STANDARD | AGGRESSIVE | EXTREME

Config — rename

Controls identifier renaming — the most impactful layer. Without renaming, decompiled code is immediately readable.

rename:
  enabled:        true     # master switch
  packages:       true     # rename package names
  classes:        true     # rename class names
  methods:        true     # rename method names
  fields:         true     # rename field names
  localVariables: true     # strip local variable debug names
  parameters:     true     # strip parameter debug names
  nameMode:       CHINESE  # ASCII | UNICODE | CHINESE

nameMode

Config — unicode

Controls which Unicode character set is used when nameMode is UNICODE or CHINESE.

unicode:
  enabled: true
  charset: CJK   # CJK | HANGUL | HIRAGANA | KATAKANA | MIXED

Config — strings

Encrypts every String constant in your code. Without this, a decompiler shows passwords, API keys, URLs, and error messages in plain text. With this enabled they are stored encrypted and decrypted at runtime when first used.

strings:
  enabled:      true
  encryption:   MIXED   # XOR | AES | MIXED
  perClassKeys: true    # unique AES key per class
  lazyDecrypt:  true    # decrypt on first access, not at startup

Config — numbers

Replaces integer, long, float, and double constants with equivalent arithmetic expressions. Instead of 42 a decompiler sees something like ((0x2F ^ 0x15) + 4). Near-zero runtime cost.

numbers:
  enabled: true

Config — controlFlow PRO+

Restructures the logic flow inside every method. The code does exactly the same thing at runtime, but decompilers (Fernflower, CFR, Procyon, jadx) either crash or produce complete gibberish full of goto statements.

controlFlow:
  enabled:            true
  level:              HEAVY    # LIGHT | MEDIUM | HEAVY | EXTREME
  opaquePredicates:   true     # always-true/false conditions
  fakeBranches:       true     # unreachable code blocks
  deadBranches:       true     # dead code injection
  switchFlattening:   false    # convert if/else chains into switch dispatch
  stateMachines:      false    # convert loops into state machine dispatchers
  exceptionBasedFlow: false    # use try/catch for unconditional jumps

Level comparison

Config — minecraft

Enable this for every Minecraft plugin. OreoObfuscator reads your plugin.yml (or paper-plugin.yml) to find your main class, commands, and listeners, and automatically keeps their names so Bukkit / Paper / Velocity can still discover them at runtime.

minecraft:
  enabled:                true
  platform:               PAPER   # BUKKIT | SPIGOT | PAPER | VELOCITY
  keepEventListeners:     true    # keep Listener classes + @EventHandler methods
  keepCommands:           true    # keep command executor classes
  keepPermissions:        true    # keep permission nodes
  keepSerializableTypes:  true    # keep ConfigurationSerializable classes

Config — virtualization ELITE

The strongest available protection. Selected methods are compiled into a private custom bytecode format and executed at runtime by an embedded interpreter. No Java decompiler can reconstruct these methods — they simply do not exist as JVM bytecode.

virtualization:
  enabled: false
  methods: []   # leave empty to auto-select, or list specific methods

# Specific method selector format: "internalClassName.methodName"
# Example:
virtualization:
  enabled: true
  methods:
    - "com/example/plugin/LicenseChecker.validate"
    - "com/example/plugin/AntiCheat.processPacket"

Config — keepRules

A list of class names that must never be renamed. Use this for any class that is referenced by name at runtime — through reflection, configuration files, service loaders, MANIFEST.MF Main-Class, or any framework that looks up classes by string name.

Use dot-separated class names (Java style). Both formats are accepted.

keepRules:
  - com.example.plugin.MyPlugin         # main plugin class
  - com.example.plugin.api.PublicAPI     # API class used by other plugins
  - com.example.plugin.gui.MyGUI         # referenced in logback.xml by string name
  - com.example.plugin.Commands          # referenced from config file

Config — libraryPrefixes

A list of internal class name prefixes (slash-separated) that identify third-party libraries bundled inside your JAR (shaded / fat JAR dependencies). Classes matching these prefixes are loaded for hierarchy analysis but are never renamed or transformed — they pass through to the output unchanged.

Without this, OreoObfuscator treats shaded libraries as your own code and tries to obfuscate them. This causes two problems: the output JAR is much larger (library code gets string/number-expanded), and large library classes with thousands of static fields can hit the JVM's 64 KB method size limit.

libraryPrefixes:
  - org/objectweb/asm        # ASM bytecode library
  - org/yaml/snakeyaml       # SnakeYAML
  - org/slf4j                 # SLF4J logging API
  - ch/qos/logback            # Logback
  - com/google/gson           # Gson
  - com/google/protobuf       # Protobuf
  - info/picocli              # PicoCLI
  - dev/yourname/libs         # your shaded dependencies (any prefix works)
  - org/sqlite                # SQLite JDBC

Config — Output Options

Fine-grained control over what debug metadata is preserved or stripped.

mappingOutput:   "mapping.json"  # where to write the name mapping file (relative to output JAR)
keepLineNumbers: false           # keep line number tables (useful for stack trace readability)
keepSourceFile:  false           # keep SourceFile attributes (shows original .java filename)
keepLocalVars:   false           # keep local variable debug tables
keepParamNames:  false           # keep method parameter name attributes

Config — Full Example

A complete oreo.yml showing every available key:

# ─────────────────────────────────────────────────────────────────────
#  oreo.yml — complete example
#  Pass to CLI with:  -c oreo.yml
#  Load in GUI via:   Config File → Browse → select this file
# ─────────────────────────────────────────────────────────────────────

# Global preset (individual sections below override this)
mode: STANDARD   # LITE | STANDARD | AGGRESSIVE | EXTREME

# ── Identifier renaming ───────────────────────────────────────────────
rename:
  enabled:        true
  packages:       true
  classes:        true
  methods:        true
  fields:         true
  localVariables: true
  parameters:     true
  nameMode:       CHINESE   # ASCII | UNICODE | CHINESE

# ── Unicode character set ─────────────────────────────────────────────
unicode:
  enabled: true
  charset: CJK   # CJK | HANGUL | HIRAGANA | KATAKANA | MIXED

# ── String encryption ─────────────────────────────────────────────────
strings:
  enabled:      true
  encryption:   MIXED   # XOR | AES | MIXED
  perClassKeys: true
  lazyDecrypt:  true

# ── Number obfuscation ────────────────────────────────────────────────
numbers:
  enabled: true

# ── Control-flow obfuscation (PRO+ only) ─────────────────────────────
controlFlow:
  enabled:            true
  level:              HEAVY    # LIGHT | MEDIUM | HEAVY | EXTREME
  opaquePredicates:   true
  fakeBranches:       true
  deadBranches:       true
  switchFlattening:   false
  stateMachines:      false
  exceptionBasedFlow: false   # test your plugin before enabling

# ── Minecraft plugin mode ─────────────────────────────────────────────
minecraft:
  enabled:               true
  platform:              PAPER   # BUKKIT | SPIGOT | PAPER | VELOCITY
  keepEventListeners:    true
  keepCommands:          true
  keepPermissions:       true
  keepSerializableTypes: true

# ── Bytecode virtualisation (ELITE only) ─────────────────────────────
virtualization:
  enabled: false
  methods: []   # empty = auto-select; or list "ClassName.methodName" entries

# ── Classes that must never be renamed ───────────────────────────────
# Use dot-separated Java class names.
keepRules:
  - com.example.plugin.MyPlugin
  - com.example.plugin.api.PublicAPI

# ── Shaded library prefixes (slash-separated internal names) ─────────
# These classes pass through unchanged — never renamed or transformed.
libraryPrefixes:
  - org/objectweb/asm
  - org/yaml/snakeyaml
  - com/google/gson
  - dev/yourname/libs

# ── Output options ────────────────────────────────────────────────────
mappingOutput:   "mapping.json"
keepLineNumbers: false
keepSourceFile:  false
keepLocalVars:   false
keepParamNames:  false

License Tiers

OreoObfuscator uses an offline RSA-2048 license system. No internet connection required — the key is verified locally using a public key baked into the binary. No one can fake or crack a license key.

Activating a License Key

Via the GUI

"Java Exception Has Occurred" when double-clicking

Cause: Windows is opening the JAR with Java 8. OreoObfuscator requires Java 21+.

Fix:

1. Double-click fix_jar_association.reg included with your download.
2. Click Yes to both Windows prompts.
3. Double-click the JAR again.

Or always launch from a terminal:

java -jar "C:\path\to\OreoObfuscator-protected.jar"

Plugin crashes with "is not an enum class"

[ERROR] SomeGibberishName is not an enum class

Cause: An old build of OreoObfuscator was renaming enum values() methods. Java's internals call values() by that exact name via reflection.

Fix: This is fixed in v1.0.0. Re-obfuscate with the current version.

Minecraft plugin does not load after obfuscation

Cannot find main class

Symptom: Server says "Cannot find main class 'com.example.MyPlugin'"
Fix: Enable Minecraft Mode in Settings (or in your config file: minecraft.enabled: true).

Commands don't respond

Fix: minecraft.keepCommands: true

Events / listeners not firing

Fix: minecraft.keepEventListeners: true

Custom YAML types broken

Fix: minecraft.keepSerializableTypes: true

Obfuscation skips some classes with "method too large" warning

Symptom: Console shows [WARN] ControlFlowObfuscation: skipping 'some/Library' — method already too large

Cause: Your JAR contains a shaded library (e.g. MySQL JDBC, SQLite, Protobuf) whose <clinit> initialises thousands of static fields. After string/number expansion the method exceeds the JVM's hard 64 KB code-attribute limit.

Fix: Add the library's package prefix to libraryPrefixes in your config so it passes through untouched:

libraryPrefixes:
  - com/google/protobuf
  - dev/yourname/libs/mysql
  - org/sqlite

OreoObfuscator gracefully handles the case where these prefixes are not set — affected classes are written with their original (non-renamed) bytes and a warning is logged — but adding them to libraryPrefixes is the correct permanent solution.

Bytecode verification errors

A verification error means the generated artifact has not passed the configured safety gate. Do not distribute it merely because a file was written or because one startup path appears to work.

Diagnosis order:

1. Keep the original input and full log. Find the first failing class and root exception.
2. Rerun with the same YAML and seed to confirm reproducibility.
3. Lower control flow from EXTREME to HEAVY or disable the transformer named in the failure to isolate the interaction.
4. Add precise keep rules or library prefixes when the failing code relies on reflection, services, generated metadata, or shaded dependencies.
5. Run both oreo verify and java -Xverify:all after every configuration change.

Do not obfuscate the distributed engine again

Customers already receive OreoObfuscator-protected.jar. Use it as the executable engine; do not select it as the target input and do not run the protected engine through itself again. Doing so produces a nested transformation that is unsupported for customer use and makes support evidence ambiguous.

If the GUI log says the input is OreoObfuscator-protected.jar, cancel the run and select the application or plugin JAR you intended to protect. The engine executable belongs after java -jar; the target belongs after the protect command:

java -jar OreoObfuscator-protected.jar protect MyApplication.jar MyApplication-protected.jar -c oreo.yml