Integrate the Secure Storage SDK

Prev Next

Android

AAR artifact-based integration

To integrate the Secure Storage SDK into your Android project via aar file

  • Copy SecureStorageSDK.aar from the OneSpan Mobile Security Suite package to the aars folder.

To use the Secure Storage SDK library, you also need to add the following external libraries to your maven/gradle project:

dependencies {
            implementation 'org.jetbrains.kotlin:kotlin-stdlib:2.2.21'
            implementation 'androidx.appcompat:appcompat:1.8.0'
            implementation 'androidx.biometric:biometric:1.1.0'
            implementation 'org.bouncycastle:bcprov-jdk18on:1.85.2'
            }

Maven-based integration

The SDK artifact is also delivered as a local Maven repository with transitive dependencies, and the package includes a documentation jar file to view the technical documentation in Android Studio (to be used in conjunction with the Maven repository).

To integrate the SDK via maven repository:

  1. Copy the maven folder from the published artifacts to the root folder of your application.

  2. Define the dependency in your build.gradle file: implementation 'com.onespan:sdk_secure_storage_android:+'.

  3. Comment out any existing definitions, for example: implementation(name: 'SecureStorageSDK', ext: 'aar'), implementation(name: 'UtilitiesSDK', ext: 'jar').

Handling of asynchronous behavior

For handling asynchronous behavior, the recommended pattern is to use the  SecureStorageWrapper.kt wrapper and run storage calls off the main thread, using lifecycleScope from the user interface. The SecureStorageWrapper.kt wraps the callback-based SecureStorage.createSecureStorage in a suspend function. It runs storage operations off the main thread on Dispatchers.IO using lifecycleScope from the user interface, guards initialisation with a mutex, and handles unreadable or corrupted storage by deleting it.

The sample included in the product package showcases this pattern.

iOS

To integrate the Secure Storage SDK into your iOS project

  • Link MSSSecureStorage.xcframework from the OneSpan Mobile Security Suite package to the linked framework and libraries of your Xcode project.

Your project must be linked with the -ObjC flag. This should be set in Other Linker Flags in the target's build settings. In a pbxproj project file, the raw key is OTHER_LDFLAGS.

To use this framework with pure Objective-C projects, you need to add a Swift file and create the Bringing Header file.

Deprecation of the iteration counter-based data protection

The iteration counter is only required to migrate a secure storage.

To migrate your application to use the new methods to create or write a new secure storage

  1. The first call must be done with the up-to-date initialization method without any iteration counter.

  2. When the migrationNeeded error is thrown,

    1. call the deprecated initialization method with iteration counter

    2. call the write method. This will create files with new security options.

      If the legacy storage cannot be opened anymore, you need to remove it by calling the delete method.

You are now ready to use the Secure Storage SDK. For more information on, see Available methods in the Secure Storage SDK.

API reference documentation and sample applications

To learn more about the public APIs and their functions, exceptions, and error codes, refer to the technical documentation that is included in the product package for each SDK and each platform. In the product package, you can also find the sample applications provided for each platform to see examples of how the SDKs can be used.

These sample apps are intended only to demonstrate basic scenarios and SDK usage. They are not designed to be copied directly into production projects!