Download the PHP package vimatech/laravel-secure-fields without Composer

Laravel Secure Fields

Secure encrypted Eloquent model fields for Laravel.

Laravel Secure Fields lets you encrypt sensitive database fields with AES-256-GCM while preserving a natural Eloquent developer experience — searchable, maskable, and rotatable.

Why Laravel Secure Fields?

Most Laravel apps storing sensitive data eventually need to answer:

• How do I encrypt PII fields at rest?
• How do I search encrypted data without decrypting everything?
• How do I rotate keys without downtime?
• How do I prevent accidental plaintext leaks in API responses?

Laravel Secure Fields provides a focused encryption layer for that.

Feature Matrix

Laravel Secure Fields vs Laravel's Built-in Encryption

Laravel Secure Fields manages:

• Field-level encryption with proper AES-256-GCM
• Searchable encrypted fields via blind indexes
• Key rotation tooling
• Serialization safety and masking

Laravel's encrypt() / Crypt facade:

• General-purpose encryption
• No searchability
• No field-level tooling
• No rotation command

They are complementary — this package is purpose-built for Eloquent model fields.

Use Cases

• PII storage (SSN, phone, email)
• GDPR / HIPAA compliance
• Payment-related data
• API keys and secrets storage
• Healthcare records
• Legal documents
• Multi-tenant sensitive data

Installation

Requirements

• PHP 8.3+
• Laravel 11, 12, or 13
• OpenSSL extension

Publish config

Publish migrations (optional, for audit logging)

Generating Keys

Important: Always generate dedicated keys. Never leave SECURE_FIELDS_KEY or SECURE_FIELDS_HASH_KEY empty — an empty value silently falls back to a key derived from APP_KEY, which means a compromised APP_KEY would expose both session/cookie encryption and all field-level ciphertext.

Generate a 32-byte encryption key (base64-encoded):

Generate a 32-byte hash key (hex-encoded or base64):

Add both to your .env:

Minimum requirements:

• SECURE_FIELDS_KEY — 32 bytes, base64-encoded (validated at boot)
• SECURE_FIELDS_HASH_KEY — minimum 32 bytes/characters (validated at boot)

Quick Start

1. Add encrypted fields to your model

2. Create your migration

Important: Use TEXT columns for encrypted fields — encrypted payloads are larger than plaintext. Add nullable() only when the field is genuinely optional in your domain. The cast handles null values correctly in both cases.

3. Use it naturally

Searchable Encrypted Fields

Search encrypted fields without exposing plaintext:

The package stores a deterministic HMAC-SHA256 hash alongside the encrypted value, enabling exact-match queries while the actual data remains encrypted.

How it works

1. On save: encrypts the value AND stores HMAC-SHA256(plaintext) in a {field}_hash column
2. On search: hashes the search term and queries the hash column
3. The hash is one-way — it cannot be reversed to obtain the plaintext

Search normalization

Blind index hashes are case-insensitive and whitespace-trimmed. These three searches are equivalent and will find the same record:

This normalization is applied consistently on both write and search, so records are always findable regardless of input case.

Field Masking

Encrypted fields are hidden by default from toArray() and toJson() to prevent accidental exposure. toMaskedArray() makes them visible with masking applied:

You can also mask individual fields with custom parameters:

Encrypted JSON Fields

Encrypt entire JSON structures:

Key Rotation

Rotate encryption keys without downtime. The rotation command re-encrypts all field values with the new key while the SECURE_FIELDS_KEY in your .env already points to the new key.

Rotation workflow

1. Generate a new key: php -r "echo base64_encode(random_bytes(32)), PHP_EOL;"
2. Update SECURE_FIELDS_KEY in .env to the new key
3. Run the rotation command with the old key
4. Verify data integrity
5. Remove the old key from any backups or records

Running the rotation

The old key is read via a secure interactive prompt that does not appear in process listings or shell history:

