Kunci Laravel Package

Technical Evaluation

Architecture Fit The addition of deterministic encryption support in Kunci v1.1 introduces a paradigm shift in how sensitive data (e.g., PII, financial records) is encrypted within Laravel applications. Deterministic encryption ensures identical plaintext inputs produce identical ciphertext outputs, enabling efficient indexing, searching, and deduplication of encrypted data—critical for compliance (e.g., GDPR, HIPAA) and performance-sensitive use cases. This aligns well with systems requiring searchable encryption (e.g., audit logs, user profiles) or data deduplication (e.g., payment gateways, CRM integrations).

Integration Feasibility

• Pros:
  • Leverages Laravel’s service container for seamless dependency injection (e.g., Kunci::encryptDeterministic()).
  • Backward-compatible with existing probabilistic encryption (non-breaking change).
  • Supports custom key derivation via Kunci::setDeterministicKey() for granular control.
• Cons:
  • Security Implications: Deterministic encryption risks exposing patterns in ciphertext (e.g., frequency analysis). Requires rigorous key management and salting strategies.
  • Schema Changes: Existing encrypted fields may need migration if deterministic behavior is adopted (e.g., altering UNIQUE constraints to UNIQUE on ciphertext).
  • Performance Trade-offs: Deterministic ops are faster but may increase load on key management systems (e.g., AWS KMS, HashiCorp Vault).

Technical Risk

• High: Misconfiguration (e.g., weak keys, lack of salting) could expose sensitive data. Requires:
  • Cryptographic Review: Validate key derivation (e.g., PBKDF2/Argon2) and IV handling.
  • Data Migration Strategy: Plan for backfilling deterministic encryption for legacy data.
  • Compliance Audit: Ensure alignment with encryption standards (e.g., NIST SP 800-38A).
• Mitigations:
  • Use Kunci::deterministic() only for non-searchable data or pair with format-preserving encryption (FPE) for searchability.
  • Implement key rotation policies for deterministic keys (unlike probabilistic keys, deterministic keys must rotate to maintain security).

Key Questions

1. Use Case Alignment: Which encrypted fields require deterministic behavior (e.g., searchable emails vs. one-time tokens)?
2. Key Management: How will deterministic keys be stored/rotated (e.g., environment variables, Vault, custom DB table)?
3. Legacy Data: How will existing encrypted data be migrated without downtime?
4. Performance: What are the expected query patterns (e.g., LIKE on encrypted fields) and their impact on DB indexing?
5. Compliance: Does the organization’s encryption policy permit deterministic encryption for the targeted data?

Integration Approach

Stack Fit

• Laravel Ecosystem: Native integration with Laravel’s config, services.php, and Encrypter facade.
• Database: Requires support for BINARY/VARBINARY fields (MySQL/PostgreSQL) or JSONB (for nested deterministic encryption).
• Caching: Deterministic ciphertexts are cacheable (unlike probabilistic), but cache invalidation must account for key rotations.
• Third-Party Services: Compatible with APIs expecting encrypted payloads (e.g., Stripe, Auth0) if deterministic keys are shared.

Migration Path

1. Assessment Phase:
   • Audit existing encrypted fields to identify candidates for deterministic encryption.
   • Benchmark performance impact (e.g., EXPLAIN ANALYZE on encrypted WHERE clauses).
2. Pilot Phase:
   • Implement deterministic encryption for a non-critical field (e.g., user_metadata).
   • Test key rotation and data migration scripts.
3. Rollout Phase:
   • Blue-Green Deployment: Route deterministic-encrypted fields to new DB schema first.
   • Feature Flags: Use Laravel’s config('features.deterministic_encryption') to toggle behavior.
4. Deprecation Phase:
   • Phase out probabilistic encryption for fields where deterministic is adopted.

Compatibility

• Breaking Changes: None. Existing probabilistic encryption remains functional.
• Dependencies:
  • PHP 8.0+ (for named arguments in v1.1).
  • OpenSSL extension (required for all Kunci operations).
  • Laravel 8.0+ (for service container optimizations).
• Conflicts: Avoid mixing deterministic/probabilistic encryption for the same logical field (e.g., email encrypted both ways).

Sequencing

1. Pre-requisite: Upgrade to Kunci v1.1 and Laravel 8.0+.
2. Key Setup: Configure deterministic keys in .env or Vault:

   KUNCI_DETERMINISTIC_KEY=base64-encoded-32-byte-key
   KUNCI_DETERMINISTIC_SALT=unique-per-dataset-salt
   

3. Schema Update: Add deterministic flag to encrypted fields or create a shadow table.
4. Application Layer: Update encryption logic:

   // Probabilistic (existing)
   $ciphertext = Kunci::encrypt('secret');
   
   // Deterministic (new)
   $ciphertext = Kunci::deterministic()->encrypt('searchable-secret');
   

5. Testing: Validate with:
   • Unit tests for encryption/decryption cycles.
   • Integration tests for search queries on encrypted fields.
   • Penetration tests for key exposure scenarios.

Operational Impact

Maintenance

• Key Rotation:
  • Probabilistic: Rotate keys periodically (e.g., quarterly) with minimal impact.
  • Deterministic: Requires full re-encryption of all data encrypted with old keys (resource-intensive). Automate with a cron job:

    // Example key rotation script
    Kunci::setDeterministicKey(newKey());
    DB::table('users')->whereNotNull('encrypted_email')->get()->each(fn ($user) =>
        User::find($user->id)->forceFill(['encrypted_email' => Kunci::deterministic()->encrypt($user->email)])->save()
    );
    

• Monitoring: Track:
  • Encryption/decryption latency spikes (indicative of key management bottlenecks).
  • Failed decryption attempts (potential key misconfiguration).

Support

• Developer Onboarding:
  • Document deterministic encryption patterns (e.g., when to use vs. probabilistic).
  • Provide examples for common use cases (e.g., searchable hashes, deduplication).
• Troubleshooting:
  • Common Issues:
    • "Decryption failed" → Verify key/salt consistency across environments.
    • "Duplicate ciphertexts" → Confirm deterministic mode is enabled for the field.
  • Debugging Tools: Enable Kunci’s debug() mode to log encryption metadata.

Scaling

• Horizontal Scaling:
  • Deterministic encryption is stateless; scale read replicas for encrypted field queries.
  • Offload key derivation to a dedicated service (e.g., AWS Lambda) if CPU-bound.
• Database:
  • Index encrypted deterministic fields (e.g., CREATE INDEX idx_encrypted_email ON users(encrypted_email)).
  • Use partial indexes for filtered searches (e.g., WHERE encrypted_email LIKE '%@gmail.com').
• Cost:
  • Increased storage for ciphertexts (deterministic outputs are slightly larger).
  • Potential DB load from reindexing during key rotation.

Failure Modes

Ramp-Up

• Training:
  • Security Team: Review deterministic encryption trade-offs (e.g., searchability vs. pattern exposure).
  • Dev Team: Hands-on workshop on key management and migration scripts.
• Documentation:
  • Decision Records: Justify deterministic adoption for specific fields.
  • Runbooks: Steps for key rotation, data recovery, and incident response.
• Phased Rollout:
  • Start with low-risk fields (e.g., internal metadata) before PII.
  • Monitor decryption success rates post-migration.