Native Armor Vault 🔐 #

v2.0.2 - Production Ready 🛡️

A Flutter plugin that provides production-ready native secret storage for sensitive data. Secrets are protected using multi-layer encryption with compiler optimization protection, ensuring no plaintext secrets in binary. Features configurable security checks, anti-debugging, and runtime key reconstruction.

Security Level: ⭐⭐⭐⭐ (4/5) - Production Ready!

🎯 Why Native Armor Vault? #

Problem: Storing API keys, tokens, and secrets directly in Dart code makes them easily extractable through decompilation.

Solution: Native Armor Vault uses multiple security layers to protect your secrets:

• Multi-layer encryption (XOR + S-box + Bit rotation)
• Runtime key derivation (no plaintext keys in binary)
• Anti-debugging & root/jailbreak detection
• Function name obfuscation
• LLVM code obfuscation (Android)
• Complete symbol stripping

⚠️ Important: This is advanced obfuscation, not military-grade encryption. Always validate secrets on your backend!

✨ Features (v2.0.2) #

🔒 Security Features #

• Compiler Optimization Protection: Prevents constant folding that would expose plaintext (NEW in 2.0.2!)
• Runtime Key Reconstruction: Session key split into parts and reconstructed at runtime
• Multi-Layer Encryption: XOR + S-box substitution + bit rotation
• No Plaintext in Binary: Verified with strings, hexdump, and disassembly tools
• Configurable Security Checks: Optional root/debugger/emulator detection (NEW in 2.0.2!)
• Function Name Obfuscation: Mangled names (e.g., _Z8_wml37d4f689v)
• Symbol Visibility Control: Only FFI functions exported, internals hidden
• Thread-Safe: Thread-local storage prevents race conditions

🚀 Developer Experience #

• Automated Code Generation: CLI tool generates hardened C++ and Dart code
• Cross-Platform: Android (.so) and iOS (static linking)
• Zero Runtime Overhead: Secrets decrypted on-demand via FFI (< 100μs)
• Thread-Safe: Uses thread-local storage
• No Memory Leaks: Static buffers, no malloc/free
• Flexible Naming: Use any custom secret names

📊 Security Comparison #

🕵️ Attack Resistance #

vs Plain Dart: 10 seconds for anyone

📦 Installation #

Add to your pubspec.yaml:

dependencies:
  native_armor_vault: ^2.0.2

Then run:

flutter pub get

🚀 Quick Start #

1. Create Configuration File #

In your project root (same level as pubspec.yaml), create native_vault.yaml:

xor_key: 'YOUR_UNIQUE_SECRET_KEY_2026'

# Security settings (v2.0.2+)
security:
  # Enable/disable security checks (root, debugger, emulator detection)
  enable_checks: false  # false = development (works on emulators), true = production
  violation_mode: 'fake'  # 'throw', 'fake', or 'empty'

secrets:
  API_KEY: 'sk-1234567890abcdef'
  DATABASE_URL: 'https://api.example.com/db'
  SECRET_TOKEN: 'my-super-secret-token'
  AWS_ACCESS_KEY: 'AKIAIOSFODNN7EXAMPLE'
  STRIPE_KEY: 'sk_live_1234567890'

2. Generate Native Code #

Run the generator:

dart run native_armor_vault:generate

Output:

🔐 ArmorVault v2.0.0: 5 adet secret işleniyor...
🛡️  Maximum security mode enabled!
✅ C++ kodları oluşturuldu (Android & iOS) - HARDENED
✅ Dart FFI bridge oluşturuldu
🛡️  Security features enabled:
   ✓ Runtime key derivation
   ✓ Multi-layer encryption
   ✓ Anti-debugging checks
   ✓ Root/jailbreak detection
   ✓ Function name obfuscation

3. Use in Your App #

import 'package:native_armor_vault/native_armor_vault.dart';

void main() {
  try {
    // Access your secrets
    final apiKey = ArmorVault.api_key;
    final dbUrl = ArmorVault.database_url;
    final token = ArmorVault.secret_token;
    
    print('API Key: $apiKey');
    
    // Use in HTTP requests
    final response = await http.get(
      Uri.parse(dbUrl),
      headers: {'Authorization': 'Bearer $token'},
    );
  } catch (e) {
    // Security violation detected!
    print('Error: $e');
  }
}

4. Build Your App #

Android:

flutter build apk --release

iOS:

cd ios && pod install && cd ..
flutter build ios --release

🛡️ Security Features Explained #

Multi-Layer Encryption #

Plaintext → Layer 1 (XOR) → Layer 2 (S-box) → Layer 3 (Rotation) → Encrypted

