Skip to main content
Version: v4.x

Upgrade Notes

This document describes the changes in the current version (v4.x) compared to the previous version (v3.x), and what you need to be aware of when upgrading.

The documentation for the older version is still available: switch to v3.x using the version dropdown in the top-right corner of the page.

Overview of changes​

ChangeImpact
Removed support for polymorphic dllProjects using polymorphic dll must remove the related settings and build steps
Disabled code watermark (WaterMark)Enabling this pass has no effect
obfuz4hybridclr requires HybridCLR v9.0.0+Projects on an older HybridCLR must upgrade, or keep using obfuz4hybridclr v3.x

Removed support for polymorphic dll​

v4.0.0 removed the polymorphic dll feature. The related code, settings, and code generation templates have been deleted from both obfuz and obfuz4hybridclr.

Specifically:

  • ObfuzSettings no longer contains PolymorphicDllSettings, so the former Enable, Code Generation Secret Key, and Disable Load Standard Dll options no longer exist.
  • obfuz4hybridclr no longer generates the polymorphic dll related C++ code (PolymorphicRawImage, etc.).

How to upgrade​

  • If your project did not enable polymorphic dll, nothing needs to be done.
  • If your project did enable polymorphic dll, the related settings simply stop taking effect after the upgrade. Review your build scripts and remove any calls to the polymorphic dll APIs. Also clean up the polymorphic dll C++ files generated by the old version under the HybridCLRData directory, otherwise the leftover files may break the il2cpp build.
  • If you still depend on the polymorphic dll feature, keep using obfuz v3.x.

The polymorphic dll documentation is available in the v3.x docs: Polymorphic Dll.

Disabled code watermark​

The code watermark pass is disabled. Enabling WaterMark in ObfuscationPasses has no effect.

The reason is that inserting instructions at certain special positions causes il2cpp.exe to fail, for example inserting instructions between ldtoken and a RuntimeHelpers.InitializeArray call.

The settings in WatermarkSettings are still present, but they have no effect.

How to upgrade​

No configuration change is required.

obfuz4hybridclr requires HybridCLR v9.0.0+​

warning

Starting from v4.0.0, obfuz4hybridclr only supports HybridCLR v9.0.0 and above.

HybridCLR v9.0.0 changed the build pipeline APIs. obfuz4hybridclr v4.0.0 has been adapted to the new APIs and is therefore no longer compatible with older versions of HybridCLR.

How to upgrade​

Pick one of the following:

  • Upgrade HybridCLR to v9.0.0 or above, then use obfuz4hybridclr v4.x.
  • Stay on the older HybridCLR version and keep using obfuz4hybridclr v3.x.

Note that the major versions of obfuz and obfuz4hybridclr must match, i.e. obfuz4hybridclr v4.x must be used together with obfuz v4.x.

For details, see Work with HybridCLR.

Note: eval stack obfuscation was disabled long ago​

This is not a v4.x change, but it was never mentioned in the v3.x documentation, so it is clarified here.

The eval stack obfuscation pass has been disabled since v3.0.0. Enabling EvalStackObfus in ObfuscationPasses has no effect.

The reason is that this pass has a poor cost-benefit ratio: it significantly increases the size of the obfuscated assemblies while providing only a limited increase in reverse engineering difficulty. If it cannot be optimized in the future, the feature may be removed entirely.

The settings in EvalStackObfusSettings are still present, but they have no effect. No configuration change is required. If you want stronger obfuscation, consider using expression obfuscation and control flow obfuscation instead.