KOP4J

KOP4J is a NAGRA-produced code obfuscation tool for Java that supports many of the R8/ProGuard features while adding a number of its own, namely: certificate protection, manifest protection, shelf life protection and string masking.

String masking will increase the size of your app, but can be disabled if the resulting size is unacceptable.

KOP4J also includes the AnNaNaS (Android Nagra Native Secure) library, which protects native (C/C++) code.

Configuring KOP4J

Configuration for KOP4J uses ProGuard rules, which modify its default behaviour by enabling or disabling features and instructing it not to obfuscate or shrink specific classes. The complete set of ProGuard rules can be found at: https://www.guardsquare.com/en/products/proguard/manual/usage.

There are additional rules to enable KOP4J-specific features such as string masking that are explained fully in the documentation provided in your KOP4J distribution.

ProGuard rules files

The KOP4J plugin includes the rules file kop-android-default.txt which contains standard configuration settings; KOP4J should be configured to use this by default (see below).

It may be necessary to define app-specific rules to work around issues caused by limitations in KOP4J's ability to correctly analyse code in certain situations, such as when your code uses reflection or calls native code via the Java Native Interface (JNI). In cases like these, you may need to force KOP4J to keep specific code rather than stripping it out. To define these rules, create your own rules file - for example, named proguard-rules.pro - and place it in the app-level directory.

A basic rules file may look something like this (comments are preceded by # ):

# Keep MyJNIClass
-keep public class com.example.MyJNIClass
  
# Keep all classes in com.example.database_package, but not in its subpackages
-keep public class com.example.database_package.*
  
# Keep all classes in com.example.open_package, and those in its subpackages
-keep public class com.example.open_package.**

SDK embedded rules

In addition to the default rules in kop-android-default.txt and those specified by the developer, the CONNECT Player SDK 5 also includes its own set of rules in a file named proguard.txt contained within the library's AAR file. Its contents must be copied into one of the ProGuard rules files listed in your KOP4J configuration. This is required to obfuscate the SDK.

In future updates to KOP4J, this manual step will not be required and the rules will be applied automatically.

Applying KOP4J to your app

Adding the dependency to the top-level build.gradle

Extract your KOP4J archive (either zip or tar.gz) to a known location. You can then add the path to the list of repositories, enabling you to add the dependency:

buildscript {
    repositories {
        ...

        flatDir {
            dirs '/path/to/kop/installation/directory/bin'
        }
    }
    dependencies {
        ...

        classpath ':kop-gradle:<version>'
    }
    ...
}

Applying the plugin to your app

...
// Apply the plugin, taking care not to place it before the `com.application.android` plugin
apply plugin: 'com.nagra.kop'
...

android {
    ...

    buildTypes {
        release {
            // In contrast to R8, `minifyEnabled` must be set to `false`
            minifyEnabled false

            // Include the KOP4J plugin's default rules, followed by your app-specific rules
            proguardFiles kop.getDefaultKopFile('kop-android-default.txt'), 'proguard-rules.pro'
            ...
        }
    }
}

Enabling AnNaNaS

AnNaNaS is provided as an AAR file. Its location must be provided in the kop configuration in the app-level build.gradle:

kop {
    repositories { flatDir { dirs '/path/to/kop/installation/directory/aar'} }
    dependencies.add('implementation', [name:'annanas-Release', ext:'aar']);

    //The line below is only required if KOP4J is unable to locate the kop-core library, or if a non-standard kop-core library is required
    pathToKopCoreJar = '/path/to/kop/lib/kop-core-<version>.jar'
}

Disabling AnNaNaS

AnNaNaS may be disabled if it is not required for your app. It must also be disabled if your app uses PRM, which uses native libraries that are already protected by KOP - a related, but separate tool to KOP4J - which provides the same rooting, emulation and debugging protections as AnNaNaS. To prevent build failures it is necessary to disable AnNaNaS to prevent it from attempting to apply its own protection mechanisms, clashing with KOP.

It is disabled by adding the following to one of your ProGuard rules files:

-kop-hash-strategy java