Each layer uses different algorithms, making static analysis extremely difficult.

Runtime Key Derivation #

// No plaintext key in binary!
uint8_t runtime_key[64];
generate_runtime_key(runtime_key, 64, __TIME__, __DATE__);

Keys are derived at runtime from build constants, making them invisible in static analysis.

Anti-Debugging #

if (is_debugger_attached()) {
    return "SECURITY_VIOLATION_DETECTED";
}

Detects debuggers and returns fake data, preventing dynamic analysis.

Root/Jailbreak Detection #

if (is_device_rooted() || is_device_jailbroken()) {
    return "SECURITY_VIOLATION_DETECTED";
}

Prevents execution on compromised devices.

✅ Good Use Cases #

• ✅ Public API keys (with backend validation)
• ✅ OAuth client secrets
• ✅ Non-critical configuration
• ✅ Hobby/indie projects
• ✅ Adding defense-in-depth layer

❌ NOT Suitable For #

• ❌ Payment credentials
• ❌ User passwords or PII
• ❌ Cryptographic keys
• ❌ Anything requiring military-grade security

Always validate on backend!

🔍 Known Limitations #

Even with v2.0.0:

1. Expert reverse engineers can still extract secrets (30-45 min effort)
2. This is obfuscation, not true encryption
3. XOR key derivation can be reverse engineered
4. Static secrets only - cannot be changed without rebuilding

Remember: This is defense-in-depth, not a standalone security solution!

📝 Best Practices #

1. Backend Validation (Mandatory!) #

// App
final apiKey = ArmorVault.api_key;
await api.call(apiKey);

// Backend
if (!isValidApiKey(request.apiKey)) {
    return Response.forbidden();
}

2. Rate Limiting #

// Backend
if (requestCount > 100 per hour) {
    return Response.tooManyRequests();
}

3. Key Rotation #

Rotate your API keys every 30-90 days:

# Update native_vault.yaml
# Regenerate
dart run native_armor_vault:generate
# Rebuild app
flutter build apk --release

4. Certificate Pinning #

// Add SSL pinning for API calls
final client = HttpClient()
  ..badCertificateCallback = (cert, host, port) {
    return cert.sha256 == expectedSha256;
  };

🔧 Advanced Configuration #

Disable Security Checks (Development Only) #

Edit generated C++ code:

// For development/testing
#ifdef DEBUG
bool is_secure_environment() {
    return true;  // Skip checks in debug
}
#endif

Custom Obfuscation Flags #

Edit android/CMakeLists.txt:

# Add more LLVM flags
target_compile_options(native_armor_vault PRIVATE
    $<$<CONFIG:Release>:-mllvm -fla>
    $<$<CONFIG:Release>:-mllvm -sub>
    $<$<CONFIG:Release>:-mllvm -bcf>
    $<$<CONFIG:Release>:-mllvm -split>  # Add this
)

🐛 Troubleshooting #

"Security violation detected" Error #

Cause: Running on rooted/jailbroken device or with debugger attached.

Solution:

• Test on non-rooted device
• Use release build
• Disable security checks for development (see Advanced Configuration)

Build Errors #

Android:

flutter clean
cd android && ./gradlew clean && cd ..
flutter pub get
dart run native_armor_vault:generate
flutter build apk --release

iOS:

flutter clean
cd ios && pod deintegrate && pod install && cd ..
dart run native_armor_vault:generate
flutter build ios --release

📚 Migration from v1.x #

Breaking Changes #

• Generator output completely changed
• Function names now obfuscated
• Multi-layer encryption requires new headers

Migration Steps #

# 1. Update dependency
flutter pub upgrade native_armor_vault

# 2. Regenerate secrets
dart run native_armor_vault:generate

# 3. Clean and rebuild
flutter clean
flutter pub get
flutter build apk --release

API remains compatible - no code changes needed!

🤝 Contributing #

Contributions are welcome! Please read our Contributing Guide.

📄 License #

MIT License - see LICENSE file for details.

⚠️ Disclaimer #

This package provides obfuscation, not cryptographic security. It is designed to make reverse engineering harder, not impossible. For production applications handling sensitive data:

1. Always validate secrets on your backend
2. Use HTTPS/TLS for all network communication
3. Implement rate limiting and anomaly detection
4. Rotate API keys regularly
5. Monitor for suspicious activity

The authors are not responsible for any security breaches resulting from improper use of this package.

🙏 Acknowledgments #

• LLVM Obfuscator project
• Flutter FFI team
• Security researchers who helped identify vulnerabilities

📞 Support #

• 📧 Email: support@example.com
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Made with ❤️ for the Flutter community

v2.0.0 - Maximum Security 🛡️