Security note: For automated pipelines, prefer passing the old key via an environment variable read inside a wrapper script rather than as a CLI argument:

Hash key rotation

The SECURE_FIELDS_HASH_KEY is separate from the encryption key and used only for HMAC blind indexes. If you need to rotate the hash key:

1. Changing SECURE_FIELDS_HASH_KEY will invalidate all existing blind indexes — secureWhere() queries will return no results for existing records until indexes are rebuilt.
2. A secure-fields:rehash command for rebuilding indexes is planned for a future release.
3. Until then, rotate the hash key only during a maintenance window where you can rebuild indexes manually.

Serialization Protection

Encrypted fields are automatically hidden from toArray() and toJson() to prevent accidental exposure in API responses or logs:

Audit Logging

The package can log every field decryption event, enabling access trail for GDPR, HIPAA, and SOC 2 compliance.

Configuration

What is logged

Deduplication

Within a single request, the same (model, id, field) combination is logged at most once, regardless of how many times the attribute is accessed. This prevents log flooding when iterating over collections.

Database driver

With SECURE_FIELDS_AUDIT_DRIVER=database, audit rows are batched and written in a single INSERT at the end of the request — not one INSERT per access. This keeps the hot path free of synchronous database writes.

The audit table must be published and migrated before enabling the database driver:

FrankenPHP / Laravel Octane

The AuditLogger is bound as scoped() in the service container, meaning a fresh instance is created for each request in Octane and FrankenPHP worker mode. The deduplication cache and pending batch are request-scoped and never leak between requests.

Log driver

The log driver writes to a Laravel log channel with no additional database queries — a good default for high-throughput applications.

Facade Usage

Configuration

Environment Variables

Complete Example

Security Notes

Encryption

• Uses AES-256-GCM — authenticated encryption providing confidentiality and integrity
• Every encryption generates a unique random 12-byte IV — no IV reuse
• 16-byte authentication tags protect against tampering
• Keys are derived via HKDF when using the APP_KEY fallback (not recommended for production)

Key Management

• Always set dedicated SECURE_FIELDS_KEY and SECURE_FIELDS_HASH_KEY values
• The APP_KEY fallback couples your session/cookie security to your field encryption — a compromised APP_KEY exposes both
• Store keys in a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) rather than .env files for production

Searchable Fields

• Uses HMAC-SHA256 with a separate key for blind indexes
• Hash indexes enable exact-match only — no partial search, no LIKE queries
• The hash is deterministic but one-way — cannot be reversed to plaintext
• Uses constant-time comparison to prevent timing attacks
• Search values are normalized (lowercased, trimmed) before hashing — ensure data is stored with the same normalization

Best Practices

• Use a dedicated SECURE_FIELDS_KEY separate from APP_KEY
• Use a dedicated SECURE_FIELDS_HASH_KEY for search indexes
• Rotate encryption keys periodically
• Enable audit logging in production (SECURE_FIELDS_AUDIT=true)
• Use TEXT columns — encrypted data is larger than plaintext
• Add nullable() only when the field is genuinely optional in your domain
• Never log decrypted sensitive values
• Configure TrustProxies middleware for accurate IP logging in audit records

Philosophy

Laravel Secure Fields is intentionally focused.

The package manages:

• Encryption at the field level
• Searchability via blind indexes
• Key rotation tooling
• Serialization safety

Design principles:

• Backend-only, UI agnostic
• Security-first defaults
• Laravel-native API
• Minimal configuration required
• Clean and testable

It does not aim to become a permissions framework, a full-disk encryption system, or a key management service.

Testing

Run static analysis:

Format code:

Contributing

Contributions are welcome.

Please ensure:

• Tests pass (composer test)
• PHPStan passes (composer analyse)
• Code style is formatted with Pint (composer format)

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our Security Policy for reporting vulnerabilities.

License

The MIT License (MIT). Please see License File for more information.

Credits

Built and maintained by Vimatech. Created by Adel Zemzemi.