biometric_signature 13.3.0

biometric_signature: ^13.3.0 copied to clipboard

Added #

• Where a key lives, and its effective policy. New KeySecurityLevel enum (strongBox, trustedEnvironment, secureEnclave, secureHardware, software).
  • KeyInfo and KeyCreationResult gain securityLevel, so apps can tell whether a key ended up in StrongBox, the TEE, the Secure Enclave or software. Before, that depended on the device and wasn't reported. Android reads it from the keystore's KeyInfo. Android 9–11 can't tell StrongBox from the TEE, so keys on devices with StrongBox report secureHardware there. iOS/macOS report secureEnclave for EC keys and software for RSA keys, whose private key is stored encrypted by the Secure Enclave but signs in app memory. Windows reports null.
  • KeyInfo also gains requiresAuthentication, invalidatedByBiometricEnrollment and allowsDeviceCredentials: the key's effective policy, which can differ from what CreateKeysConfig asked for. For example, Android 10 and older ignore useDeviceCredentials, and an iOS/macOS key that accepts the passcode is never invalidated by enrollment changes.
• listKeyAliases() lists the aliases that have a key, without a prompt, with the default alias as null. Use it to find keys your app's records have lost, e.g. iOS/macOS keychain keys that survived an uninstall. On Windows it only finds aliases tracked in the app's settings, which an uninstall deletes, so after a reinstall only the default key is found.
• cancelButtonText now works on iOS and macOS for createKeys (with enforceBiometric), createSignature, createSignatureFromBytes, decrypt and simplePrompt, through LAContext.localizedCancelTitle. It used to be Android-only.
• biometricAuthAvailable(biometricStrength:). Android checked only for strong (Class 3) biometrics, so a device whose only biometric is Class 2 reported canAuthenticate: false even though simplePrompt with BiometricStrength.weak works there. The default stays strong; iOS, macOS and Windows ignore it. Use weak only before simplePrompt: a Class 2 biometric can never unlock a key, so signing, decryption and key creation with enforceBiometric always need a strong one.
• Platform interface: BiometricSignaturePlatform gains biometricAuthAvailableWithStrength and listKeyAliases. Both have default implementations, so implementations that extend it keep compiling and working: biometricAuthAvailableWithStrength falls back to biometricAuthAvailable(), and listKeyAliases throws UnimplementedError until implemented. Classes that implement the interface instead, such as mocks using MockPlatformInterfaceMixin, need to add both, as with any new platform method.

Fixed #

• Android: a key created with requireAuthentication: false couldn't sign or decrypt without a foreground activity. createSignature, createSignatureFromBytes and decrypt returned unknown ("Foreground activity required") as soon as no activity was attached, although such a key never shows a BiometricPrompt. So a background FlutterEngine, such as one handling a notification action while the app is closed, couldn't sign with the app's silent device key. The activity check now runs only before a prompt, so these keys work with no activity attached. Keys that need authentication still return "Foreground activity required" without an activity, and createKeys and simplePrompt still need one. Because the check runs later, a missing key (keyNotFound) is now reported ahead of a missing activity, and so is an empty payload (invalidInput) when signing. (#86)
• Android: decrypting with a requireAuthentication: false RSA key now uses the same OAEP parameters as other keys. That path built its own cipher, which named only the SHA-256 main digest and left the MGF1 digest to an undocumented AndroidKeyStore default, the reliance 13.0.0 removed from decryption with keys that prompt. It now pins SHA-256 and MGF1 SHA-1 too, and falls back the same way when a key doesn't accept that. The parameters are the ones AndroidKeyStore applied before, so existing ciphertext still decrypts.
• Windows: a key under the alias __default__ was mistaken for the default key. The plugin records each alias that has a key in the app's settings, and it recorded the default key as __default__, the same as a named alias of that name. So deleteAllKeys never deleted a key named __default__, deleteKeys on the default key stopped tracking it, and listKeyAliases reported it as the default alias. The default key is no longer recorded, because it is always checked directly, so every alias, __default__ included, is handled as itself. Settings written by earlier versions keep working.

Examples #

• The example app has an Android instrumented test, BackgroundSigningTest, that creates requireAuthentication: false keys with an activity attached, then signs with an EC key and decrypts with an RSA key from a second FlutterEngine that never had one. Run it on a device or emulator with ./gradlew :app:connectedDebugAndroidTest from example/android.
• The iOS example apps no longer crash at launch on iOS 27. iOS 27 doesn't launch an app built with Xcode 27 unless it adopts the UIScene life cycle, and the examples hadn't. Flutter's own scene support (FlutterSceneDelegate) isn't available in Flutter 3.24.5, which the examples also build with, so each app's AppDelegate.swift now runs a FlutterEngine that a SceneDelegate shows, with the scene declared in Info.plist. This works with Flutter 3.24.5 and newer versions alike.

Added #

• Optional key attestation. New CreateKeysConfig.attestationMode decides what createKeys does when attestationChallenge is set but the key can't be attested:
  • enforceOnChallenge (default): fails, as in 13.1.0.
  • enforceOnChallengeIfSupported: creates an unattested key when the device or platform can't attest keys (notSupported, including iOS, macOS and Windows), but still fails on transient keystore failures (notAvailable). Android 7–12 report transient failures as notSupported, so this mode falls back there.
  • preferred: creates an unattested key on any attestation failure.
  • disabled: ignores the challenge.
  • When a mode falls back, the key is created in the same call, with no second prompt, and the new KeyCreationResult.attestationErrorCode (notSupported or notAvailable) and attestationError say why. Every mode except disabled still returns invalidInput for an empty or over-128-byte challenge.

