Getting Started with Sentinel® LDK for Android (ARM or x86)

Sentinel LDK v.7.8


This document describes how to set up and get started with Sentinel LDK components required for protecting and licensing software for applications on an Android (ARM or x86) platform.

(Note that the Sentinel LDK Vendor Suite components must be installed on a Windows-based computer. For information on installing the Sentinel Vendor Suite, refer to the Sentinel LDK Installation Guide.)

The following topics are discussed:

Overview

Sentinel LDK for Android enables you to apply LDK protection to your applications on an Android platform. Sentinel LDK Envelope protects the Android application and encrypts the entire DEX file for the application. This provides an additional layer of security for the protected application. The protected Android application contains all required distribution files, including an Embedded License Manager. No Run-time Environment is required.

License updates for the Android application are performed using Sentinel EMS or Sentinel License Generation API on a Windows platform.

(Note: Sentinel EMS Customer Portal is not supported for Android platforms.)

Android applications can be protected using either SL UserMode licenses or Sentinel HL (Driverless configuration) keys:

Return to top of document

Operating Systems and Hardware Supported

Refer to the Sentinel LDK Release Notes.

Return to top of document

Required Software

The following software must be installed on the same machine as Sentinel LDK Envelope:

Return to top of document

How to Get Started

  1. On a Windows computer, install Sentinel EMS and Sentinel LDK Vendor Suite. Sentinel LDK Envelope is (optionally) used to protect your application. These components of Sentinel LDK provide the backend and licensing infrastructure for the ordering and production processes for distributing your protected applications. Introduce your Sentinel Master key on the Windows computer. For more information, see the Sentinel LDK Installation Guide.

  2. Files for Android can be found on the machine where Sentinel LDK Vendor Suite is installed, under the following directory:
    %ProgramFiles(x86)%\Gemalto Sentinel\Sentinel LDK\Additional Platforms\Android\

    The following directories are included:
  3. To develop basic familiarity with Sentinel LDK, Gemalto recommends that you perform the exercises provided in the Sentinel LDK Software Protection and Licensing Tutorial.

Return to top of document

How to Protect an Android Application

Sentinel LDK offers you two methods for protecting your application on a Windows platform: integrated or automatic. This depends on the type of protection being used for Android.

You can also choose to combine these two methods to provide a greater level of protection.

Return to top of document

How to Determine If an Android Device Supports USB Keys

To use an attached USB device, the user requires:

To determine if your device has all the required hardware and software, you can use an app such as USB Host Diagnostics (USBHostDiagnostics-v1.3.apk). Do the following:

  1. Install USB Host Diagnostics.
  2. Ensure that nothing is plugged into the USB port on your device.
  3. Start the app.
  4. Tap the Start Diagnostics link.
  5. Follow the displayed instructions. When prompted to do so, attach a device (such as a USB flash drive).

Return to top of document

Overview of the HaspDemo Sample

The HaspDemo sample is contained in the Samples directory as described earlier in this document.

The Hasp_Demo sample program has two tabs that demonstrate the use of Sentinel LDK licensing functions and the license update process:

How to build the HaspDemo sample:

If you are using a Sentinel HL key:

  1. Connect the Sentinel HL (Driverless configuration) key to the Android device using an OTG cable.

  2. Open the LDKDemo app on the Android device. The following message is displayed: Allow application LDK Demo to use this device?

  3. Click Yes.

  4. Click the License Consumption Demo button to run the sample.

If you are using a Sentinel SL key:

  1. Click the License Update Demo button to go to the license update screen.

  2. Click the New SL Key button to activate your initial SL license. The RUS screen is displayed.

  3. You can select the Product Key option or the License File option as the license update method:

  4. When you receive a message that the license activation succeeded, click OK to return to the license update screen.

  5. Click your Android device's Back button to return to the demo screen.

  6. Click the License Consumption Demo button to run the sample.

Return to top of document

How to Integrate Sentinel Licensing API in Your Application

