- Created by user-5c3b0, last modified by Seema on May 14, 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 4 Next »
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
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.gradleallprojects { 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.
In your module (app-level) Gradle file (
app build.gradle
), add the following rules:
Item Mandatory/
OptionalDescription 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 sourceandroid { ……. 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
Add configuration file: Copy the
cipher.json
file toapp/src/main/assets
. The JSON file contains config data necessary to setup your SDK along with the following four keys:tenantId
storeAppId
apiKey
sdkName
Initialize the SDK: In the
onCreate()
method of your Application class, create ain.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.
Authenticate the SDK: Once the user logs in, generate the
jwtToken
and callcipherService.authenticate(<jwtToken>)
.Important
- We recommend updating
jwtToken
token at every app launch. This ensures hassle-free creation ofauth
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.
- We recommend updating
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.
Error Code | Description |
---|---|
Server-side | |
| Internal server error. Try again. |
ER001 | Invalid arguments provided in the authentication request. Ensure that a valid SDK configuration file, cipher.json , is provided. |
ER004 | Error in generating auth token. |
ER005 | Error in creating resource. Please check and update the jwt token if required. |
ER007 | Authentication of JWT failed. Ensure that
|
Client-side | |
SDKER001 | JWT not set. Set it and try again. |
SDKER002 | Inconsistency with the SDK stored data. Log out and set up the SDK again. |
SDKER003 | Failure in execution of a request. Try again. |
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.
- No labels