better_local_auth

Enhanced Flutter plugin for local authentication with required cryptoObject support for Android security compliance.

Overview

better_local_auth is a fork and enhancement of the local_auth-3.0.1 Flutter package. It addresses security concerns identified by static analysis tools like Ostorlab by making the Android cryptoObject parameter required for biometric authentication. This change ensures that apps using biometric authentication on Android are not flagged as insecure.

Key Features

Security First: Requires cryptoObject on Android to prevent security warnings from static analysis tools
Simplified Maintenance: Consolidates multiple packages into one, removes unused platform support
Backward Compatibility: Maintains API compatibility with local_auth-3.0.1 where possible
Enhanced Features: Adds optional keychain support for iOS secure storage
Clear Migration Path: Provides comprehensive migration guidance for developers

Platform Support

Platform	Supported	Changes from local_auth
Android	✅ Yes	`cryptoObject` required
iOS	✅ Yes	`keychainOptions` required
Windows	❌ No	Removed
Web	❌ No	Removed
Linux	❌ No	Removed
macOS	❌ No	Removed

Installation

Add better_local_auth to your pubspec.yaml:

dependencies:
  better_local_auth: ^1.0.0

iOS Setup

For iOS, you need to add the NSFaceIDUsageDescription key to your app's Info.plist file to use Face ID:

<key>NSFaceIDUsageDescription</key>
<string>Your reason for using Face ID (e.g., "App needs to authenticate using faces.")</string>

This description will be shown to users when they are asked for Face ID permission.

Usage

Basic Authentication

import 'package:better_local_auth/better_local_auth.dart';
import 'package:better_local_auth/src/types/types.dart';

final auth = LocalAuthentication();

// Create required cryptoObject and keychainOptions
final cryptoObject = CryptoObject.forSignature(
  keyAlias: 'my_app_key',
  data: Uint8List.fromList('data_to_sign'.codeUnits),
);

final keychainOptions = KeychainOptions(
  serviceName: 'com.example.app',
  accountName: 'user_token',
);

try {
  final bool didAuthenticate = await auth.authenticate(
    localizedReason: 'Please authenticate to access secure data',
    cryptoObject: cryptoObject,
    keychainOptions: keychainOptions,
  );
  
  if (didAuthenticate) {
    // User authenticated successfully
  }
} on ArgumentError catch (e) {
  // Handle missing cryptoObject or keychainOptions
  print('Security requirement missing: ${e.message}');
} on LocalAuthException catch (e) {
  // Handle authentication errors
  print('Authentication failed: ${e.code}');
}

Enhanced API

For additional features, use BetterLocalAuthentication:

import 'package:better_local_auth/better_local_auth.dart';

final betterAuth = BetterLocalAuthentication();

// Use factory methods for common crypto objects
final signatureCrypto = BetterLocalAuthentication.createSignatureCryptoObject(
  keyAlias: 'signing_key',
  dataToSign: Uint8List.fromList('important_data'.codeUnits),
);

// Enhanced authentication with detailed results
final result = await betterAuth.authenticateEnhanced(
  localizedReason: 'Authenticate to sign transaction',
  cryptoObject: signatureCrypto,
  keychainOptions: KeychainOptions(
    serviceName: 'com.example.app',
    accountName: 'transaction_signing',
  ),
);

if (result.authenticated) {
  print('Authentication successful');
  print('Crypto result: ${result.cryptoResult}');
  print('Keychain key: ${result.keychainStorageKey}');
}

Device Capabilities

final LocalAuthentication auth = LocalAuthentication();

// Check if device supports biometrics
final bool canAuthenticateWithBiometrics = await auth.canCheckBiometrics;

// Check if device supports any authentication
final bool canAuthenticate = await auth.isDeviceSupported();

// Get enrolled biometrics
final List<BiometricType> availableBiometrics = await auth.getAvailableBiometrics();

Migration from local_auth

Breaking Changes

Android cryptoObject Requirement: The cryptoObject parameter is now required for Android authentication
iOS keychainOptions Requirement: The keychainOptions parameter is now required for iOS authentication
Platform Support: Windows, Web, Linux, and macOS platforms are no longer supported

Migration Steps

Update Dependencies: Replace local_auth with better_local_auth in your pubspec.yaml
Add Required Parameters: Update all authenticate() calls to include cryptoObject and keychainOptions
Remove Platform-Specific Code: Remove any code specific to Windows, Web, Linux, or macOS
Test on Both Platforms: Verify authentication works correctly on Android and iOS

Migration Example

Before (local_auth):

import 'package:local_auth/local_auth.dart';

final auth = LocalAuthentication();

final bool didAuthenticate = await auth.authenticate(
  localizedReason: 'Please authenticate',
);

After (better_local_auth):

import 'package:better_local_auth/better_local_auth.dart';
import 'package:better_local_auth/src/types/types.dart';

final auth = LocalAuthentication();

// Create required security objects
final cryptoObject = CryptoObject.forSignature(
  keyAlias: 'my_app_key',
  data: Uint8List.fromList('auth_data'.codeUnits),
);

final keychainOptions = KeychainOptions(
  serviceName: 'com.example.app',
  accountName: 'authentication',
);

final bool didAuthenticate = await auth.authenticate(
  localizedReason: 'Please authenticate',
  cryptoObject: cryptoObject,
  keychainOptions: keychainOptions,
);

Common Migration Issues

Missing cryptoObject on Android: Will throw ArgumentError with clear message
Missing keychainOptions on iOS: Will throw ArgumentError with clear message
Platform-specific code: Remove any conditional code for unsupported platforms

Security Considerations

Android CryptoObject Requirement

The cryptoObject requirement ensures that biometric authentication on Android performs cryptographic operations, which:

Prevents security warnings from static analysis tools like Ostorlab
Ensures authentication results can be cryptographically verified
Provides secure key storage in Android's Keystore system
Enables secure operations like data signing and encryption

iOS Keychain Integration

The keychainOptions requirement ensures secure storage of authentication results in iOS Keychain, which:

Provides hardware-backed secure storage
Enables secure token storage and retrieval
Supports biometric-protected keychain items
Maintains security even if device is lost or stolen

API Reference

LocalAuthentication Class

Maintains API compatibility with local_auth-3.0.1 but requires additional security parameters.

Methods:

authenticate() - Authenticate user with biometrics (requires cryptoObject and keychainOptions)
stopAuthentication() - Cancel in-progress authentication
canCheckBiometrics - Check if device supports biometrics
isDeviceSupported() - Check if device supports any authentication
getAvailableBiometrics() - Get list of enrolled biometrics