Changed #

• An invalid attestationChallenge now returns invalidInput on every platform. An empty or over-128-byte challenge used to return notSupported on Android 6 (API 23), iOS, macOS and Windows. The challenge length is now checked first, in every mode except disabled.

Added #

• Android hardware key attestation. Fixes #69.
  • New CreateKeysConfig.attestationChallenge (Uint8List, 1–128 bytes, Android 7.0+). When set, createKeys passes it to KeyGenParameterSpec.Builder.setAttestationChallenge, and returns the keystore's X.509 attestation chain for the new signing key in the new KeyCreationResult.attestationCertificateChain (List<Uint8List>, DER, leaf first). The plugin doesn't parse the chain; verify it on your server — see the README's "Hardware Key Attestation" section.
  • getKeyInfo returns the same chain in the new KeyInfo.attestationCertificateChain for keys created with a challenge. The chain is recognised by the key attestation extension (OID 1.3.6.1.4.1.11129.2.1.17) on its leaf; unattested keys report null.
  • Attestation is an explicit opt-in, so createKeys fails instead of returning an unattested key:
    • invalidInput for an empty or over-128-byte challenge, and notSupported on Android 6 (API 23). Both are checked before any existing key is touched.
    • notSupported when the keystore can't attest the key, and notAvailable for a transient keystore failure (e.g. attestation keys not provisioned yet — retry later with a fresh challenge). The transient case is detected on Android 13+; older versions report notSupported. As with any key-creation failure, the existing key under the alias has already been deleted by then; use failIfExists or a fresh alias to keep it.
    • If StrongBox key generation fails, the plugin retries once in the TEE. The chain's attestationSecurityLevel shows which one produced the key.
  • In hybrid mode (ecdsa + enableDecryption) only the keystore EC signing key is attested; the software decryption key cannot be.
  • iOS/macOS/Windows: setting attestationChallenge returns notSupported without touching existing keys, instead of being ignored like other platform-specific fields — ignoring it would hand back an unattested key the caller believes is attested. Apple has no public API to attest an individual Secure Enclave key, and Windows attestation is not implemented.
  • No new BiometricError values.

Fixed #

• Android: a failed hybrid-mode createKeys could leave a signing-only key behind. If the AES master key failed to generate after the EC signing key was created (ecdsa + enableDecryption), createKeys returned an error but left the EC key under the alias, so getKeyInfo reported a non-hybrid EC key there (with an attestation chain, if a challenge was set). The partially created keys are now deleted before the error is returned, as they already were for failures later in key creation, and also if the Flutter engine detaches while the keys are being generated.

• Android: a missing key was reported as unknown instead of keyNotFound. Signing or decrypting with an alias that has no key (or whose hybrid-mode decryption key is gone) threw a generic exception that fell through to unknown. These cases now return keyNotFound, as they already did on iOS, macOS and Windows.

• iOS/macOS: getKeyInfo couldn't return the public key of an RSA key, and reported it as hybrid. In RSA mode the RSA private key is stored wrapped by the Secure Enclave key, and its public key wasn't persisted, so getKeyInfo returned publicKey: null (reading it back would have needed a prompt). The public key is now stored at creation, so getKeyInfo returns the same key createKeys did. Keys created by earlier versions store it on their next successful sign or decrypt.

  • isHybridMode is now false for these keys in both createKeys (previously unset) and getKeyInfo (previously true). The same RSA key signs and decrypts, so this isn't hybrid mode (separate signing and decryption keys) as the field is defined, and it now matches Android's RSA mode. Encrypt RSA-OAEP payloads against publicKey; the README previously said decryptingPublicKey, which is null for these keys.

• iOS/macOS: a key invalidated by a biometric enrollment change was never reported as keyInvalidated. Signing or decrypting with a .biometryCurrentSet key after a face/fingerprint was enrolled or removed surfaced whatever the Secure Enclave returned, usually unknown or authenticationFailed, so apps couldn't tell that the key had to be re-created. The plugin now compares the enrollment snapshot saved at key creation before prompting, and returns keyInvalidated without showing a prompt, as Android does. getKeyInfo(checkValidity: true) uses the same check, which also fixes two false reports of an invalid key:

  • A key created with useDeviceCredentials: true uses .userPresence, which the device passcode can always satisfy, so an enrollment change never invalidates it. It was nevertheless recorded as invalidatable and reported isValid: false after one. Such keys are no longer recorded or reported as invalidatable.
  • Biometric lockout, and keys created before v8.1.0 (always .biometryAny or .userPresence), no longer report isValid: false.

• createSignature and decrypt now reject an empty payload before any prompt.

  • iOS/macOS createSignature signed an empty payload. createSignature(payload: '') went on to sign zero bytes, where Android and Windows return invalidInput. It now returns invalidInput ("Payload is required") before any key lookup or prompt, as createSignatureFromBytes already did. Android still also rejects a whitespace-only string; iOS, macOS and Windows sign it.
  • iOS/macOS decrypt checked the payload only after accessing the key, in RSA mode after the user had authenticated. An empty or whitespace-only payload then failed with unknown or invalidInput ("Invalid payload"), depending on the format. Both now return invalidInput ("Payload is required") before any key lookup or prompt, as on Android.
  • Android decrypt returned unknown for an empty payload when no activity was in the foreground, because it checked for the activity first. It now checks the payload first, as createSignature does.
  • Windows decrypt is unchanged: it returns notAvailable, since Windows doesn't support decryption.

