Job Encryption and Serialization

Purpose and Scope

This document explains how jobs are serialized and optionally encrypted in the hypervel/queue system. It covers two primary mechanisms:

1. Job Encryption: Protecting sensitive job payload data at rest using the ShouldBeEncrypted interface
2. Closure Serialization: Enabling closure-based jobs through SerializableClosure configuration

For information about transaction-aware dispatching, see 7.3. For job middleware and processing features, see 7.1.

---

Overview

The queue system handles two critical serialization concerns when dispatching jobs:

Job Serialization: All jobs must be converted to a string format for storage in queue backends. The system uses PHP's serialize() function to convert job objects into storable payloads. When jobs contain closures, the SerializableClosure library enables these closures to be serialized with their captured variables.

Job Encryption: For jobs containing sensitive data, the system provides optional encryption. When a job implements the ShouldBeEncrypted interface (or sets the $shouldBeEncrypted property), the serialized job object is encrypted before storage, ensuring sensitive data cannot be read by anyone with queue backend access.

Key Features:

• Transparent serialization and optional encryption during job dispatch
• Automatic deserialization and decryption during job processing
• Support for closures in job payloads via SerializableClosure
• Configurable serialization hooks for custom value transformation
• Works with all queue drivers
• Minimal code changes required

---

Encryption Check Flow

The system determines whether a job requires encryption through a two-step check process:

Diagram: Job Encryption Decision Process

Sources: src/Queue.php221-228

---

Implementing Encrypted Jobs

Interface-Based Approach

The recommended approach is to implement the ShouldBeEncrypted interface:

Property-Based Approach

Alternatively, set the $shouldBeEncrypted property on the job class:

Approach	Advantages	Use Case
Interface	Type-safe, explicit contract	New jobs, team projects
Property	Quick implementation, less formal	Rapid development, legacy code

Sources: src/Queue.php16 src/Queue.php221-228

---

Encryption Mechanism

Payload Creation with Encryption

The encryption occurs during payload creation in the createObjectPayload method:

Diagram: Encryption Sequence During Job Dispatch

Code Implementation

The encryption logic is implemented in the createObjectPayload method:

Encryption Logic (src/Queue.php146-148):

Encryption Check (src/Queue.php221-228):

Payload Structure

The encrypted job is stored in the payload's data.command field:

Payload Field	Unencrypted Job	Encrypted Job
data.commandName	Full class name	Full class name (always visible)
data.command	Serialized object	Encrypted serialized object
uuid	Generated UUID	Generated UUID
job	Handler class	Handler class
Other metadata	Visible	Visible

Only the actual job object is encrypted. Metadata like uuid, displayName, maxTries, and timeout remain visible for queue management and monitoring purposes.

Sources: src/Queue.php128-156

---

Encryption Requirements

Container Dependencies

For encryption to work, the following conditions must be met:

Diagram: Encrypter Service Resolution

Important: If the Encrypter service is not registered in the container, the job will be serialized without encryption, even if it implements ShouldBeEncrypted. This is a graceful degradation to prevent application crashes, but it means sensitive data will not be protected.

Configuration Requirements

The Encrypter service requires proper configuration in the framework:

1. Encryption key must be set in the application configuration
2. Encrypter service must be registered in the dependency injection container
3. The cipher algorithm should be configured (typically AES-256-CBC)

Sources: src/Queue.php146-148

---

Decryption Process

When a worker processes an encrypted job:

Diagram: Job Decryption During Processing

The decryption is handled automatically by the CallQueuedHandler class (referenced in the payload's job field at src/Queue.php133). The handler:

1. Retrieves the encrypted command from the payload
2. Detects that it's encrypted (not a serialized PHP object)
3. Uses the Encrypter service to decrypt it
4. Unserializes the decrypted string to restore the job object
5. Executes the job's handle() method

This process is completely transparent to the job implementation.

Sources: src/Queue.php133 src/Queue.php146-148

---

Security Considerations

What Gets Encrypted

Data Type	Encrypted	Reason
Job properties	✓ Yes	Contains sensitive data
Constructor arguments	✓ Yes	Part of job object
Job class name	✗ No	Needed for routing and monitoring
Queue name	✗ No	Needed for worker routing
Metadata (tries, timeout)	✗ No	Needed for queue management
Job UUID	✗ No	Needed for tracking

Protection Scope

The encryption protects against:

• Unauthorized database access: Data at rest in database queues is encrypted
• Redis dump file exposure: Encrypted data in Redis snapshots
• Backup exposure: Queue backups contain encrypted payloads
• Queue storage inspection: Administrators cannot read job contents

The encryption does NOT protect against:

• Active worker process inspection: Jobs are decrypted in memory during processing
• Application code access: Any code with container access can decrypt
• Logging: If job data is logged during execution, it will be visible

Best Practices

1. Selective Encryption: Only encrypt jobs with truly sensitive data to minimize performance overhead
2. Key Rotation: Regularly rotate the encryption key, but ensure old jobs can still be processed
3. Secure Key Storage: Store encryption keys securely (environment variables, key management service)
4. Audit Logging: Log when encrypted jobs are dispatched and processed for security auditing
5. Minimize Sensitive Data: Consider passing IDs instead of full sensitive objects when possible

Sources: src/Queue.php128-156 src/Queue.php221-228

---

Performance Impact

Encryption Overhead

Diagram: Processing Steps Comparison

The encryption adds:

• CPU overhead: Encryption/decryption computation
• Payload size increase: Encrypted data is typically larger than serialized data
• Latency: Additional processing time during dispatch and execution

Typical Impact:

• Dispatch time: +1-5ms per job (depending on job size)
• Storage size: +20-40% (due to encryption padding and encoding)
• Processing time: +1-5ms per job for decryption

For most applications, this overhead is negligible compared to the actual job processing time.

---

Integration with Queue Drivers

All queue drivers support encryption transparently:

Driver	Encryption Support	Storage Location
SyncQueue	✓ Supported	In-memory (never persisted)
CoroutineQueue	✓ Supported	In-memory channels
DatabaseQueue	✓ Supported	Database payload column
RedisQueue	✓ Supported	Redis strings/lists
BeanstalkdQueue	✓ Supported	Beanstalkd job body
SqsQueue	✓ Supported	SQS message body

The encryption is applied at the Queue base class level (src/Queue.php146-148), so all drivers inherit this functionality without driver-specific implementation.

Sources: src/Queue.php28-404

---

Example Use Cases

Processing Credit Card Payments

Handling Personal Identifiable Information (PII)

API Token Management

---

Summary

The job encryption feature provides transparent, automatic encryption for sensitive job payloads with minimal configuration. Key points:

• Implementation: Add the ShouldBeEncrypted interface or $shouldBeEncrypted property
• Mechanism: Jobs are serialized, encrypted, and stored; decrypted automatically during processing
• Requirements: Encrypter service must be registered in the container
• Scope: Protects data at rest in queue storage, not data in transit or during execution
• Performance: Minimal overhead (1-5ms per job) for significantly improved security
• Compatibility: Works with all queue drivers transparently

Sources: src/Queue.php15-16 src/Queue.php128-156 src/Queue.php221-228