Overview of the Secure Storage SDK

Prev Next

The Secure Storage SDK provides a generic API to securely store data on a mobile device and mask how information is stored on the platform. It provides storage facilities to read, write, or delete storage and to add, get, or remove data.The SDK can create one or more independent storages, identified by their names. Data read from or written to the storage is handled through unique identifiers.

Supported platforms

The Secure Storage SDK can be used on a variety of devices and supports the following platforms:

Android devices:

  • Minimum Android 7 (API level 24)

  • Target Android 16 (API level 36)

iOS devices:

  • iOS 16 or later

  • Swift 6 or later

  • Xcode 16 or later

SDK package contents

The Secure Storage SDK package includes the following:

  • SecureStorageSDK.aar for Android

  • MSSSecureStorage.xcframework for iOS

  • Maven repository with transitive dependencies for Android

  • Documentation jar file to view the technical documentation in Android Studio (to be used in conjunction with Maven repository)

For instructions on how to integrate the Secure Storage SDK into your project, see Integrate the Secure Storage SDK.

Upgrading the SDK

This is an advance notice, you can still upgrade directly to the current version.

Beginning with the upcoming version 6.x, migration support for storages created with SDK versions 4.29.0 and earlier are not supported. Apps using Secure Storage SDK version 4.29.0 or earlier must first upgrade to 5.x before upgrading to version 6.x.

Supported upgrade paths

  • From 4.x: upgrade to the latest 5.x version first, then upgrade to version 6.x

  • From 5.x: direct upgrade to version 6.x

Upgrading directly from version 4.25.0 or earlier is not supported and will cause the storage migration to fail, making existing secure storage(s) unreadable.

Upgrading on Android

Note that upgrading the dependency alone is not enough. The on-disk storage format is only rewritten the first time the app writes to secure storage after upgrading, so simply bumping the SDK version and launching the app does not migrate existing data.

To migrate correctly

  1. Upgrade the app's Secure Storage SDK dependency to 5.x (i.e., a version prior to that which removes legacy migration support).

  2. Launch the app and initialize the SDK as usual.

  3. Perform at least one write operation (e.g. store, or a biometric-protected write) so the storage file is rewritten in the current format.

It is only safe to upgrade the SDK to the latest version after this write-operation has completed. Apps that upgrade the SDK version but never invoke a write operation will remain on the old storage format and will fail to migrate once legacy support is removed.

Upgrading on iOS

Before upgrading to version 6.x, if you already use version 5.x and you get the migrationNeeded error, you must call getInstance(fileName:fingerprint:iterationNumber:) to migrate your storage.