Skip to main content
Version: 4.3.x.x RR (Android, iOS) / 4.4.x.x RR (Flutter, React Native)

Device Migration and Backup/Restore

The Nevis Mobile Authentication SDK does not support transferring registered credentials to a new device, whether through OS-level backup/restore mechanisms or device migration flows. This applies to all SDK variants, native and cross-platform alike: Android, iOS, React Native, and Flutter.

Why credentials cannot be transferred​

Private keys created during FIDO UAF registration are stored in hardware-backed secure storage:

Both are designed to be non-exportable: private key material never leaves the secure hardware boundary. This is a fundamental security property of the FIDO UAF protocol. Authenticators are bound to the specific device hardware on which they were registered. Even Apple and Google cannot read or copy these keys out of the secure hardware.

Alongside the private keys, the SDK stores supporting metadata (push notification keys, PIN material, and internal state) in platform data stores:

  • Android: SharedPreferences
  • iOS: Keychain

This metadata can be included in OS backups or device transfers. When restored or transferred to a new or factory-reset device, the metadata references private keys that no longer exist in the secure hardware of that device. The result is an inconsistent state that causes the SDK to fail.

Android​

App Auto Backup​

The Android Auto Backup feature can back up and restore app data, including SharedPreferences. Because the FIDO private keys are hardware-bound and cannot be transferred, restoring backed-up SDK metadata to a device creates an inconsistency: the metadata references keys that do not exist in the Keystore of the target device.

caution

If SDK data is backed up and then restored, the SDK can fail during initialization.

This is a mandatory configuration step, not an optional hardening measure. For more information on excluding SDK data from backups, see Android installation.

Android device-to-device migration​

The Android OS-level device migration flows (for example, the Setup Wizard restore, Google One Backup, or cable-based device transfer) may copy app data, including SharedPreferences, to the new device. The private keys in the Android Keystore are hardware-bound and cannot be transferred. Any SDK metadata migrated to the new device will reference key material that does not exist in the Keystore of the new device, causing the SDK to fail.

iOS​

iCloud Backup​

iCloud backup includes app data and most Keychain items, but Secure Enclave keys are never included in any backup. They are hardware-bound and non-exportable by design. Other SDK data stored in the Keychain (such as PIN material and internal metadata) may be included in the iCloud backup.

When the backup is restored on a new device or a factory-reset device, the Keychain data is present but the corresponding Secure Enclave key is absent. Attempting to authenticate with a previously registered FIDO credential will fail because the private key cannot be found.

Device-to-device migration (iPhone Quick Start, Migration Assistant)​

The Apple device migration flows, such as iPhone Quick Start and iTunes/Finder restore, transfer app data and Keychain items to the new device. However, Secure Enclave private keys are explicitly excluded from all migration mechanisms.

As a result, after migration the new device will contain SDK metadata that references private keys which are not present in the Secure Enclave of the new device. Authentication attempts will fail.

Expected SDK behavior​

After a backup restore or device migration, the SDK will encounter one of the following situations:

  1. SDK initialization fails (primarily Android): If the SharedPreferences data of the SDK has been restored but the corresponding keys do not exist in the Keystore of the device, the SDK returns an InitializationError during initialization.

  2. Authentication operation fails (primarily iOS, also possible on Android): The SDK initializes successfully but fails during authentication when attempting to use the hardware-bound key. The operation returns an OperationError.

In both cases, the existing credentials are not recoverable. The user must go through a new registration process on the target device.

info

For more information on initialization and operation errors, see Error Handling.

Recovery flow​

When the SDK state is inconsistent after a device migration or backup restore, the recommended recovery flow is:

  1. Detect the failure: The SDK returns an error during initialization (InitializationError) or during an operation (OperationError).

  2. Inform the user: Display a clear message explaining that the previous registration is no longer valid on this device and that re-registration is required.

  3. Clean up local state: Use the Remove Local Data operation to clear any stale local SDK state on the device.

  4. Clean up the stale credential on the backend: Because the private key is no longer available on the device, the SDK deregistration operation cannot be used. The stale registration must be removed directly on the server side. Depending on the design of the application:

    • Provide a self-service flow where the user authenticates with alternative credentials (for example, username and password) and the application calls the backend to remove the stale FIDO credential.
    • Alternatively, provide a support desk process where a support agent removes the credential on behalf of the user.

  5. Re-register: Guide the user through the standard Registration flow on the target device.

Recommendations for SDK integrators​

  • Android: Always configure your application to exclude SDK data from backups, see Android installation. Failing to do so will cause the SDK to break whenever users restore a backup on the same or a different device.

  • iOS: No SDK-level backup configuration is needed. The OS guarantees that Secure Enclave keys are never exported. Ensure your app handles authentication failures gracefully after device migrations, since this is an expected scenario.

  • Error handling: Implement robust error handling for both InitializationError and OperationError. The re-registration path must always be accessible to users, even when authentication fails.

  • UX: Consider informing users proactively that switching to a new device requires re-registration. A short explanation during onboarding or in the app settings reduces support burden and user confusion.

  • Backend credential management: Implement a mechanism for users or support agents to deregister stale credentials on the backend. Without this, users will accumulate orphaned registrations after every device migration.

Last updated on