Cipher SDK is a Two Factor Authentication (2FA) solution designed to provide a secured way to verify transactions. This is achieved by enabling customers to verify their identity. Cipher SDK ensures a safe implementation of 2FA with minimum friction and generation of OTP is not required. Follow the steps mentioned below:

Before you begin

• Ensure you have  cipher.json  file at hand before proceeding. The file contains configuration data necessary to set up the SDK. To obtain the file for your application, contact  Zeta .
• Fusion uses JSON Web Token (JWT) to authenticate the SDK. The token must be fetched and passed on to cipher SDK during runtime. 
• The token generation logic is shared over the email as it contains sensitive information. It is later made accessible through Apollo Dashboard.
• Add Firebase project to your app and register your Cloud Messaging server key in our dashboard.
• Minimum Android SDK version required: 19 
• Minimum Java Runtime Environment (JRE) version required: 8
  

Install Cipher SDK

1. To install SDK to your app, add the following Apollo maven repository to your project-level Gradle file (build.gradle ). This downloads the Maven artifacts.

   Project build.gradle

   allprojects {
       repositories {
           ....
   maven{url 'https://apollo-maven.corp.zeta.in/nexus/content/repositories/releases/' }
   maven {url 'https://apollo-maven.corp.zeta.in/nexus/content/repositories/snapshots/'}
           ....       
       }
   }

   Important

   We recommend to maintain the order of including the repositories as mentioned in the above project build gradle.

2. In your module (app-level) Gradle file ( app build.gradle ),  add the following rules:
   

   Item	Mandatory/ Optional	Description
   multiDexEnabled	Optional	Use this for debugging the build if you overshoot the 64K methods ceiling.
   compileOptions	Mandatory	Add support for Java 8 language features.
   packagingOptions	Optional	Add this only if you face packaging error.
   dependencies	Mandatory	Include Cipher SDK dependencies for the latest version.

   app build.gradle  Expand source

   android {
   …….
       defualtConfig {
   	// Use for debug build if needed
   multiDexEnabled true
       }
       ........
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_1_8
           targetCompatibility JavaVersion.VERSION_1_8
       }
   	kotlin_options = {
          jvmTarget = "1.8"
       }
       // Include this if you face packing errors ..
       packagingOptions {
           exclude 'META-INF/library_release.kotlin_module'
           exclude 'META-INF/DEPENDENCIES'
       }
       ........
   }
   dependencies {
     ………...
     implementation 'in.zeta.apollo:cipher:<latest-version>'
     ………….
   }
   // Please include this if you are not using j2v8 engine in your code. APK would inflate if we don’t do this
   configurations {
       all*.exclude group: 'in.apollo.android', module: 'templating_engine'
       all*.exclude group: 'com.eclipsesource.j2v8', module: 'j2v8'
   }

Configure Cipher SDK

1. Add configuration file:  Copy the cipher.json  file to app/src/main/assets . The JSON file contains config data necessary to setup your SDK along with the following four keys: 

   1. tenantId 

   2. storeAppId

   3. apiKey

   4. sdkName

2. Initialize the SDK:  In the onCreate()  method of your Application class, create a in.android.zeta.acs.CipherService instance.

   Creating CipherService instance

   …..
   final CipherService cipherService = new CipherServiceBuilder(this)
   .setSecuritySupportMethods(methodsSupport) // SupportedSecurityStores
   .setTenantSecuredStoreAccess(securedStoreAccess) // AppSecuredStoreAccess. To be provided when using the tenant secured store
   .setBankLogo(R.drawable.ok_bank_logo)
   .build();
   ….

   Important

   If you are using Timber logging utility, initialize it after initialization of cipher SDK.

3. Authenticate the SDK: Once the user logs in, generate the jwtToken  and call cipherService.authenticate(<jwtToken>).

   Important

   • We recommend updating jwtToken token at every app launch. This ensures hassle-free creation of auth resource by the SDK whenever needed.
   • jwtToken must be generated on the server-side as it involves signing the data with a private key. The private key must never be compromised.

Set up the secured store

For setting the secured store, you must provide an implementation for SupportedSecurityStores interface.

public interface SupportedSecurityStores {
   boolean supportDeviceLock();
   boolean useOwnSecureStore();
}

