AndroidOptions

Specific options for Android platform for secure storage.

Provides configurable options for encryption, key wrapping, biometric enforcement, and shared preferences naming.

Properties

• biometric_prompt_subtitle(str) –

  Subtitle displayed in the biometric authentication prompt.

• biometric_prompt_title(str) –

  Title displayed in the biometric authentication prompt.

• enforce_biometrics(bool) –

  Whether to enforce biometric or PIN authentication.

• key_cipher_algorithm(KeyCipherAlgorithm) –

  Algorithm used to encrypt the secret key.

• migrate_on_algorithm_change(bool) –

  When the encryption algorithm changes, automatically migrate existing data

• preferences_key_prefix(str | None) –

  Prefix for shared preference keys. Ensures keys are unique to your app.

• reset_on_error(bool) –

  When an error is detected, automatically reset all data to prevent fatal errors

• shared_preferences_name(str | None) –

  The name of the shared preferences database to use.

• storage_cipher_algorithm(StorageCipherAlgorithm) –

  Algorithm used to encrypt stored data.

Properties

biometric_prompt_subtitle class-attribute instance-attribute

biometric_prompt_subtitle: str = (
    "Use biometrics or device credentials"
)

Subtitle displayed in the biometric authentication prompt.

biometric_prompt_title class-attribute instance-attribute

biometric_prompt_title: str = 'Authenticate to access'

Title displayed in the biometric authentication prompt.

enforce_biometrics class-attribute instance-attribute

enforce_biometrics: bool = False

Whether to enforce biometric or PIN authentication.

When True

• The plugin throws an exception if no biometric/PIN is enrolled.
• The encryption key is generated with authentication required.

When False

• The plugin gracefully degrades if biometrics are unavailable.
• The key is generated without authentication required.

key_cipher_algorithm class-attribute instance-attribute

key_cipher_algorithm: KeyCipherAlgorithm = (
    RSA_ECB_OAEP_WITH_SHA256_AND_MGF1_PADDING
)

Algorithm used to encrypt the secret key.

Legacy RSA/ECB/PKCS1Padding is available for backwards compatibility.

migrate_on_algorithm_change class-attribute instance-attribute

migrate_on_algorithm_change: bool = True

When the encryption algorithm changes, automatically migrate existing data to the new algorithm. Preserves data across algorithm upgrades.

If False, data may be lost when algorithm changes unless reset_on_error is True.

preferences_key_prefix class-attribute instance-attribute

preferences_key_prefix: str | None = None

Prefix for shared preference keys. Ensures keys are unique to your app.

An underscore (_) is added automatically.

Changing this prevents access to existing preferences.

reset_on_error class-attribute instance-attribute

reset_on_error: bool = True

When an error is detected, automatically reset all data to prevent fatal errors with unknown keys.

Be aware that data is PERMANENTLY erased when this occurs.

shared_preferences_name class-attribute instance-attribute

shared_preferences_name: str | None = None

The name of the shared preferences database to use.

Changing this will prevent access to already saved preferences.

storage_cipher_algorithm class-attribute instance-attribute

storage_cipher_algorithm: StorageCipherAlgorithm = (
    AES_GCM_NO_PADDING
)

Algorithm used to encrypt stored data.

Legacy AES/CBC/PKCS7Padding is available for backwards compatibility.

Disabling Auto Backup

By default Android backups data on Google Drive. It can cause exception java.security.InvalidKeyException: Failed to unwrap key. You need to:

• Disable autobackup, details
• Exclude sharedprefs used by SecureStorage

Add the following to your pyproject.toml:

[tool.flet.android.manifest_application]
"allowBackup" = "false"
"fullBackupContent" = "false"

Encryption Options

Default

AndroidOptions()

• Key Cipher: RSA/ECB/OAEPWithSHA-256AndMGF1Padding
• Storage Cipher: AES/GCM/NoPadding
• Biometric Support: No
• Description: Standard secure storage with RSA OAEP key wrapping. Strong authenticated encryption without biometrics. Recommended for most use cases.

Optional Biometrics

AndroidOptions(
    enforce_biometrics=False,
    key_cipher_algorithm=KeyCipherAlgorithm.AES_GCM_NO_PADDING,
)

• Key Cipher: AES/GCM/NoPadding
• Storage Cipher: AES/GCM/NoPadding
• Biometric Support: Optional
• Description: KeyStore-based with optional biometric authentication. Gracefully degrades if biometrics unavailable.

Required Biometrics

AndroidOptions(
    enforce_biometrics=True,
    key_cipher_algorithm=KeyCipherAlgorithm.AES_GCM_NO_PADDING,
)

• Key Cipher: AES/GCM/NoPadding
• Storage Cipher: AES/GCM/NoPadding
• Biometric Support: Required (API 28+)
• Description: KeyStore-based requiring biometric/PIN authentication. Throws error if device security not available.

Custom Cipher Combinations

For advanced users, all combinations below are supported using the AndroidOptions() constructor with custom parameters:

Key Cipher Algorithm	Storage Cipher Algorithm	Implementation	Biometric Support
RSA_ECB_PKCS1_PADDING	AES_CBC_PKCS7_PADDING	RSA-wrapped AES	No
RSA_ECB_PKCS1_PADDING	AES_GCM_NO_PADDING	RSA-wrapped AES	No
RSA_ECB_OAEP_WITH_SHA256_AND_MGF1_PADDING	AES_CBC_PKCS7_PADDING	RSA-wrapped AES	No
RSA_ECB_OAEP_WITH_SHA256_AND_MGF1_PADDING	AES_GCM_NO_PADDING	RSA-wrapped AES	No
AES_GCM_NO_PADDING	AES_CBC_PKCS7_PADDING	KeyStore AES	Optional (via enforce_biometrics)
AES_GCM_NO_PADDING	AES_GCM_NO_PADDING	KeyStore AES	Optional (via enforce_biometrics)

Biometric Authentication

Secure Storage supports biometric authentication (fingerprint, face recognition, etc.) on Android API 23+.

Required Permissions

To use biometric authentication on Android, you need to grant the necessary permissions (USE_BIOMETRIC and optionally USE_FINGERPRINT) in your project.

For configure permissions in your pyproject.toml or when building the app using flet build.

See the official Flet documentation for details: Android Permissions in Flet

Example configuration in pyproject.toml:

[tool.flet.android.permission]
"android.permission.USE_BIOMETRIC" = true
"android.permission.USE_FINGERPRINT" = true

You can also pass permissions when building your Android app:

flet build \
  --android-permissions android.permission.USE_BIOMETRIC=True \
  android.permission.USE_FINGERPRINT=True

This ensures that biometric authentication works correctly on all supported Android devices.

Using Biometric Authentication

You can enable biometric authentication:

# Optional biometric authentication (graceful degradation)
storage = SecureStorage(
  android_options=AndroidOptions(
    enforce_biometrics=False, # Default - works without biometrics
    biometric_prompt_title='Unlock to access your data',
    biometric_prompt_subtitle='Use fingerprint or face unlock',
  ),
)

# Strict biometric enforcement (requires device security)
storage = SecureStorage(
  android_options=AndroidOptions(
    enforce_biometrics=True, # Requires biometric/PIN/pattern
    biometric_prompt_title: 'Biometric authentication required',
  ),
)

Requirements

• API Level: Android 6.0 (API 23) minimum for basic encryption
• API Level: Android 9.0 (API 28) minimum for enforced biometric authentication
• Device Security: Device must have a PIN, pattern, password, or biometric enrolled (when using enforce_biometrics = True)
• Permissions: USE_BIOMETRIC permission in pyproject.toml