Native Encrypted Storage #

A Flutter plugin for secure data storage with hardware-backed encryption using Android Keystore. All encryption happens in native code for maximum security.

Note: Currently supports Android only. iOS support is coming in a future update.

🔐 Features #

• ✅ AES-256-GCM Encryption - Military-grade encryption
• ✅ Hardware-Backed Security - Keys stored in Android Keystore
• ✅ Native Implementation - All encryption happens in native code (Kotlin)
• ✅ Simple API - Easy to use, similar to SharedPreferences
• ✅ No External Dependencies - Uses only Android native APIs
• ✅ Production Ready - Clean code without debug logs
• 🔜 iOS Support - Coming in a future update

🚀 Why Use This Plugin? #

The Problem with JWT and Other Tokens #

JWT tokens and API keys are often stored in plain text or with Base64 encoding, which is NOT encryption:

// ❌ INSECURE - Anyone with file access can read this
final prefs = await SharedPreferences.getInstance();
await prefs.setString('token', jwtToken);

Even though JWT is signed, the payload is readable by anyone:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiam9obiJ9.signature
                                        ↑ This is just Base64 - easily decoded!

The Solution #

// ✅ SECURE - Encrypted with AES-256, key stored in hardware
await storage.write(key: 'token', value: jwtToken);

The token is now encrypted and impossible to read without the encryption key from Keystore/Keychain.

📦 Installation #

Add this to your pubspec.yaml:

dependencies:
  native_encrypted_storage: ^0.1.0

Then run:

flutter pub get

🎯 Usage #

Basic Example #

import 'package:native_encrypted_storage/native_encrypted_storage.dart';

final storage = NativeEncryptedStorage();

// Save encrypted data
await storage.write(
  key: 'user_token',
  value: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
);

// Read and decrypt data
final token = await storage.read(key: 'user_token');
print(token); // Original value, automatically decrypted

// Delete data
await storage.delete(key: 'user_token');

// Delete all data
await storage.deleteAll();

// Check if key exists
final exists = await storage.containsKey(key: 'user_token');

// Get all keys
final keys = await storage.getAllKeys();

Real-World Example: Authentication #

class AuthService {
  final _storage = NativeEncryptedStorage();

  // Save user token after login
  Future<void> saveToken(String token) async {
    await _storage.write(key: 'auth_token', value: token);
  }

  // Get token for API requests
  Future<String?> getToken() async {
    return await _storage.read(key: 'auth_token');
  }

  // Save user credentials (if needed)
  Future<void> saveCredentials({
    required String email,
    required String password,
  }) async {
    await _storage.write(key: 'user_email', value: email);
    await _storage.write(key: 'user_password', value: password);
  }

  // Logout - clear all data
  Future<void> logout() async {
    await _storage.deleteAll();
  }
}

🔒 How It Works #

Architecture #

┌─────────────────────────────────────────┐
│         Your Flutter App                │
│  storage.write(key, value)              │
└─────────────────┬───────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│      Native Code (Kotlin)               │
│  1. Get encryption key from Keystore    │
│  2. Encrypt value with AES-256-GCM      │
│  3. Save encrypted data                 │
└──────────┬──────────────┬───────────────┘
           ↓              ↓
    ┌──────────┐   ┌─────────────┐
    │ Keystore │   │SharedPrefs  │
    │    🔑    │   │ key → 📦    │
    └──────────┘   └─────────────┘
    Hardware-backed  Encrypted data

What Gets Encrypted? #

Security Details #

• Algorithm: AES-256-GCM (Galois/Counter Mode)
• Key Size: 256 bits
• IV: Random 12 bytes per encryption
• Authentication: 128-bit authentication tag
• Key Storage: Android Keystore (hardware-backed) / iOS Keychain

🛡️ Security Guarantees #

✅ What This Plugin Protects Against #

1. File Access: Even if someone gets your app's data files, they cannot decrypt the data
2. Backup Extraction: Encrypted data in backups is useless without the hardware key
3. Rooted/Jailbroken Devices: Keys are hardware-protected and cannot be extracted
4. Memory Dumps: Data is encrypted at rest, only decrypted when needed

⚠️ What This Plugin Does NOT Protect Against #

1. Runtime Access: If malware is running in your app's process, it can read decrypted data
2. Screen Recording: Decrypted data shown on screen can be captured
3. Debugger Attachment: A debugger can read decrypted values in memory

📱 Platform Support #

🔧 API Reference #

Methods #

write({required String key, required String value})

Encrypts and saves a value.

await storage.write(key: 'api_key', value: 'secret123');

read({required String key})

Reads and decrypts a value. Returns null if key doesn't exist.

final value = await storage.read(key: 'api_key');

delete({required String key})

Deletes a key-value pair.

await storage.delete(key: 'api_key');

deleteAll()

Deletes all stored data.

await storage.deleteAll();

containsKey({required String key})

Checks if a key exists.

final exists = await storage.containsKey(key: 'api_key');

getAllKeys()

Returns all stored keys.

final keys = await storage.getAllKeys();

🆚 Comparison with Other Solutions #

💡 Best Practices #

✅ DO #

• Use for sensitive data (tokens, passwords, API keys)
• Use unique, descriptive keys
• Handle exceptions properly
• Clear data on logout

try {
  await storage.write(key: 'token', value: token);
} catch (e) {
  print('Failed to save token: $e');
}

❌ DON'T #

• Store large files (use encrypted file storage instead)
• Store non-sensitive data (use SharedPreferences for better performance)
• Use the same key for different data types
• Forget to handle null returns from read()

🐛 Troubleshooting #

Android: "Key not found" after app reinstall #

This is expected behavior. The encryption key is tied to the app installation. When you uninstall and reinstall, the old encrypted data cannot be decrypted.

Solution: Clear data on first launch after reinstall.

Android: Encryption fails #

Check that your minimum SDK version is met:

• Android: minSdkVersion 23 (Android 6.0)

iOS Support #

iOS support is coming in a future update. Stay tuned!

📄 License #

MIT License - see LICENSE file for details.

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Support #

For issues and feature requests, please use the GitHub issue tracker.

🙏 Acknowledgments #

• Android Keystore documentation
• iOS Keychain Services documentation
• Flutter plugin development guide

Made with ❤️ for secure Flutter apps