Deprecations and API removal notices
SecureStorageSDK class deprecated (Android)
The SecureStorageSDK class has been deprecated and will be removed in a future release of the SDK. It has been replaced with the SecureStorage class, and SecureStorageSDK.init() is now initialized with SecureStorage.createSecureStorage(…).
Advance notice: removal of legacy storage migration support
Android
In the next version of the SDK we will remove migration support for secure storages created with SDK versions 4.29.0 and earlier. Apps using Secure Storage SDK version 4.29.0 or earlier must first upgrade to version 5.x, i.e., a version that supports this migration, before upgrading to the next or a later version.
Upgrading directly from version 4.29.0 or earlier is not supported and will cause the storage migration to fail, making existing secure storage(s) unreadable.
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
Upgrade the app's Secure Storage SDK dependency to 5.0.0—5.8.0 (i.e., a version prior to that which removes legacy migration support).
Launch the app and initialize the SDK as usual.
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.
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
This is an advance notice, you can still upgrade directly to the current version.
iOS
In the next version of the SDK we will remove migration support for storages created with SDK versions 4.17.5 to 4.29.0. Apps using Secure Storage SDK version 4.29.0 or earlier must first upgrade to version 5.x, i.e., a version that supports this migration, before upgrading to upcoming version 6.x of the SDK.
Upgrading directly from version 4.29.0 or earlier is not supported and will cause the storage migration to fail, making existing secure storage(s) unreadable.
If you already use version 5.x, before upgrading to version 6.x, and you get the migrationNeeded error, you must call getInstance(fileName:fingerprint:iterationNumber:) to migrate your storage.
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
This is an advance notice, you can still upgrade directly to the current version.
New features and enhancements
Android
Maven-based integration
The SDK artifact is now delivered as a local Maven repository, in addition to the previously published standalone aar artifact, and the package now also includes a documentation jar file. For more information, see Maven-based integration.
Sample showcases correct implementation for asynchronous behavior
For handling asynchronous behavior, the recommended pattern is to use the new SecureStorageWrapper.kt wrapper and run storage calls off the main thread, using lifecycleScope from the user interface. The sample included in the product package has been enhanced accordingly and showcases this pattern. For more information, see Handling of asynchronous behavior.
iOS
Enhanced error lookup
The technical documentation provided in the product package now includes the numeric value of each error code (SecureStorageErrorCodes), making error lookup easier.
General improvements
We added general improvements the help prevent potential issues and increase the SDK’s reliability and stability.
Fixes and other updates
Android
[MSS-13413]: Unexpected termination from ProGuard/R8 rules
Description: An issue caused ProGuard/R8 to rewrite methods, causing an unexpected termination.
Status: This issue has been fixed. New keep rules stop R8 from rewriting methods in SecureKeyStore and Crypto. This fixes a bytecode verifier crash seen with the minified release AAR when JaCoCo is involved, and an ART runtime warning.
Supported platforms
For information on the supported operating systems and platforms supported by Mobile Security Suite and the affiliated SDKs, see Supported platforms.
Known issues
For information on issues that have not yet been resolved in this release of Mobile Security Suite, see Known issues.
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!
Third party licenses
For information on third party dependencies associated with Mobile Security Suite and the affiliated SDKs in this release, see Third party licenses.