Native Encrypted Storage

pub package License

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?

Item Encrypted? Location Purpose
Encryption Key ✅ Hardware-protected Android Keystore Encrypts/decrypts data
Key (identifier) ❌ Plain text SharedPreferences Used to find data
Value (your data) ✅ AES-256-GCM SharedPreferences Your sensitive data

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

Platform Status Minimum Version Encryption Backend
Android ✅ Supported API 23 (6.0) Android Keystore
iOS 🔜 Coming Soon - -

🔧 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

Feature Native Encrypted Storage flutter_secure_storage SharedPreferences Hive (encrypted)
Hardware-backed ✅ Yes ✅ Yes ❌ No ❌ No
Encryption ✅ AES-256-GCM ✅ AES-CBC ❌ None ✅ AES-256
Native Code ✅ Yes ✅ Yes ✅ Yes ❌ Dart only
Key Storage ✅ Keystore/Keychain ✅ Keystore/Keychain ❌ Plain text ❌ In app
Performance ⚡ Fast ⚡ Fast ⚡ Very Fast ⚡ Very Fast
Setup ✅ Zero config ⚠️ Requires config ✅ Zero config ⚠️ Manual key

💡 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

Libraries

native_encrypted_storage
native_encrypted_storage_method_channel
native_encrypted_storage_platform_interface