Using the above interface, you can tell the Cipher SDK if it has to use a secured store implemented by your app. If not, then you should specify if you want to support device lock or not. If useOwnSecureStore()is set to return true, then you should give an implementation for AppSecuredStoreAccess. This interface enables the Cipher SDK to securely store/retrieve sensitive data into your secure store. In case, you have not provided access to your secured store and the device lock is also disabled, then Zeta representative sets up the SDK PIN for securing sensitive data.

public interface AppSecuredStoreAccess {
   interface SetaDataInSecureStoreListener {
       void done(final boolean success, final Exception exp);
   }
   void setDataInSecureStore(@NonNull final String key, final byte[] data, @NonNull final SetaDataInSecureStoreListener listener);
   interface GetDataInSecureStore {
       void done(final byte[] data, final Exception exp);
   }
   void getDataFromSecureStore(@NonNull final String key, @NonNull final GetDataInSecureStore listener);
   boolean contains(@NonNull final String key);
}

Cipher Service public methods

The various public methods used in Cipher service are described below: 

isTenantAuthTokenRequired() - Returns boolean

If this method returns true, you must call  authenticate(tenantToken: String). This indicates that the SDK is in the initial state which is achieved on clean install. 

isSwipeToPaySetupDone() - Returns boolean

If this method returns true, your Swipe to Pay setup is completed. If Swipe to Pay does not work, the SDK might be in an error state. See  getSDKErrorState() for more details.

isSecureStoreSetupRequired() - Returns boolean

If this method returns true, the SDK requires a secure store setup. Secure store setup is done by invoking  setupSecureStore(). 

setupSecuredStore() - Returns void

This method triggers setup of secure storage. Ensure this method is called only if isSecuredStoreSetupRequired() returns true, else this leads the SDK into an unusable state. Post this step, SDK will be able to setup the Swipe to Pay and Super Pin.

authenticate(tenantToken: String) - Returns void

This method authenticates a tenant user by providing a tenantAuthToken to the SDK.

getSDKErrorState() - Returns a string error code

This method returns the latest error related to SDK authentication. See  Exceptions and error codes for more details.

getSuperPin(GetSuperPinListener listener)

This method returns the Super Pin on providing authentication to the secured store/device lock. The Super Pin is required to authorize the payment.

setParentActivityForAuth(Activity activity)

This method sets the parent activity where we want to set up the secured storage.

setCipherStateUpdateListener(listener: CipherStateUpdateListener)

This method is used to subscribe to SDK state updates.

handleNotification(data: Map<String, String>) - Returns void

This method communicates the notification data payload to the Cipher SDK. If you receive a notification from Zeta's senderID, you should call this method with the data payload of the notification and SDK will take care of the notification.

onPushTokenUpdated() - Returns void

This method should be called when you receive an update from the firebase push token. Refer Monitor token generation for more details.

logout() - Returns void

This method resets the SDK whenever you need to perform a logout for the user in the app.

Using the SDK

After setting up the SDK in your app, you can decide the actions to be taken in the following manner:

if(cipherService.isTenantAuthTokenRequired()) {
	// The SDK is in uninitialized state. You should provide ‘tenantAccessToken’ by triggering cipherService.authenticate(<token>)
} else if(cipherService.isSecureStoreSetupRequired()) {
	// You are now ready to setup the secure store as instructed by the AppSecuredStoreAccess
} else if(cipherService.isSwipeToPaySetupDone()){
	// You are ready to receive swipe to pay or you can use getSuperPin() to access the super pin.
}

You can subscribe to listen to the updates of the SDK states by providing an interface implementation to setCipherStateUpdateListener(listener: CipherStateUpdateListener).

Set up notification

Fusion uses the Firebase-based cloud messaging approach. It is recommended to setup a Firebase project for your app. See Setting up a Firebase cloud messaging client app for more information.

Exceptions and error codes

This section explains various exceptions thrown by Cipher SDK and how to handle them. Exceptions provide system error codes along with Throwable message, that helps to recognize and troubleshoot the issue.

The sample error response below shows server-side error code and message returned in case of invalid JWT:

in.zeta.apollo.sdkauth.SdkAuthException: The jwt token set seems invalid. Please check the parameters and signature to create the token
SdkAuthException.erroCode: ER007

SDK authentication

Exceptions related to SDK authentication are received as SdkAuthException. They are categorized as server-side and client-side.

The following table lists the error codes, descriptions and possible solutions. If the issue persists, contact Zeta.

Soft Logout

Ensure cipherService.logout() method is called when performing a soft logout in the app. Else, the SDK might not run properly in the next login.