net.truelicense.obfuscate

Class ObfuscatedString

java.lang.Object

net.truelicense.obfuscate.ObfuscatedString

public final class ObfuscatedString
extends Object

A thread-safe representation of an obfuscated string.

Motivation

Software developers may wish to apply some licensing scheme to protect their Intellectual Property (IP). When implementing the licensing scheme, it is vital to obfuscate the Java byte code. Otherwise, a reverse engineer can simply replace the licensing code with a stub in order to break the licensing scheme.

Likewise, all constant string expressions which are used to interact with the licensing code need to get obfuscated, too. Otherwise, a reverse engineer can simply search for known strings in the Java byte code in order to identify the obfuscated licensing code or replace its key strings with self-generated key strings.

Usage

This class specifically addresses the need to obfuscate constant string expressions in Java byte code. Note that general Java byte code obfuscation is out of scope - there are other tools required to do this!

To obfuscate a constant string expression you need to pass it to the static method obfuscate(java.lang.String) at design time and replace it with the generated Java source code expression. At runtime, a duplicate of the original constant string expression will get computed by the Java source code expression. If you need to preserve the identity relation of constant string expressions, then you need to add a call to String.intern()()} to the duplicated string.

A tool for Java byte code transformation (e.g. the TrueLicense Maven Plugin) may automate some or all of these steps. However, it needs to call array(java.lang.String) instead of obfuscate(java.lang.String) at build time.

Security Considerations

Note that obfuscation is not equal to encryption: In contrast to the application of the simple and cheap obfuscation scheme in this class, strong encryption would be comparably slow and expensive in terms of resources - no matter what encryption algorithm would actually get used. Moreover, encrypting constant string expressions in Java byte code does not effectively increase the security level when compared to simple obfuscation. This is because an encryption key still needs to be made available to the Java byte code and so could get eavesdropped by tracing JVM calls with the standard JDK tool chain. Thus, the simple obfuscation scheme implemented by this class is preferred over complex encryption. Conversely, if someone is proposing to encrypt constant string expressions then please check if (s)he is trying to sell snake oil.

Author:

Christian Schlichtherle

See Also:

Obfuscate

Constructor Summary

Constructors

Constructor and Description
ObfuscatedString(long[] obfuscated) Constructs an obfuscated string from the given array.

Method Summary

Modifier and Type	Method and Description
static long[]	array(String s) Returns an obfuscated array representation of the given string.
protected void	finalize()
static String	java(long[] obfuscated) Returns a string containing an obfuscated Java source code expression which computes a duplicate from the given array representation of the original string.
static String	literal(String s) Encodes the given string to a valid string literal in Java source code.
static String	obfuscate(String s) Returns a string containing an obfuscated Java source code expression which computes a duplicate of the given string again.
char[]	toCharArray() Reproduces a copy of the original string from the obfuscated array representation provided to the constructor.
String	toString() Reproduces a copy of the original string from the obfuscated array representation provided to the constructor.
String	toStringIntern() Equivalent to toString()() toString()}.String.intern()() intern()}.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ObfuscatedString

public ObfuscatedString(long[] obfuscated)

Constructs an obfuscated string from the given array.

Parameters:

obfuscated - the array representation of the obfuscated string.

Throws:

ArrayIndexOutOfBoundsException - If the provided array does not contain at least one element.

See Also:

toString()

Method Detail

array

public static long[] array(String s)

Returns an obfuscated array representation of the given string. Obfuscation is performed by encoding the given string into UTF8 and then XOR-ing a sequence of pseudo random numbers to it. The result is decoded into an array of long integers as the obfuscated array representation of the given string. The sequence of pseudo random numbers is seeded with a random number in order to provide a non-deterministic result for the obfuscated array representation. Hence, two subsequent calls with an equal string will produce equal results by a chance of only 1/(2⁴⁸ - 1) - zero is not used as a seed.

Parameters:

s - the string to obfuscate. This may not contain null characters.

Returns:

an obfuscated array representation for the given string.

Throws:

IllegalArgumentException - If s contains a null character.

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

java

public static String java(long[] obfuscated)

Returns a string containing an obfuscated Java source code expression which computes a duplicate from the given array representation of the original string.

Parameters:

obfuscated - the obfuscated array representation of the original string.

Returns:

a string containing an obfuscated Java source code expression which computes a duplicate from the given array representation of the original string.

literal

public static String literal(String s)

Encodes the given string to a valid string literal in Java source code.

Parameters:

s - the string to quote and escape.

Returns:

The transformed string.

obfuscate

public static String obfuscate(String s)

Returns a string containing an obfuscated Java source code expression which computes a duplicate of the given string again. This is equivalent to calling java(long[])(long[])}(array(java.lang.String)(String)}(s)).

As an example, calling this method with "Hello world!" as its parameter may produce the result "new net.truelicense.obfuscate.runtime.ObfuscatedString(new long[] { 0x39e61a665e397740l, 0xb681642064a96eael, 0xb8eb509886cc10f9l }).toString()". If this Java source code is compiled and executed, it will reproduce the original string "Hello world!" again.

Parameters:

s - the string to obfuscate. This may not contain null characters.

Returns:

Some obfuscated Java source code to produce the given string again.

Throws:

IllegalArgumentException - If s contains a null character.

toCharArray

public char[] toCharArray()

Reproduces a copy of the original string from the obfuscated array representation provided to the constructor.

Returns:

A copy of the original string in a new char array.

toString

public String toString()

Reproduces a copy of the original string from the obfuscated array representation provided to the constructor.

Overrides:

toString in class Object

Returns:

A copy of the original string.

toStringIntern

public String toStringIntern()

Equivalent to toString()() toString()}.String.intern()() intern()}.

Returns:

A canonical representation of the original string.