• iOS/macOS: RSA-mode decrypt could return garbage as a successful result. When RSA-OAEP decryption failed, decrypt fell back to PKCS#1 v1.5, for ciphertext made for keys created before v11.0.0. Current iOS and macOS releases decrypt PKCS#1 v1.5 with implicit rejection: invalid ciphertext yields pseudorandom bytes instead of an error. So corrupted or tampered OAEP ciphertext fell through to the fallback, and roughly once in 100 to 300 attempts decrypt returned success with a meaningless, often empty, string (measured on iOS 26.5, iOS 27 and macOS 27).

  • Keys created with v11.1.0 or later now decrypt RSA-OAEP only, as Android keys created since v11.0.0 always have. If your server still encrypts PKCS#1 v1.5 for such keys, switch it to RSA-OAEP with SHA-256 and MGF1-SHA-256 (see "Encrypting a payload" in the README); PKCS#1 v1.5 ciphertext now fails with unknown.
  • Keys created before v11.1.0, and keys migrated from v2.x, keep the PKCS#1 v1.5 fallback, so their existing ciphertext still decrypts. Keys from 11.0.x can't be told apart from older ones, so they keep it too. The fallback now checks the padding itself (RFC 8017), so invalid ciphertext is rejected instead of turning into garbage.

• decrypt reported a malformed payload only after the user had authenticated. In RSA mode on iOS/macOS, and for every key that needs authentication on Android, the payload was decoded only after the prompt. It's now decoded first: input that isn't valid for payloadFormat returns invalidInput before any key access or prompt. So does input that can't be an ECIES payload (too short, or not starting with an uncompressed ephemeral key) for Android hybrid keys and iOS/macOS EC keys, once the key checks pass. It used to fail only later, sometimes with unknown.

  • Base64 is decoded strictly: spaces, tabs and line breaks are still ignored, but any other character outside the standard alphabet makes the payload invalid. Both platforms used to drop such characters and decode the rest, so A!Q== decoded as AQ== and .... as nothing.

• README: the ECIES section said no per-platform branch was needed. It is: Android derives a 16-byte AES key and a 12-byte GCM IV from the shared secret with empty shared info, while Apple's eciesEncryptionStandardX963SHA256AESGCM uses the ephemeral public key as shared info, derives only the key, and uses a 16-byte zero IV. A payload encrypted for one platform fails on the other. "Encrypting a payload" now gives both, and notes that decrypt returns UTF-8 text.

Examples #

• The example apps are rebuilt around what the plugin does beyond a biometric prompt; see EXAMPLES.md. example/ is now an API Explorer covering every method, option, format and error code, and the scenario apps (passwordless_login, banking_app, and secure_vault, formerly document_signer) verify signatures and Android attestation chains in an in-process mock server instead of only checking that a signature is non-empty.
• The example apps now target iOS 15.0 and macOS 12.0, the oldest versions Xcode 27 builds for. The plugin itself still supports iOS 13.0 and macOS 10.15.
  • Xcode 27 also fails on pods that declare an older minimum, including this plugin's, so the examples' Podfiles raise pod targets to the app's in post_install. Flutter 3.47 and later do this for you; on older versions, an app that builds with Xcode 27 through CocoaPods needs the same step.

Added #

