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

Feature	Plain Dart	v1.x	v2.0.0
Decompilation resistance	❌	⚠️	✅
XOR key visibility	N/A	🔴 Plaintext	🟢 Obfuscated
Function names	✅ Clear	🔴 Clear	🟢 Mangled
Anti-debugging	❌	❌	✅
Root detection	❌	❌	✅
Code obfuscation	❌	❌	✅
Security Level	1/10	3/10	7-8/10

🕵️ Attack Resistance

Attacker Level	Time to Extract
Script kiddie	❌ Blocked
Intermediate hacker	4-6 hours
Advanced reverse engineer	1-2 hours
Expert	30-45 minutes

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:

Expert reverse engineers can still extract secrets (30-45 min effort)
This is obfuscation, not true encryption
XOR key derivation can be reverse engineered
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:

Always validate secrets on your backend
Use HTTPS/TLS for all network communication
Implement rate limiting and anomaly detection
Rotate API keys regularly
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 🛡️