Zelix KlassMaster - Documentation
 

The longEncryptionExclude Statement

(Note, generally speaking, any reference below to an long constant should be taken to mean a reference to a byte, char, short or int constant. See Long Constant Encryption tutorial for more detail.)

The ZKM Script longEncryptionExclude statement excludes specified eligible long constants from being encrypted by the Zelix KlassMaster™ obfuscate statement. If an exclusion parameter is a classExcludeParameter then all the eligible long constants within the specified class or classes will be excluded from long encryption. If an exclusion parameter is a fieldExcludeParameter then the initial values of matching long fields will not be Long encrypted.

There is a subtle distinction here. If you exclude at the class level then you are excluding all the long constants of that class from long encryption. If you exclude at the field level then you are excluding only those long constants that initialize the specified fields. So "longEncryptionExclude *.*" is NOT equivalent to "longEncryptionExclude *.* *". The former has a more extensive effect than the latter.

The statement has no impact if the obfuscate statement's encryptLongConstants parameter is set to none. Similarly, a parameter that specifies a non-long field or an long field that is not initialized has no impact. Successive longEncryptionExclude statements have a cumulative effect. Once an exclusion has been set the only way to remove it is with a resetLongEncryptionExclusions statement.

The remainder of this page is organized into the following sections.

Explanation and Examples

longEncryptionExclude statement parameters may be loosely categorized into the following groups

Class exclude parameters

Put informally (with mandatory components in bold), the syntax is:
<classAnnotations> <classModifiers> "<archiveQualifier>"!<packageQualifiers>.<className> <containingClause> <extendsClause> <implementsClause>;

For all the long constants in a class to be excluded, all of the following must be true:
  • Its annotations must match any specified annotations.
  • The class's modifiers (e.g. public final) must match all parameter modifiers. So if the parameters are public abstract !interface then the class must be public, abstract and NOT an interface to be excluded.
  • If the parameter has an archive qualifier then the class must be contained in an archive which matches that archive qualifier.
  • The class's package qualifiers must match any specified package exclude parameter component. If there is no package exclude parameter component then the class must be in the default package.
  • The class's unqualified name must match the parameter's class name specifier.
  • If the parameter has a containing clause then the class must contain members which match the specified class
  • If the parameter has an extends clause then the class must be a subclass of the specified class
  • If the parameter has an implements clause then the class must directly or indirectly implement all of the specified interfaces
longEncryptionExclude 
          pack2.Class1 and //Exclude all long constants in class pack2.Class1 from encryption
          *.* and //Exclude all long constants in all classes from encryption
          //Exclude all long constants in all classes contained in a JAR file with a name matching "MyJar*.jar"
          "MyJar*.jar"!*.* and 
          //Exclude all long constants in all classes annotated which an annotation matching *.MyAnnotation0 
          @*.MyAnnotation0 *.*; 

Field exclude parameters

Put informally (with mandatory components in bold), the syntax is:
<classAnnotations> <classModifiers> "<archiveQualifier>"!<packageQualifiers>.<className> <extendsClause> <implementsClause>
    <fieldAnnotations> <fieldModifiers> <fieldType> <fieldName>;

For the intitialization long constant of a field to be excluded, all of the following must be true:
  • The field's containing class must match any class exclude parameter component (see Class exclude parameters).
  • The field's annotations must match any specified field level annotations.
  • The field's modifiers (e.g. public volatile) must match all parameter field modifiers. So if the parameters are public static !transient then the field must be public, static and NOT transient to be excluded.
  • The field's type (e.g. int[] or java.lang.String) must match the parameter field type if it exists.
  • The field's name must match the parameter field name specifier.
longEncryptionExclude 
          *.* public static * and //Exclude long constants that initialize 
                                  //public static fields in any class from encryption
          pack2.Class1 * and //Exclude long constants that initialize any fields 
                             //in pack2.Class1 from encryption
          //Exclude long constants that initialize any fields annotated with a class matching *.MyAnnotation0.
          *.* @*.MyAnnotation0 *;  

Syntax

"longEncryptionExclude" excludeParameter ("and" excludeParameter)* ";"

annotationSpecifier ::= ("@" [packageExcludeParameter] nameSpecifier) | annotationSpecifierAndList

annotationSpecifierAndList ::= ["!"] "(" annotationSpecifierOrList ("&&" annotationSpecifierOrList)* ")"

annotationSpecifierOrList ::= annotationSpecifier ("||" annotationSpecifier)*

classExcludeParameter ::=
   [annotationSpecifier] [["!"] "public" | "package"]
   [["!"] "abstract"] [["!"] "final"] [["!"] "interface"] [["!"] "synthetic"] [["!"] "enum"] [["!"] "annotation"]
   ["\"" archiveQualifier "\"" "!"] [packageExcludeParameter ["."]] nameSpecifier [containingClause]
   [extendsClause] [implementsClause]

containingClause ::= "containing" "{" "memberAndList" "}"

excludeParameter ::= classExcludeParameter |
fieldExcludeParameter

extendsClause ::= "extends" [annotationSpecifier] wildcardClassName

fieldExcludeParameter ::=
   classExcludeParameter [annotationSpecifier] [["!"] "public" | "protected"| "package"| "private"]
   [["!"] "static"] [["!"] "final"] [["!"] "transient"] [["!"] "volatile"] [["!"] "synthetic"] [["!"] "enum"]
   [type] nameSpecifier

fullyQualifiedClassName ::= name ("." name)*

implementsClause ::= "implements" [annotationSpecifier] wildcardClassName ("," [annotationSpecifier] wildcardClassName)*

memberAndList ::= ["!"] "(" memberOrList ("&&" memberOrList)* ")"

memberOrList ::= memberSpecifier ("||" memberSpecifier)*

memberSpecifier ::= fieldExcludeParameter | methodExcludeParameter

nameAndList ::= ["!"] "(" nameOrList ("&&" nameOrList)* ")"

name ::= (["0"-"9","a"-"z","A"-"Z","$","_"])+
   i.e. a Java identifer (e.g. a package, class, field or method name) with no wildcards allowed

nameAndList ::= ["!"] "(" nameOrList ("&&" nameOrList)* ")"

nameOrList ::= nameSpecifier ("||" nameSpecifier)*

nameSpecifier ::= wildcardName | nameAndList

packageExcludeParameter ::= packageName | packageNameAndList

packageName ::= wildcardName ("." wildcardName)* "."
   NB: the final "." is part of the package name

packageNameAndList ::= ["!"] "(" packageNameOrList ("&&" packageNameOrList)* ")"

packageNameOrList ::= packageExcludeParameter ("||" packageExcludeParameter)*

type ::=
   ("byte" | "short" | "char" | "int" | "long" | "float" | "double"| "boolean" |
   fullyQualifiedClassName) ("[]")*

wildcardClassName ::= wildcardName ("." wildcardName)*

wildcardName ::= (["*","0"-"9","a"-"z","A"-"Z","$","_"])+
   i.e. a Java identifer (e.g. a package, class, field or method name) with the "*" wildcard allowed
Where archiveQualifier is a relative or absolute archive path name with the "*" wildcard allowed. E.g. "/lib/*.jar" or "myJar0.jar"

ZKM Script resetIntegerEncryptionExclusions statement The ZKM Script Language ZKM Script longEncryptionUnexcludeStatement statement
Zelix KlassMaster - Java Obfuscator