• Two new descriptive BiometricError causes: authenticationFailed (an attempt that didn't succeed — unrecognised biometric or the platform couldn't process it; retrying usually works) and notInteractive (the prompt couldn't be shown, e.g. the app is backgrounded). Whether to retry or degrade is left to the consumer.

Changed (breaking) #

• Errors that used to surface as unknown are now classified more precisely:
  • iOS: authenticationFailed and the observed -1000 code → authenticationFailed; notInteractive → notInteractive; app-cancel → systemCanceled; -1018 and keychain errSecInteractionNotAllowed → notAvailable; keychain errSecAuthFailed → authenticationFailed.
  • Android: UNABLE_TO_PROCESS (2) and "key user not authenticated" → authenticationFailed. Pruned keystore ops and TIMEOUT (3) stay unknown with the enriched message; the retry-once for pruned ops still applies.
• Adding enum values is breaking for exhaustive switches on BiometricError.
• CreateKeysConfig.setInvalidatedByBiometricEnrollment now defaults to true on every platform. The default diverged per platform: Android used true, iOS/macOS used false, so the same createKeys call produced keys with different lifetimes on each platform. All platforms now default to true, matching AndroidKeyStore's own default for auth-bound keys (mInvalidatedByBiometricEnrollment = true) and the flag's documented security intent. Fixes #70.
  • Android: unchanged.
  • iOS/macOS: a createKeys call that leaves the flag unset now produces a .biometryCurrentSet Secure Enclave key instead of .biometryAny, so the key is permanently invalidated when a face/fingerprint is enrolled or removed and the app must create a new key and re-enroll its public key. Pass setInvalidatedByBiometricEnrollment: false to keep the previous behaviour. Use getKeyInfo(checkValidity: true) to detect an invalidated key before signing.
  • The flag remains ignored on Windows, and is ignored when requireAuthentication is false — a key created without a user-authentication constraint carries no biometry binding, so it is neither invalidated nor reported as invalid on enrollment changes.

Fixed #

• Android: an explicit setInvalidatedByBiometricEnrollment: false was silently ignored. KeyManager.configureInvalidation only ever called KeyGenParameterSpec.Builder.setInvalidatedByBiometricEnrollment(true) and skipped the call entirely for false. Since AndroidKeyStore's own default is true, opting out left the platform default in place and the key was still permanently invalidated on the next biometric enrollment — with no error to indicate the request had been dropped. The setter is now always called with the caller's value (API 24+; API 23 has no setter and always invalidates).

• Android: the plugin failed to configure under Android Gradle Plugin 9. AGP 9 ships "built-in Kotlin" — it supplies the Kotlin toolchain itself — and rejects kotlin-android with "The 'org.jetbrains.kotlin.android' plugin is no longer required for Kotlin support since AGP 9.0", so android/build.gradle aborted at apply plugin: "kotlin-android". AGP 9 also removed kotlinOptions {} from the Android extension. The plugin now applies kotlin-android only when AGP has not already registered a kotlin extension, and sets the JVM target through kotlin { compilerOptions { jvmTarget } }, which works on both toolchains. Verified building on AGP 8.9.1/Gradle 8.12/Flutter 3.24.5, and on AGP 9.3.1/Gradle 9.6.1/Flutter 3.44.8 with android.builtInKotlin both true (the AGP 9 default) and false (what Flutter's AGP 9 migrator writes). Fixes #78.

  • compileSdk stays at 35: a library's compileSdk is a floor for its consumers, not a ceiling, so apps on compileSdk 36/37 already build against it. Raising it would force every consuming app to raise theirs.
  • On AGP 9, Flutter prints WARNING: ... plugins that apply Kotlin Gradle Plugin (KGP): biometric_signature. It is a text match on this plugin's build file, not a reflection of what runs, and is safe to ignore — see the README.

• lintOptions {} (deprecated) replaced with the equivalent lint {} block.

Fixed(android): pin RSA-OAEP MGF1 digest to SHA-1 for decryption #

AndroidKeyStore defaults to SHA-1 for the MGF1 digest in RSA-OAEP, even when SHA-256 is used as the main digest. To prevent future platform changes from making existing ciphertexts undecryptable, this change explicitly pins the RSA-OAEP parameters.

Changed #

• Signing failures now report a meaningful error code instead of unknown (iOS/macOS). createSignature previously hard-coded code: .unknown on every SecKeyCreateSignature failure, discarding the real cause. classifySigningError now walks the CFError's NSUnderlyingErrorKey chain and maps the first layer it recognises — LAErrorDomain via mapLAError, NSOSStatusErrorDomain (e.g. errSecUserCanceled / -128) via mapSecError — so a cancelled or unavailable signing prompt surfaces BiometricError.userCanceled / BiometricError.notAvailable regardless of whether the cancel arrives as the top-level CFError, an OSStatus layer, or a nested LAError (e.g. a localized "Authentifizierung abgebrochen." cancel). The "Signing Error: …" message is additionally enriched with the full domain:code chain (e.g. … [CryptoTokenKit:-4 -> com.apple.LocalAuthentication:-2]) so any still-unmapped failure is self-describing in logs. Both the RSA and EC signing paths are covered.
• Android UNKNOWN errors are no longer flattened to a constant string. ErrorMapper.safeErrorMessage used to collapse every unmapped failure to "Biometric operation failed", throwing away both the numeric BiometricPrompt code and the original errString. The UNKNOWN branch now appends whatever context is available, e.g. "Biometric operation failed (code=3 msg=…)", keeping failures diagnosable in logs without an API/schema change.

Added #

• Non-interactive (no user authentication) keys via CreateKeysConfig.requireAuthentication. Defaults to true (existing behaviour). When set to false, the key pair is created without a use-time user-authentication constraint and can be used to sign/decrypt without any biometric or device-credential prompt — useful for a device-bound key that lives alongside an interactive (biometric) key under a different keyAlias.

  • Android: the keystore key is generated without setUserAuthenticationRequired(true) (and without per-operation auth / invalidation), and createSignature/decrypt detect the key's KeyInfo.isUserAuthenticationRequired and skip the BiometricPrompt entirely.
  • iOS/macOS: the Secure Enclave key is created with only .privateKeyUsage access control (no .biometryAny/.userPresence) and kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, so signing/decryption never prompt while the device is unlocked.
  • Windows: ignored — Windows Hello always authenticates.
  • Security note: a non-interactive key provides device binding ("something you have") only; it does not verify user presence and cannot satisfy inherence-based SCA requirements.

• New createSignatureFromBytes method: Introduced a high-level API to request biometric signatures directly over raw binary payloads (Uint8List), supporting secure challenge-response and transaction validation patterns across Android, iOS/macOS and Windows.

• Binary Challenge-Response Demo Card: Added a demonstration card inside the example app showcasing the complete secure random nonce generation and direct signing workflow.

• Android: three more BiometricPrompt error codes are classified. ErrorMapper.mapToBiometricError now maps ERROR_NO_BIOMETRICS (11) → notEnrolled, ERROR_HW_NOT_PRESENT (12) → notAvailable, and ERROR_SECURITY_UPDATE_REQUIRED (15) → securityUpdateRequired. ERROR_TIMEOUT (3) and ERROR_VENDOR (8) intentionally remain enriched-UNKNOWN so their volume can be observed before assigning a dedicated bucket.

• Android: error-source markers. Failures now carry a short source tag so a "couldn't even show the prompt" failure isn't mistaken for a signing failure: [src=prompt cred=<allowDeviceCredentials>] for real onAuthenticationError callbacks, [src=availability] for canAuthenticate pre-checks, and [src=launch] for setup/launch failures (e.g. the host is not a FragmentActivity). CancellationException is passed through unchanged so coroutine cancellation semantics and its userCanceled classification are preserved.

Fixed #

• Android: transient Keystore operation pruning during signing is now retried. The crypto-bound signing operation is opened at prepareSignature() and held open across the entire BiometricPrompt interaction. While a device-credential (PIN/pattern) prompt is showing, the app is backgrounded and its operation has the lowest pruning resistance, so keystore2 can evict it (INVALID_OPERATION_HANDLE / "outcome: Pruned") whenever another operation needs a slot — which previously surfaced as a hard "Biometric operation failed". Since the key is intact, createSignature now detects this specific transient failure (ErrorMapper.isPrunedOperationError) and transparently re-runs begin → authenticate → sign once before giving up. Pruning is contention-based, not a timeout, so it can strike no matter how long the user takes on the credential screen.

Fixed #

• Android prompt customization fields are now honored on createKeys, createSignature, and decrypt. The Dart API and Pigeon schema have always exposed promptSubtitle, promptDescription, and cancelButtonText on CreateKeysConfig / CreateSignatureConfig / DecryptConfig, and the README documented them, but the Android plugin was silently dropping them — createKeys and decrypt hard-coded null, null, "Cancel" into the BiometricPrompt, and createSignature hard-coded null for the description. All three are now threaded through to BiometricPrompt.PromptInfo.Builder. Fixes #67.
• Release-build biometric type detection on Android. Added ProGuard/R8 keep rules for androidx.biometric.BiometricManager#getStrings(int) and BiometricManager$Strings#getButtonLabel() / getPromptMessage() / getSettingButtonLabel(), which are invoked via reflection by BiometricPromptHelper.detectBiometricTypes to disambiguate face/fingerprint/iris on devices that advertise multiple BIOMETRIC_STRONG modalities. Without these rules, R8 would rename or strip the methods in release builds and the label-matching path would silently fall back to feature-flag-only detection.

Changed #

• Lowered minimum Flutter to 3.24.5 / Dart to 3.5.0. The plugin resolves on Flutter 3.24.5 with a small Android build-config override in the consuming app — Flutter 3.24.5's defaults (flutter.compileSdkVersion = 34, flutter.ndkVersion = "23.1.7779620", flutter.minSdkVersion = 21) are below what androidx.biometric:1.4.0-alpha05 and modern AndroidX plugins require. Set compileSdk = 35, ndkVersion = "27.0.12077973", and minSdk = 23 in your app's android/app/build.gradle.kts. See README → "Required Android build configuration" for the exact snippet.
• Android minSdk lowered to 23, the floor required by androidx.biometric for BiometricPrompt.
• Android compileSdk lowered to 35 (from 36). The plugin no longer requires Android SDK Platform 36 or AGP 8.9.1 — compileSdk = 35 and AGP 8.6.0 are sufficient.
• androidx.biometric:biometric downgraded from 1.4.0-alpha06 → 1.4.0-alpha05, which only requires compileSdk 35 and AGP 8.6.0. Plugin's buildscript classpath also dropped to AGP 8.6.0 to match.
• Pigeon dev dependency loosened from 25.3.2 → ^25.3.2.

Fixed #

• iOS shouldMigrate: true against an existing EC key no longer errors. Previously, setting shouldMigrate: true on CreateSignatureConfig / DecryptConfig against a v10+ EC-only key (no legacy v2.x RSA in the keychain) triggered a misfired migration that returned RSA private key not found in Keychain. The migration is now auto-detected from keychain state instead of a caller-supplied flag, so the misfire scenario is structurally unreachable. Fixes #65.

Removed (Breaking) #

• Custom fallback options on the biometric prompt (Android 15+). The androidx.biometric API for Fallback.CustomOption, Fallback.ICON_TYPE_*, and AuthenticationResult.CustomFallbackSelected only exists in 1.4.0-alpha06+, which forced compileSdk = 36. Removed entirely so the plugin can run on broader tooling.
  • Removed BiometricFallbackOption class.
  • Removed BiometricError.fallbackSelected enum value.
  • Removed fallbackOptions field from CreateKeysConfig, CreateSignatureConfig, DecryptConfig, and SimplePromptConfig.
  • Removed selectedFallbackIndex and selectedFallbackText fields from SignatureResult, DecryptResult, and SimplePromptResult.
• shouldMigrate flag on CreateSignatureConfig and DecryptConfig. The iOS Secure Enclave migration from v2.x unwrapped RSA keys is now auto-detected (see Fixed above). Apps no longer need to opt in — and no longer can opt in incorrectly. Pigeon-bridged removal, so existing call sites that pass shouldMigrate: true or shouldMigrate: false will fail to compile until the parameter is dropped.

Migration from 11.x #

• If you were using BiometricFallbackOption to render Android 15+ custom fallback buttons, you now need to drive that fallback behaviour from your own UI (e.g. catch the negative-button cancel, then present a Flutter sheet listing the alternatives). The plugin's standard cancelButtonText and allowDeviceCredentials flow still work everywhere they did before.
• If you were branching on BiometricError.fallbackSelected or reading selectedFallback* fields, those code paths can be deleted — they will never fire from the new plugin version.
• Delete the shouldMigrate: line from any CreateSignatureConfig(...) / DecryptConfig(...) constructor calls. The plugin auto-detects whether a legacy v2.x RSA key exists and migrates it on the first sign/decrypt call when appropriate.

Added #

• isDeviceLockSet() API: New method on BiometricSignature to check whether a device-lock credential is configured. Android uses KeyguardManager.isDeviceSecure() (authoritative). iOS/macOS evaluate LAPolicy.deviceOwnerAuthentication; true means "set or indeterminate" — a stronger guarantee surfaces via the reactive BiometricError.passcodeNotSet during the next operation. Windows reports Windows Hello availability via KeyCredentialManager.IsSupportedAsync(), not a generic screen-lock state — see the dartdoc for details.
• AuthenticationType reporting: New AuthenticationType enum (credential, biometric, unknown) plus an authenticationType field on KeyCreationResult, SignatureResult, DecryptResult, and SimplePromptResult. Authoritative on Android (from BiometricPrompt.AuthenticationResult). Inferred on Apple platforms from the key's stored useDeviceCredentials flag and biometric hardware availability; returns .unknown when the stored flag is unavailable rather than falsely reporting .biometric. Always .unknown on Windows.
• BiometricError.passcodeNotSet: Dedicated error code for "device has no screen lock / passcode configured", distinct from notAvailable.

Fixed #

• iOS/macOS authenticationType inference: The useDeviceCredentials flag is now persisted in the keychain at key-creation time and read during sign/decrypt, replacing the previous signing-time heuristic that could not produce an accurate result.
• iOS/macOS keychain accessibility: The DeviceCredentialsSetting keychain item is now created with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, matching the lifetime of the Secure Enclave key it accompanies and keeping the flag device-local.
• https://github.com/chamodanethra/biometric_signature/issues/62 was fixed.

Changed #

• Breaking (behavioural) — Android error mapping: ERROR_NO_DEVICE_CREDENTIAL (cause code 14) now maps to BiometricError.passcodeNotSet instead of BiometricError.notAvailable. Consumers that were pattern-matching on BiometricError.notAvailable to drive a "no screen lock" UX must update their switch statements to handle BiometricError.passcodeNotSet. This is a minor-version bump because the Dart API surface is unchanged; only the runtime error value differs.
• Breaking (behavioural) — iOS/macOS error mapping: kLAErrorPasscodeNotSet now maps to BiometricError.passcodeNotSet instead of BiometricError.notAvailable. Same migration guidance as above.

• Documentation updates.
• Bug fixes.

Fixed #

• Fixed macOS SPM issue.

Added #

• Named Key Aliases: All key operations (createKeys, createSignature, decrypt, deleteKeys, getKeyInfo, biometricKeyExists) now accept an optional keyAlias parameter, allowing apps to manage multiple independent key pairs (e.g., one for auth, one for payment signing).
• Key Overwrite Protection: CreateKeysConfig.failIfExists prevents accidental key replacement. When true, createKeys() fails with BiometricError.keyAlreadyExists if a key with the specified alias already exists.
• Delete All Keys: New deleteAllKeys() method removes all plugin-managed keys across all aliases.
• Custom Fallback Options (Android 15+): All config classes (CreateKeysConfig, CreateSignatureConfig, DecryptConfig, SimplePromptConfig) now support fallbackOptions — a list of BiometricFallbackOption items that appear as custom buttons on the biometric prompt. When the user taps a fallback option, the result contains BiometricError.fallbackSelected with selectedFallbackIndex and selectedFallbackText.
• OAEP Padding for RSA: RSA encryption now uses OAEP padding with PKCS#1 v1.5 fallback for improved security.
• Atomic File Writing: Sensitive key material writes use atomic file operations to prevent data corruption.

Fixed #

• KEY_INVALIDATED Error Mapping: BiometricError.keyInvalidated is now correctly returned when keys have been invalidated by biometric enrollment changes on Android.
• Android Coroutine Dispatching: Key management operations now use proper coroutine dispatchers (IO for file/crypto operations).
• CancellationException Handling: Structured concurrency is preserved — CancellationException is always rethrown, preventing callbacks to a detached Flutter engine.
• Hybrid Key Cleanup: If the second biometric authentication fails during hybrid key creation, partially-created keys are now cleaned up.

Changed #

• Modularized Android Architecture: Extracted Android plugin into focused helper classes (BiometricPromptHelper, CryptoOperations, ErrorMapper, FileIOHelper, FormatUtils, KeyManager).
• Unified macOS/iOS Plugin: Consolidated Swift plugin code using conditional compilation (#if os(macOS)) to support both platforms from a single source file.
• Refined ProGuard Rules: Updated Android ProGuard/R8 rules for better compatibility.

• Enhance biometric key security on iOS/macOS.
• Enforce CryptoObject usage for Android signatures.
• Add Android ProGuard rules.

• Added Swift Package Manager (SPM) support for iOS and macOS plugin integration.
• Migrated iOS/macOS native source layout to Package.swift + Sources/<plugin_name>/.
• Updated Pigeon generation output paths for Darwin host code to match the SPM layout.
• Updated CocoaPods podspecs to remain compatible alongside SPM.
• Updated package and platform version references/documentation.
• Fix: Enhanced biometric type detection for android.

• Breaking: Added new BiometricError enum values; consumers using exhaustive switches must handle the new cases(security update required, not supported, system canceled, prompt error).
• Feature: Added simplePrompt() for lightweight biometric authentication without cryptographic operations.
• Fix: Improved Android error handling and prompt robustness.
• Fix: Aligned iOS/macOS error mapping with Android.
• Docs: Updated README and usage examples.

• Reduced published package size by ~45%.

• Package Optimization: Reduced published package size significantly:
  • Converted assets/logo.png (1.0 MB) to assets/logo.jpeg (120 KB), reducing image size by ~90%
  • Added .pubignore to exclude example applications (banking_app, document_signer, passwordless_login) from published package
  • Total package size reduced from ~2 MB to ~535 KB
• Maintenance: Updated version references across all platform files and documentation.
• Minor bug fix.
• Enhanced the passwordless login example.
• Added "Migration Guide" section to the README.md.

• Feature: Added "Biometric Decryption" section to README.md with a detailed lifecycle diagram (usecase-2.png) and process description.
• Improved: Enhanced Windows platform documentation to clarify KeyCredentialManager usage, TPM backing, RSA-2048 constraints, and lack of decryption support.
• Metadata: Updated pubspec.yaml description to explicitly include supported platforms and Windows Hello.
• Maintenance: Updated Android native dependency.

• Breaking: Method signature changes:

  • createKeys() now takes config, keyFormat, promptMessage parameters
  • createSignature() now takes payload, config, signatureFormat, keyFormat, promptMessage parameters
  • decrypt() now takes payload, payloadFormat, config, promptMessage parameters

• Moved cross-platform parameters into unified config objects:

  • signatureType, enforceBiometric, setInvalidatedByBiometricEnrollment, useDeviceCredentials now in CreateKeysConfig
  • Each field is documented with which platform(s) it applies to

Architecture - Type-safe Communication with Pigeon #

• Breaking: Migrated entire platform communication layer to Pigeon.
• Breaking: Replaced raw string/map returns with structured strongly-typed objects:
  • KeyCreationResult: Contains publicKey, error, and code.
  • SignatureResult: Contains signature, publicKey, error, and code.
  • DecryptResult: Contains decryptedData, error, and code.
  • BiometricAvailability: detailed availability status including enrolled biometric types and error reasons.
• Breaking: Standardized BiometricError enum across all platforms.

API Improvements #

• Breaking: biometricAuthAvailable() now returns a BiometricAvailability object instead of a raw string.
• Removed legacy signature_options.dart, decryption_options.dart and old config classes.
• Enhanced error handling with specific error codes (e.g., userCanceled, notEnrolled, lockedOut) instead of generic strings.
• New getKeyInfo() method: Retrieve detailed information about existing biometric keys without creating a signature.
  • Returns KeyInfo object with: exists, isValid, algorithm, keySize, isHybridMode, publicKey, decryptingPublicKey.
  • Accepts checkValidity parameter to verify key hasn't been invalidated by biometric changes.
  • Accepts keyFormat parameter to specify output format (base64, pem, hex).
• New KeyInfo class: Exported via Pigeon for type-safe key metadata.
• biometricKeyExists() is now a convenience wrapper around getKeyInfo().

Improved #

• Cleaner, simpler API with fewer method parameters
• Better documentation of platform-specific options
• Updated all example projects to use new API

Added - macOS Platform Support #

Platform Integration

• Full macOS support for biometric authentication using Touch ID.
• Native macOS implementation via BiometricSignaturePlugin.swift.
• Support for macOS 10.15 (Catalina) and later.
• CocoaPods integration for seamless dependency management.

API and Configuration

• New MacosConfig class for platform-specific configuration:
  • useDeviceCredentials: Enable device credentials (passcode) fallback
  • signatureType: Support for both MacosSignatureType.RSA and MacosSignatureType.ECDSA
  • biometryCurrentSet: Bind keys to current Touch ID enrollment state
• New Parameter: Added optional promptMessage parameter to createKeys() method across all platforms
  • Allows customization of the authentication prompt when enforceBiometric is true
  • Defaults to "Authenticate to create keys" for backward compatibility
  • Provides context-specific instructions to users during key generation

Security Features

• App-specific keychain isolation: Keychain identifiers now incorporate bundle identifier to prevent cross-app conflicts on macOS
  • Each app's keys are completely isolated: {bundleId}.eckey, {bundleId}.biometric_key, etc.
  • Solves the issue where multiple apps using the plugin would share the same keychain items
  • iOS implementation remains unchanged as it already has proper sandboxing
• Secure Enclave integration for EC key storage and operations
• Hardware-backed cryptographic operations using macOS Security framework
• Domain state tracking for biometric enrollment changes

Cryptographic Features

• RSA Mode:
  • RSA-2048 hardware-backed signing
  • Hybrid mode with software RSA decryption key wrapped via ECIES
• EC Mode:
  • P-256 (secp256r1) hardware-backed signing in Secure Enclave
  • Native ECIES decryption using SecKeyAlgorithm.eciesEncryptionStandardX963SHA256AESGCM
  • Support for EC-only mode and hybrid EC mode

Implementation Details

• Biometry change detection via LAContext.evaluatedPolicyDomainState
• Automatic key invalidation when Touch ID enrollment changes (when biometryCurrentSet is true)
• Support for all key formats: BASE64, PEM, RAW, HEX
• Consistent error handling and Flutter method channel integration

Changed #

• Updated platform interface to distinguish macOS from iOS
• Enhanced BiometricSignaturePlatform to properly handle macOS-specific parameters
• Updated documentation with macOS integration steps and examples
• Added macOS to platform support table (macOS 10.15+)

Added #

• ECIES decryption on Android and iOS.
• X9.63-SHA256 KDF and AES-128-GCM support for elliptic-curve decryption.
• RSA decryption support via decrypt() on Android and iOS.
• enableDecryption option in AndroidConfig to generate RSA keys with decryption capability.
• Cross-platform ECIES support for P-256 (secp256r1) keys.

Android #

• Manual ECIES implementation using ECDH, X9.63 KDF, and AES-GCM.
• Software EC private key for decryption is encrypted using a biometric-protected AES-256 master key (Keystore/StrongBox).
• Wrapped EC private key blob is stored in app-private files with MODE_PRIVATE permissions.
• All sensitive key material is zeroized after use.

iOS #

• Native ECIES support through SecKeyAlgorithm.eciesEncryptionStandardX963SHA256AESGCM.
• Hybrid RSA mode: software RSA key for decryption encrypted via ECIES with Secure Enclave EC public key.

Architecture #

• Updated hybrid EC design:
  • Android: hardware EC signing key + AES-wrapped software EC decryption key
  • iOS: hardware EC signing key + ECIES-wrapped software RSA key

Misc #

• Expanded documentation and updated examples.
• Improved test coverage across decryption and hybrid modes.

• Optimize iOS createKeys implementation.
• ReadMe.md was updated.

• Added enforceBiometric parameter to createKeys() method to require biometric authentication before generating the key-pair.
• Added an optional subtitle parameter to Android biometric prompts via AndroidSignatureOptions.
• ReadMe.md and example updates.

• Upgraded Flutter from 3.32.8 to 3.35.7
• Upgraded Dart SDK from ^3.8.1 to ^3.9.2
• iOS minimum deployment target upgraded from 12.0 to 13.0
• Android minimum SDK upgraded from 23 to 24
• Upgraded Android Gradle Plugin from 8.7.3 to 8.9.1
• Upgraded Android compileSdk from 35 to 36
• Refactored Android native code to use internal objects for error constants and key aliases
• Code quality improvements: formatting and style consistency updates across example projects

• A small bug was fixed.

• Added an optional parameter to configure whether the key should be invalidated on new biometric enrollment when creating the key.

• Breaking: createKeys now returns a KeyCreationResult instead of a plain base64 string, enabling configurable output formats.
• Breaking: createSignature returns a SignatureResult that includes both the formatted signature and public key metadata.
• Added KeyFormat support across Dart, Android, and iOS with BASE64, PEM, RAW (DER/bytes), and HEX representations.
• Android: refactored native layer to emit structured maps, generate PEM blocks directly, and expose raw DER bytes when requested.
• iOS: aligned public key formatting with SubjectPublicKeyInfo, added PEM/RAW/HEX conversions, and unified signature responses.
• Updated documentation, examples, and helper classes to illustrate working with FormattedValue utilities.
• Removed createSignatureFromLegacyOptions helper.

• ReadMe.md updates.
• Reverting back to previous iOS IPHONEOS_DEPLOYMENT_TARGET(12.0).
• Added 3 practical-world examples.

• Updating documentations.
• Minor bug fixes.

• Fix formatting errors.

• Updating documentations.

• Breaking: Replace the map-based createSignature API with typed SignatureOptions, plus platform-specific option classes.
• Added createSignatureFromLegacyOptions helper to ease migration from the legacy API.
• Fixed Android allowDeviceCredentials parsing so boolean values are honoured.
• Updated the iOS plugin to accept native booleans for shouldMigrate.
• Improved Android native Kotlin coroutines implementation.
• Updated native dependencies.

• The migrate path for iOS from 5.x is preserved.
• ReadMe.md updates.

• Suggesting a fix for issue.

• Suggesting a fix for issue using Kotlin coroutines.

• fix dart formatting errors.

• Upgrading Flutter from 3.27.2 to 3.32.8.
• Updating the README.md file descriptions.
• Adding ECDSA Key support for cryptographic operations.
• Suggesting a fix for issue.

• Suggesting a fix for issue.

• Upgrading Flutter from 3.27.0 to 3.27.2.
• Updating the README.md file descriptions.
• Device Credentials' fallback support for compatible devices can be configured.

• Feature - Allow Device Credentials as a fallback for biometric authentication.

• Upgrading Flutter from 3.19.6 to 3.27.0

• A bug fix for key user not authenticated android crash.

• A bug fix for android KeyStoreException crash.

• A bug fix in iOS createKeys() flow.

• ReadMe.md updates.

• Feature Secure Enclave migration from Key Chain.

• Secure Enclave integration in iOS.

• Fix iOs issue: biometricKeyExists always false .

• Fix linting issues.

• Feature Use StrongBox in compatible android devices.
• Refactor key creation to use AndroidConfig object.

• fix Local Authentication bypass in iOS when calling createSignature().

• fix Biometric portal not coming up in iOS simulators when calling createSignature().
• General improvements.

• A crash on Android devices below API level 28 was fixed.
• General improvements.

• Fixed a bug in createKeys() for iOS.
• Fixed a bug in createSignature() for android.
• Error codes were updated to maintain consistency.
• Updated README.md and Licence content.
• Hardcoded default payload was removed.
• Improved error handling.

New Features: #

• The plugin offers more flexibility for advanced use cases, such as handling different biometric modalities and customizing the signature generation process.

Bug Fixes: #

• Improved the handling of biometric prompt cancellations.
• Enhanced the accuracy of biometric authentication on some devices.

Other Changes: #

• Updated the plugin's documentation to reflect the new features and improvements.
• Migrated the plugin to use the latest Flutter development tools.
• Improved the overall performance and stability of the plugin.
• This version is now compatible with AGP >=7.3 including 8.x support.

Breaking Changes: #

• The minimum supported Flutter version has been increased to 3.3.0.

Fixed: #

• Android: Fixed the issue with the createSignature() method, ensuring it doesn't encode the payload to base64.
• iOS: Corrected the public key header in createKeys() method to align with standard RSA key formats.

Other Changes: #

• Updated README.md and Licence content.

• Removes a redundant code push in Android native code.
• Updates README.md and the Example.

• Returns "biometric" for Android devices with multiple BIOMETRIC_STRONG options when called biometricAuthAvailable().
• Let createSignature() accept a "payload" keyValue pair in options arg.
• updates dependencies.
• updates README.md and the Example.

• Consistent Platform error handling.
• Upgrade dependencies.

• improved documentation.

• upgrading flutter sdk to 3.7.11.
• improved documentation.

• upgrading dependencies.
• refactoring.

• fixing createSignature's options param.

• downgrade min Dart Sdk.

• improved documentation.

• initial release.