Installing Protector OATH SDK

Protector OATH SDK must be installed as part of your development platform.

The first step is to unzip the contents of the Protector OATH SDK release onto the host platform. The steps required to build an application based on Protector OATH SDK are listed in their target platforms.

To test an application based on Protector OATH SDK, various servers are required depending on the feature under the test (for example, an authentication server to verify an OTP).

Each platform provides a debug and a release version of Protector OATH SDK for your application:

  • A debug version which allows you to debug your codes and use of more TLS configurations to ease app development.
  • A release version where the security configuration is enforced by TLS configuration, debugging detection, hooking detection, and so on.

Protector OATH SDK supports the following platforms:

  • Android
  • iOS
Note

The application must not go live with the debug version of the library. The debug version is only for development purposes that may contain debug symbols and introduce certain security issues if used in production. The application must go live using a release version of the library and a properly signed CA Certificate for the server.

Integration guide

Android integration

In the debug/, and release/ folders, different types of libraries are provided.

To integrate Protector OATH SDK, modify your build.gradle file with the following configuration:

dependencies {
	debugImplementation fileTree(dir: "${your-ezio-root-dir}/android/debug", include: ["protector-oath.aar"])
	releaseImplementation fileTree(dir: "${your-ezio-root-dir}/android/release", include: ["protector-oath.aar"])
}

The AAR file contains the following permission:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.USE_BIOMETRIC" />
    <uses-permission android:name="android.permission.USE_FINGERPRINT" />
    <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />

If you are integrating the FastTrack API, add the following configuration:

dependencies {
  debugImplementation files("${your-ezio-root-dir}/android/fasttrack/debug/libidpmobilefasttrack.jar")
  releaseImplementation files("${your-ezio-root-dir}/android/fasttrack/release/libidpmobilefasttrack.jar")
}
Note

For other configurations such as the recommended obfuscation rules, refer to Android Platform specific.

Migrating from JAR to AAR package

Before Protector OATH SDK V6.0, it was released as a JAR package together with other artifacts. Since Protector OATH SDK V6.0, it is released as an AAR package for the final delivery artifact for simpler application integration. So if you are migrating from a version earlier than V6.0, these are the changes to note:

Updating the AndroidManifest.xml file

Since all the required permissions have been registered in the AAR’s AndroidManifest.xml file, the application can remove the existing permissions in its manifest file. Refer to previous section for the permission list.

Updating the application’s build.gradle file

Prior to Protector OATH SDK V6.0, the application had to link to the libidpmobile.jar, the shared library libidp-shared.so, and libmedl.so (only on 4.9.0 or earlier) manually, it is not required anymore in the current Protector OATH SDK. You can remove these files and update the configurations in your project’s build.gradle file:

dependencies {
	debugImplementation files("${your-ezio-root-dir}/android/debug/libidpmobile.jar")
	releaseImplementation files("${your-ezio-root-dir}/android/release/libidpmobile.jar")
}
android {
    sourceSets {
        debug {
            jniLibs.srcDirs += ["${your-ezio-root-dir}/android/debug"]
        }
        release {
            jniLibs.srcDirs += ["${your-ezio-root-dir}/android/release"]
       }
    }
}

Proguard rules configuration

Same as the permissions in AndroidManifest.xml, the ProGuard configuration rules has been embedded in the AAR file since Protector OATH SDK V6.0, so the application can remove the earlier configuration:

  • Earlier configuration
    buildTypes {
        debug {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), "${your-ezio-root-dir}/proguard-project.pro", "proguard.txt"
        }

        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), "${your-ezio-root-dir}/proguard-project.pro", "proguard.txt"
        }
    }
  • New configuration
    buildTypes {
        debug {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), "proguard.txt"
        }

        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), "proguard.txt"
        }
    }
Note

Only remove the Protector OATH SDK’s configuration, but keep the remaining configurations (if any).

Examples

Protector OATH SDK provides the following examples to illustrate the usage of the SDK. Refer to the platform’s README.txt for details on building and deploying the project, and the additional information.

Core API example:

Android:

  • android/examples/eziomobilesdk_dskpp_example
  • android/examples/eziomobilesdk_emvqr_example
  • android/examples/eziomobilesdk_oathdcv_example
  • android/examples/eziomobilesdk_example

iOS:

  • ios/examples/eziomobilesdk_dskpp_example
  • ios/examples/eziomobilesdk_dskpp_swift_example
  • ios/examples/eziomobilesdk_emvqr_example
  • ios/examples/eziomobilesdk_oathdcv_example
  • ios/examples/eziomobilesdk_example

FastTrack API example:

Android:

  • android/fasttrack/examples/fasttrack_example

iOS:

  • ios/fasttrack/examples/fasttrack_example

Tools

EPS-TokenBuilder

Protector OATH SDK provides the Token Builder tool (tools/eps-tokenbuilder) for application development. The Token Builder tool enables the application developer to provision their device without a live EPS server. It generates two types of files:

  • A file having contents that the Protector OATH SDK requires.
  • A file having contents that the verification server needs. For further details, refer to the documentation within the tool.

SecureLog-Destop tool

From Protector OATH SDK V6.0, a tool provided to help decrypt the secured log file (tools/securelog-desktop). For further information, refer to DesktopTool.

aar-tool

From Protector OATH SDK V6.0, an aar-tool is packaged in the tools folder to help exclude the sharing of libsecurelog.jar in the AAR file.

As this is a gradle script, you have to perform these steps to use it:

  • Use terminal/console, go to the aar-tool folder
  • Run this command:
$ ./gradlew process

For further information of the tool, check the Readme.md file.