Cipher SDK is a Two Factor Authentication (2FA) solution designed to provide a secure way of verifying transactions. This is achieved by enabling customers to verify their identity. Cipher SDK ensures a safe implementation of 2FA with minimum friction without the need of OTP generation . 

In this article, SDK integration is documented in both Swift and Objective C languages.

Before you begin

Take care of the following prerequisites before you begin with SDK setup:

• Fusion uses tenantAuthToken to authenticate the SDK. To know how to create tenantAuthToken, see SDK Authentication.
• Minimum iOS version required: 9
• Install the code editor XCode.

Getting Started with iOS Cipher SDK

Follow the steps below to integrate SDK:

1. Download the Framework which contains the structure and required libraries for your Project. 
2. Now install the SDK in your app.
3. Prepare the SDK setup.
4. Add the implementation for Secured Store setup.
5. Configure the API operations of Cipher service.
6. Now the SDK setup is ready to begin with verifying the SDK. 
7. Finally, call iOS Cipher SDK API to clear the session data.

Step 1: Download the Framework

In Fusion, the SDKs are built on top of a Framework  which is a combined set of libraries to help you easily create a production-ready app, by providing a unified platform from where you can manage your app and observe the analytics of the app. The XC Framework packaging is used to package different variants of the Framework to support any platform such as iOS, macOS and others. 

To add the Framework into your project, extract the below zip folder containing an XCFramework for Cipher SDK.

Cipher_XCFramework.zip

Step 2: Install the SDK

The iOS Card SDK is compatible with apps supporting iOS 9 and above. To install the SDK, follow these steps:

1. Drag & drop the XCFramework manually into your project's target. 
   

2. Click Embed & sign under the XCFramework in your project's target.
   

3. Set Allow Non-modular Includes in Framework Modules to "YES" under Target > Build Settings.

4. Set Enable Bitcode to "NO" under Target > Build Settings.

Step 3: Set up the SDK

Follow the steps below to set up the SDK: 

1. Add the Configuration file:
   You must add cipher.plist (properties list file) to your project as it contains all the configurations necessary for activating the SDK. You will receive the cipher.plist file through email. If you haven't received the file, contact Zeta. 
2. Configure properties:
   To enable authentication using face recognition (Face ID), add a value to the NSfaceIdUsageDescription (Privacy - Face ID Usage Description) with a message in the info.plist file. However, this step is not needed if the app is providing its own secure store access.

3. Initialize the SDK: 
   The Cipher build is initialized with tenant secure store, if a new secure store is not required by the tenant. 
   

   Swift

   Objective C

   Adding instance

   let cipher: ApolloCipher = ApolloCipherBuilder()
   .setSecureStore(tenantSecureStore) // AppSecuredStoreAccess. To be provided when using the tenant secured store
   .setViewContext(viewController)   // An instance of UIViewController to show modals. Not required if using tenant secured store
    .build()
   

   Adding instance

   ApolloCipherBuilder *builder = [ApolloCipherBuilder new];
   [builder setSecureStore:appSecureStoreAccess]; // AppSecuredStoreAccess. To be provided when using the tenant secured store
     [builder setViewContext:viewController]; // An instance of UIViewController to show modals. Not required if using tenant secured store
       ApolloCipher *cipher = [builder build];

Step 4: Set up the Secured Store

For setting up the Secured Store, you must provide an implementation for AppSecuredStoreAccess protocol. This protocol enables the Cipher SDK to securely store/retrieve sensitive data into your secure store. The protocol is responsible for four different functionalities as mentioned below:

• dataforKey:completion: to fetch data from the store for a particular key.
  
• setDataforKey:completion: to set data in the store for a particular key.
  
• resetAllData: to reset all the data in store.
  
• containsKey: to check if data for a key exists.

If you haven't provided access to your Secured Store and the device lock is also disabled, contact Zeta for assistance. 

func data(forKey key: String, completion: ((Error?, Data?) -> Void)? = nil)    
func setData(_ data: Data?, forKey key: String, completion: ((Error?) -> Void)? = nil)
func resetAllData() 
func containsKey(_ key: String) -> Bool

- (void)dataForKey:(NSString *_Nonnull)key
        completion:(nullable void (^)(NSError * _Nullable error, NSData * _Nullable data))completion;
 
- (void)setData:(NSData *_Nullable)data forKey:(NSString *_Nonnull)key completion:(nullable void (^)(NSError * _Nullable error))completion;
 
- (void)resetAllData;
 
- (BOOL)containsKey:(NSString *_Nonnull) key;

Step 5: Configure the SDK

You can configure the SDK by providing the implementation for the following APIs based on your requirement:

• Authenticate the SDK
• Set up Secured Store
• Generate Super PIN
• Manage Listener

Authenticate the SDK

An authentication token is required to authenticate the SDK. This is an initial state of the SDK which is achieved on clean install.

1. Check the state of Cipher SDK
   

   If a call to isTenantAuthTokenRequired() returns true, you should provide tenantAccessToken by triggering authenticate(tenantToken:String!).

   Swift

   Objective C

   isTenantAuthTokenRequired() -> bool

   - (BOOL) isTenantAuthTokenRequired

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

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

   Swift

   Objective C

   authenticate(tenantToken:String!) -> void

   - (void) authenticateWithToken:(NSString *) tenantToken

Set up Secured Store

If a call to isSecureStoreSetUpRequired() returns true, you are ready to set up the Secured Store by triggering the setUpSecuredStore().

1. Check the state of Cipher SDK
   

   If this method returns true, the SDK requires a Secured Store setup.

   Swift

   Objective C

   isSecureStoreSetUpRequired()-> bool

   - (BOOL) isSecureStoreSetUpRequired

2. Call setUpSecuredStore API
   

   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 Super PIN.

   Swift

   Objective C

   setUpSecuredStore() -> void

   - (void) setUpSecuredStore

if(cipher.isTenantAuthTokenRequired()) {
             // The SDK is in uninitialized state. You should provide ‘tenantAccessToken’ by triggering 'cipher.authenticate(with:)' API
 } else if (cipher.isSecureStoreSetUpRequired()) {
            // You are ready to setup the Secure Store by triggering 'setUpSecuredStore()' API
 } else if (cipher.canGenerateSuperPin()) {
            // You are ready to trigger 'cipher.generateSuperPin(completion:)' API
} else {
            // The SDK is in a corrupt state. You can trigger logout() API to reset the SDK
}

if([_cipher isTenantAuthTokenRequired]) {
        // The SDK is in uninitialized state. You should provide ‘tenantAccessToken’ by triggering [_cipher authenticateWithToken:] API
} else if ([_cipher isSecureStoreSetUpRequired]) {
        // You are now ready to setup the secure store by triggering [_cipher setUpSecuredStore] API
} else if ([_cipher canGenerateSuperPin]) {
        // You are ready to trigger [_cipher generateSuperPinWithCompletion:] API
} else {
        // The SDK is in a corrupt state. You can trigger [_cipher logout] API to reset the SDK 
}

Step 7: Logout

When a user logs out from the app, ensure that you clear all the session data. A default call to Logout method is important for the SDK to work properly in next login session.

A simple logout is available by using: 

self.cipherManager?.logout()

[self.cipherManager logout]

Exceptions and Error Codes

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

All the exceptions thrown will have the following fields in addition to the message:

1. code: Error code related to the response.
2. traceId: Trace ID which can be provided to Zeta support for identifying the root cause.
3. errorType: Type of error. 

There are two kinds of exception that Cipher SDK can throw:

• SdkAuthException
• CipherException

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