iOS

Provided Frameworks

In this section, we will learn about the integration of the Master Controller SDK into a sample iOS application.

The MC SDK comes with the following frameworks, which are all required for proper functioning (except "kssidp.xcframework" and KSTrustedWebView.xcframework ):

KSMasterController.xcframework (Debug and Release) Contains all the classes of the Master Controller (MC) API for iOS, facilitating the use of MC functionalities in iOS applications. There is no difference between the debug and release apart from the ability of debugging native code (c / c++) with debug build configuration.

hnb.xcframework (hardening-ios): Provides security mechanisms to protect the native code and secure the application against various threats. Debug: Enables app startup in iOS Simulator and allows debugging with the iOS Debugger. Release: Intended for distribution to end users, without debugger support.

KSTrustedWebView.xcframework A software stack that adds additional security to WebView inside a KOBIL Secured App. It includes features like SSL/TLS certificate pinning for enhanced security.

kssidp.xcframework Built on top of the MasterController SDK, this framework facilitates activation, login, change password, and forgot password flows. It simplifies these processes by allowing applications to maintain their native interfaces while handling these operations without direct communication with the IDP.

Do NOT use the debug build configuration libraries for release/production purposes.

Our libraries are delivered and tested in specific combinations in QA. We strongly recommend using the exact combination of libraries delivered to avoid compatibility issues. Avoid mixing libraries from different release packages to streamline troubleshooting and ensure compatibility with our tested configurations.

Note: KSSIDP is specifically for Shift environments, not for Digitanium/Digitanium+.

Step-by-step Instruction

1. Create a new Xcode project and select "Single View App".

2. The project name chosen for this document is "MCSDKGettingStartedSwift". However, you can choose another name.

3. Select the project file and choose target "MCSDKGettingStartedSwift" and Click on the '+' button in the section Embedded Binaries and Select the 'Add Other...' option in the opening section.

4. Choose MasterController and Harden the XC-framework in the finder. Apple defines XCFrameworks as a distributable binary package created by Xcode that contains variants of a framework or library so that it can be used on multiple platforms (iOS, macOS, tvOS, and watchOS), including Simulator builds. An XCFramework can be either static or dynamic and can include headers. 'We have also provided our MasterController and Hardening framework as an XCFramework.'

5. 'Embedded Binaries' and 'Linked Frameworks and Libraries' sections should look like below. "KSMasterController.xcframework", "hnb.xcframework", kssidp.framework. and "KSTrustedWebview.xcframework" in 'Linked Frameworks and Libraries' are automatically added. There is no need for extra effort to add the frameworks in that section.

6. You can also give support to multiple servers in your application by simply adding the SDK configuration file of that server. You can add this server configuration file like this.

You can switch your server in the currently running application also, for that you have to first delete all users of the existing server and then select a server on which you want to switch.

To activate users on different servers, please navigate to the corresponding server.

Initial Steps

1. Ensure you have all the necessary assets and frameworks ready to proceed with the MasterController SDK:

   • MasterController SDK framework for both debug and release modes.
   • GettingStartedApps and MC configuration files.

2. Follow these steps to set up communication with the MasterController framework:

   • Add the MasterController framework to your project using artifacts.
   • Use the MasterControllerAdaptor class for communicating with the Master Controller. To start actual communication, initialize its components in the AppDelegate.

3. Register your app version in the Security Server.

Further Information

The MasterController and Hardening come in two different variants: one in the debug folder and the other in the release folder. Refer to the table below to understand the differences and choose the appropriate MasterController Hardening for your situation:

Debug	Release
KOBIL App Security is disabled, allowing iOS debugger attachment and using dummy values for KOBIL App Security	KOBIL App Security is enabled, prohibiting iOS debugger attachment
Some MasterController logs are written to the Xcode console	MasterController logs are not written to the Xcode console; only encrypted log files are available
This variant is not recommended for productive usage; a notification is displayed on startup

Simulator Support

Running a release version of the Hardening framework on a simulator is prevented by the security features of our framework. However, developers may want to run components or tests of their app on the simulator in release mode. To simplify this, we provide a "dummy" release version of our framework for the simulator, which is essentially a copy of the debug version. Note that the timing differences between release and debug versions are even more pronounced in this scenario. While the simulator can aid in app development and debugging, it is not a substitute for testing on a real device. Additionally, if the SDK relies on the Secure Enclave, attempting to run it on a simulator will always fail. In such cases, testing and debugging must be conducted on a real device.

Backup of iPhone and iPad

For security purposes, KOBIL App Security's device binding parameter is not stored in iCloud or local computer backups. Consequently, after restoring a backup, the user will lose activation and must reactivate the app. Therefore, the MCSDK does not support the backup/restore process. When a user makes a backup, the MCSDK prevents the iOS system from backing up a database file. Otherwise, restoration would result in an undefined state where the device binding parameter is missing, but the app still believes it is activated. Developers need not take any action, as this process occurs automatically.