This section is relevant if you want to use the Integrated Protection method for your application.

  1. Build the JNI layer as follows:

    1. Ensure that NDK is installed on your machine (for example: C:\android-ndk-r9).
    2. Modify Java/jni/Android.mk to link your vendor-specific library (libhasp_android_<vendorId>.a).
    3. Switch to the Java directory. Run C:\android-ndk-r9\ndk-build from a command prompt.
    4. The JNI library is generated in Java/libs/armeabi-v7a/libHASPJava.so and in Java/libs/x86/libHASPJava.so .

  2. Add the following files to your project:

  3. Refer to Java/src/com/HaspDemo/HaspDemo.java to see how to call the Licensing API.

  4. Add the following line to load the LDK JNI library:
  5. System.loadLibrary("HASPJava");

  6. If you are using Sentinel HL keys to protect and license your application:

  7. Add the following lines to AndroidManifest.xml for your project:

  8. <uses-sdk android:minSdkVersion="14" />

  9. If you are using Sentinel HL keys to protect and license your application, add the following line to AndroidManifest.xml for your project:

    <uses-feature android:name="android.hardware.usb.host" />

Return to top of document

Activation or Update of a Licensing Key by the Protected Application

This section is relevant if you want to use the Integrated Protection method or if you want to customize the RUS utility.

Because of Android sandboxing, license update and license consumption logic must be part of the protected application. It is not possible to update or activate a license using an external RUS utility or by using the Sentinel EMS Customer Portal in a Web browser. Therefore, the activation/update mechanism must be integrated into the protected application.

Note: If you are using automatic protection, Sentinel LDK Envelope packs ldkrus.jar with the protected APK at protection time. The activation/update mechanism is added automatically. You do not need to integrate RUS code into your application.

If you want to customize the look and feel of RUS, you can update the files in the folder Java/src/com/ldk_rus and export it to the JAR file.

If you want to build activation/update mechanism in your application, you can accomplish this by using the Licensing API and the RUS code. If you plan to use the RUS code, include the following files in the application:

To build librus.so (for ARM and for x86), use your vendor code in Java/jni/rus.c. Update Java/jni/Android.mk to link your vendor-specific API: libhasp_android_<vendorId>.a

Note: Before starting RUS (activity com.ldk_rus.ldk_rus), set parameter newSL to the appropriate value (described below) and pass the parameter to the activity. Refer to Java/src/com/HaspDemo/RUSDemo.java to see how to set newSL and start RUS activity.

If a Sentinel SL license does not exist and you want to install a new SL license, set newSL to true. RUS will retrieve the fingerprint of the system.
If a Sentinel SL license already exists, or you are using Sentinel HL, set newSL to false. RUS will retrieve the current state of the Sentinel protection key.

If the application is protected with Sentinel LDK Envelope, a routine is added to the application that checks for a valid license. If a valid license is not found, the routine calls RUS to handle the licensing process. To implement this, ldkrus.jar is used. Envelope packs ldkrus.jar with the protected APK at protection time. If you want to customize the look and feel of RUS, you can update the files in the folder Java/src/com/ldk_rus and export it to the JAR file:

export.png

Export the files in src/com/ldk_rus only.

Replace the file ldkrus.jar in %ProgramFiles(x86)%\Gemalto Sentinel\Sentinel LDK\VendorTools\VendorSuite, and restart Envelope to protect your application. RUS will be customized.

You can also use the RUS utility if the application is not protected with Sentinel LDK Envelope. (Note that the language and program flow for the user interface in RUS can be customized.)

Regardless of whether or not you protect your application with Sentinel LDK Envelope: It is not necessary to modify RUS code as long as the RUS class name that Envelope looks for (when it cannot find a valid license) is specific (com.ldk_rus.ldk_rus). The Android sample provided demonstrates the correct class name. This name must not be changed.

Return to top of document

Limitations

SL UserMode licenses have the following limitations:

Sentinel HL Driverless keys have the following limitations:

Return to top of document

Known Issues

Refer to the Sentinel LDK Release Notes.

Return to top of document

© Gemalto 2018. All rights reserved. Gemalto, the Gemalto logo, are trademarks and service marks of Gemalto and are registered in certain countries.

DocID 193 Revision 1802-3