Signing Messages in Symfony 7.4: A Deep Dive

Security in distributed systems is often a game of layers. We secure the transport (TLS), we secure the infrastructure (firewalls, VPCs), and we secure the application access (Voters, ACLs). But when it comes to the Messenger component — the beating heart of many modern Symfony applications — there has always been a subtle gap. Once a message leaves your producer and sits in a queue (Redis, RabbitMQ, SQS), it is essentially a serialized string payload. If an attacker gains write access to your transport, they can inject malicious messages, modify payloads, or replay old commands. Messenger In Symfony 7.4, the Messenger component introduces a native, robust mechanism to close this gap: Message Signing. Symfony 7.4 Message Signing This feature ensures that every message processed by your handlers was indeed produced by your application and has not been tampered with in transit. It brings cryptographic integrity to your message bus with the elegance and developer experience you expect from Symfony. In this deep dive, we will explore why this matters, how the new signing architecture works, and provide a complete implementation guide using the libraries available today to replicate this “future” standard. Trust in a Zero-Trust World Imagine a standard e-commerce architecture: Checkout Service dispatches a ProcessPayment message. The message travels to RabbitMQ. Payment Worker consumes the message and charges the card. Checkout Service dispatches a ProcessPayment message. Checkout Service ProcessPayment The message travels to RabbitMQ. Payment Worker consumes the message and charges the card. Payment Worker If an attacker compromises the RabbitMQ instance, they could manually publish a ProcessPayment message for a fake order or modify the amount of a legitimate order. The worker, blindly trusting the serializer, would hydrate the object and execute the handler. ProcessPayment Prior to Symfony 7.4, solving this required writing custom Middleware to wrap messages in a “Signed Envelope,” calculating HMACs, and managing serialization groups carefully. It was boilerplate-heavy and prone to implementation errors (like signing the object before serialization rather than the serialized payload). before The Symfony 7.4 Solution The new Signing capability in Symfony 7.4 integrates directly into the Middleware and Serializer chain. It introduces a mechanism to control integrity requirements on a per-handler or per-message basis. The core philosophy is simple: Sign the serialized payload, not the object. Sign the serialized payload, not the object. The Dispatch Flow: The Dispatch Flow: The serializer converts the object to JSON/XML. The signing mechanism takes the serialized body. It computes a cryptographic hash (HMAC) using your application’s kernel.secret (or a dedicated signing key). It attaches the signature and the algorithm to the message headers (Stamps). The serializer converts the object to JSON/XML. The signing mechanism takes the serialized body. It computes a cryptographic hash (HMAC) using your application’s kernel.secret (or a dedicated signing key). kernel.secret It attaches the signature and the algorithm to the message headers (Stamps). The Consumption Flow: The Consumption Flow: The mechanism reads the body and the signature header from the incoming envelope. It re-computes the hash of the body. If the hashes don’t match, it throws an InvalidMessageSignatureException before the serializer even attempts to hydrate the object. The mechanism reads the body and the signature header from the incoming envelope. It re-computes the hash of the body. If the hashes don’t match, it throws an InvalidMessageSignatureException before the serializer even attempts to hydrate the object. InvalidMessageSignatureException before Implementation Guide Since we are acting as early adopters (or polyfilling this for current versions like 7.1/7.2), we will build this feature using the standard symfony/messenger and symfony/serializer libraries. This implementation mirrors the functionality described in the Symfony 7.4 release notes. symfony/messenger symfony/serializer 1. Prerequisites & Installation Ensure you have the Messenger component installed. composer require symfony/messenger symfony/serializer symfony/uid composer require symfony/messenger symfony/serializer symfony/uid 2. The Signature Stamp The metadata for the signature needs to travel with the message. In Messenger, we use Stamps. We need a stamp to hold the signature hash and the algorithm used. Stamps // src/Messenger/Stamp/SignatureStamp.php namespace App\Messenger\Stamp; use Symfony\Component\Messenger\Stamp\StampInterface; final class SignatureStamp implements StampInterface { public function __construct( private string $signature, private string $algorithm = 'sha256' ) {} public function getSignature(): string { return $this->signature; } public function getAlgorithm(): string { return $this->algorithm; } } // src/Messenger/Stamp/SignatureStamp.php namespace App\Messenger\Stamp; use Symfony\Component\Messenger\Stamp\StampInterface; final class SignatureStamp implements StampInterface { public function __construct( private string $signature, private string $algorithm = 'sha256' ) {} public function getSignature(): string { return $this->signature; } public function getAlgorithm(): string { return $this->algorithm; } } 3. The Signing Service We need a dedicated service to handle the cryptographic heavy lifting. This keeps our middleware clean and allows us to rotate keys or change algorithms easily. We will use PHP’s native hash_hmac for this example, utilizing the kernel.secret as the key. hash_hmac kernel.secret // src/Service/MessageSigner.php namespace App\Service; use Symfony\Component\DependencyInjection\Attribute\Autowire; class MessageSigner { public function __construct( #[Autowire('%kernel.secret%')] private string $secret ) {} public function sign(string $messageBody): string { return hash_hmac('sha256', $messageBody, $this->secret); } public function verify(string $messageBody, string $signature): bool { $expected = $this->sign($messageBody); return hash_equals($expected, $signature); } } // src/Service/MessageSigner.php namespace App\Service; use Symfony\Component\DependencyInjection\Attribute\Autowire; class MessageSigner { public function __construct( #[Autowire('%kernel.secret%')] private string $secret ) {} public function sign(string $messageBody): string { return hash_hmac('sha256', $messageBody, $this->secret); } public function verify(string $messageBody, string $signature): bool { $expected = $this->sign($messageBody); return hash_equals($expected, $signature); } } 4. The Signing Serializer Decorator This is the core of the feature. To ensure we are signing the exact string that enters the transport, we decorate the Serializer. This guarantees that any modification to the JSON string in the queue will break the signature. // src/Serializer/SignedMessageSerializer.php namespace App\Serializer; use App\Messenger\Stamp\SignatureStamp; use App\Service\MessageSigner; use Symfony\Component\Messenger\Envelope; use Symfony\Component\Messenger\Exception\MessageDecodingFailedException; use Symfony\Component\Messenger\Transport\Serialization\SerializerInterface; class SignedMessageSerializer implements SerializerInterface { private const HEADER_SIGNATURE = 'X-Message-Signature'; public function __construct( private SerializerInterface $inner, private MessageSigner $signer ) {} public function decode(array $encodedEnvelope): Envelope { // 1. Check for signature header if (!isset($encodedEnvelope['headers'][self::HEADER_SIGNATURE])) { // If no signature is present, we pass it to the inner serializer. // We will enforce the requirement for a signature later in Middleware. return $this->inner->decode($encodedEnvelope); } $signature = $encodedEnvelope['headers'][self::HEADER_SIGNATURE]; $body = $encodedEnvelope['body']; // 2. Verify Integrity if (!$this->signer->verify($body, $signature)) { // Throwing here prevents object hydration, blocking the attack immediately. throw new MessageDecodingFailedException('Invalid message signature. The message may have been tampered with.'); } // 3. Decode normally $envelope = $this->inner->decode($encodedEnvelope); // 4. Add the stamp so handlers know it was verified return $envelope->with(new SignatureStamp($signature)); } public function encode(Envelope $envelope): array { // 1. Encode normally $encoded = $this->inner->encode($envelope); // 2. Compute signature of the BODY $signature = $this->signer->sign($encoded['body']); // 3. Add to headers $encoded['headers'][self::HEADER_SIGNATURE] = $signature; return $encoded; } } // src/Serializer/SignedMessageSerializer.php namespace App\Serializer; use App\Messenger\Stamp\SignatureStamp; use App\Service\MessageSigner; use Symfony\Component\Messenger\Envelope; use Symfony\Component\Messenger\Exception\MessageDecodingFailedException; use Symfony\Component\Messenger\Transport\Serialization\SerializerInterface; class SignedMessageSerializer implements SerializerInterface { private const HEADER_SIGNATURE = 'X-Message-Signature'; public function __construct( private SerializerInterface $inner, private MessageSigner $signer ) {} public function decode(array $encodedEnvelope): Envelope { // 1. Check for signature header if (!isset($encodedEnvelope['headers'][self::HEADER_SIGNATURE])) { // If no signature is present, we pass it to the inner serializer. // We will enforce the requirement for a signature later in Middleware. return $this->inner->decode($encodedEnvelope); } $signature = $encodedEnvelope['headers'][self::HEADER_SIGNATURE]; $body = $encodedEnvelope['body']; // 2. Verify Integrity if (!$this->signer->verify($body, $signature)) { // Throwing here prevents object hydration, blocking the attack immediately. throw new MessageDecodingFailedException('Invalid message signature. The message may have been tampered with.'); } // 3. Decode normally $envelope = $this->inner->decode($encodedEnvelope); // 4. Add the stamp so handlers know it was verified return $envelope->with(new SignatureStamp($signature)); } public function encode(Envelope $envelope): array { // 1. Encode normally $encoded = $this->inner->encode($envelope); // 2. Compute signature of the BODY $signature = $this->signer->sign($encoded['body']); // 3. Add to headers $encoded['headers'][self::HEADER_SIGNATURE] = $signature; return $encoded; } } 5. Configuration We need to decorate the default messenger serializer. # config/services.yaml services: App\Serializer\SignedMessageSerializer: decorates: 'messenger.transport.native_php_serializer' # Check your messenger config for the ID used arguments: $inner: '@.inner' # config/services.yaml services: App\Serializer\SignedMessageSerializer: decorates: 'messenger.transport.native_php_serializer' # Check your messenger config for the ID used arguments: $inner: '@.inner' If you are using the default Symfony serializer, the ID is usually messenger.transport.symfony_serializer. You might need to alias this in your messenger.yaml transport config to point to your new signed serializer. messenger.transport.symfony_serializer messenger.yaml # config/packages/messenger.yaml framework: messenger: serializer: default_serializer: App\Serializer\SignedMessageSerializer transports: async: dsn: '%env(MESSENGER_TRANSPORT_DSN)%' serializer: App\Serializer\SignedMessageSerializer # config/packages/messenger.yaml framework: messenger: serializer: default_serializer: App\Serializer\SignedMessageSerializer transports: async: dsn: '%env(MESSENGER_TRANSPORT_DSN)%' serializer: App\Serializer\SignedMessageSerializer Usage: The #[Signed] Attribute #[Signed] In the Symfony 7.4 spirit, we want to control this with Attributes. We might want to enforce that specific handlers only accept signed messages, allowing for a gradual rollout. specific // src/Attribute/Signed.php namespace App\Attribute; use Attribute; #[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)] class Signed { } // src/Attribute/Signed.php namespace App\Attribute; use Attribute; #[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)] class Signed { } Now, we need a Middleware to enforce this attribute. Even though the Serializer handles the verification, we need to ensure that a handler rejects messages that arrived without a signature at all. verification rejects // src/Middleware/EnforceSignatureMiddleware.php namespace App\Middleware; use App\Attribute\Signed; use App\Messenger\Stamp\SignatureStamp; use Symfony\Component\Messenger\Envelope; use Symfony\Component\Messenger\Middleware\MiddlewareInterface; use Symfony\Component\Messenger\Middleware\StackInterface; use Symfony\Component\Messenger\Exception\UnrecoverableMessageHandlingException; class EnforceSignatureMiddleware implements MiddlewareInterface { public function handle(Envelope $envelope, StackInterface $stack): Envelope { $message = $envelope->getMessage(); $reflection = new \ReflectionClass($message); // Check if the message class has the #[Signed] attribute if ($reflection->getAttributes(Signed::class)) { $stamp = $envelope->last(SignatureStamp::class); if (!$stamp) { throw new UnrecoverableMessageHandlingException(sprintf( 'Message of type "%s" requires a signature, but none was found.', get_class($message) )); } } return $stack->next()->handle($envelope, $stack); } } // src/Middleware/EnforceSignatureMiddleware.php namespace App\Middleware; use App\Attribute\Signed; use App\Messenger\Stamp\SignatureStamp; use Symfony\Component\Messenger\Envelope; use Symfony\Component\Messenger\Middleware\MiddlewareInterface; use Symfony\Component\Messenger\Middleware\StackInterface; use Symfony\Component\Messenger\Exception\UnrecoverableMessageHandlingException; class EnforceSignatureMiddleware implements MiddlewareInterface { public function handle(Envelope $envelope, StackInterface $stack): Envelope { $message = $envelope->getMessage(); $reflection = new \ReflectionClass($message); // Check if the message class has the #[Signed] attribute if ($reflection->getAttributes(Signed::class)) { $stamp = $envelope->last(SignatureStamp::class); if (!$stamp) { throw new UnrecoverableMessageHandlingException(sprintf( 'Message of type "%s" requires a signature, but none was found.', get_class($message) )); } } return $stack->next()->handle($envelope, $stack); } } Register the middleware in messenger.yaml: messenger.yaml framework: messenger: buses: default: middleware: - App\Middleware\EnforceSignatureMiddleware framework: messenger: buses: default: middleware: - App\Middleware\EnforceSignatureMiddleware Real-World Example Let’s look at how we use this in a Payment processing scenario. The Message We mark the message as requiring a signature. // src/Message/ProcessPayment.php namespace App\Message; use App\Attribute\Signed; #[Signed] class ProcessPayment { public function __construct( public int $orderId, public float $amount, public string $currency ) {} } // src/Message/ProcessPayment.php namespace App\Message; use App\Attribute\Signed; #[Signed] class ProcessPayment { public function __construct( public int $orderId, public float $amount, public string $currency ) {} } The Handler The handler doesn’t need to know about the cryptography. It just does its job. If the code reaches here, we know the message is authentic. // src/MessageHandler/PaymentHandler.php namespace App\MessageHandler; use App\Message\ProcessPayment; use Symfony\Component\Messenger\Attribute\AsMessageHandler; use Psr\Log\LoggerInterface; #[AsMessageHandler] class PaymentHandler { public function __construct(private LoggerInterface $logger) {} public function __invoke(ProcessPayment $message): void { // This code will ONLY execute if the message had a valid HMAC signature. $this->logger->info('Processing secure payment', [ 'order' => $message->orderId, 'amount' => $message->amount ]); // ... Payment logic } } // src/MessageHandler/PaymentHandler.php namespace App\MessageHandler; use App\Message\ProcessPayment; use Symfony\Component\Messenger\Attribute\AsMessageHandler; use Psr\Log\LoggerInterface; #[AsMessageHandler] class PaymentHandler { public function __construct(private LoggerInterface $logger) {} public function __invoke(ProcessPayment $message): void { // This code will ONLY execute if the message had a valid HMAC signature. $this->logger->info('Processing secure payment', [ 'order' => $message->orderId, 'amount' => $message->amount ]); // ... Payment logic } } Verification Steps To ensure your implementation works, you should verify both success and failure scenarios. 1. Verify Successful Signing Dispatch a message normally via the bus. // src/Controller/TestController.php #[Route('/test-sign')] public function test(MessageBusInterface $bus): Response { $bus->dispatch(new ProcessPayment(123, 99.99, 'USD')); return new Response('Message Dispatched'); } // src/Controller/TestController.php #[Route('/test-sign')] public function test(MessageBusInterface $bus): Response { $bus->dispatch(new ProcessPayment(123, 99.99, 'USD')); return new Response('Message Dispatched'); } Check: Inspect your Transport (e.g., Doctrine table messenger_messages or Redis). You should see the headers column (or map) contains: Check: messenger_messages headers { "X-Message-Signature": "a1b2c3d4...", "type": "App\\Message\\ProcessPayment" } { "X-Message-Signature": "a1b2c3d4...", "type": "App\\Message\\ProcessPayment" } 2. Verify Tamper Detection This is the critical test. Manually modify the body of a queued message in your database or Redis. Dispatch a message. Pause your worker (messenger:consume). Go to your database/redis. Find the message. Change the amount in the body JSON from 99.99 to 10.00. Start the worker. Dispatch a message. Pause your worker (messenger:consume). messenger:consume Go to your database/redis. Find the message. Change the amount in the body JSON from 99.99 to 10.00. amount body 99.99 10.00 Start the worker. Expected Result: Expected Result: The worker should throw a MessageDecodingFailedException. The message should be rejected (and sent to the failure transport, if configured). MessageDecodingFailedException php bin/console messenger:consume async -vv php bin/console messenger:consume async -vv Output: [Critical] Error thrown while handling message ... MessageDecodingFailedException: Invalid message signature. The message may have been tampered with. [Critical] Error thrown while handling message ... MessageDecodingFailedException: Invalid message signature. The message may have been tampered with. Advanced: Algorithm Agility & Rotation The implementation above uses sha256 and a single shared secret. In a production environment, you might want Key Rotation. sha256 You can enhance the MessageSigner to support a keys array: MessageSigner keys # config/services.yaml parameters: messenger.signing_keys: - '%env(CURRENT_SIGNING_KEY)%' - '%env(OLD_SIGNING_KEY)%' # Allow verifying with old key during rotation # config/services.yaml parameters: messenger.signing_keys: - '%env(CURRENT_SIGNING_KEY)%' - '%env(OLD_SIGNING_KEY)%' # Allow verifying with old key during rotation Update the verify method to loop through valid keys: verify public function verify(string $messageBody, string $signature): bool { foreach ($this->keys as $key) { if (hash_equals(hash_hmac('sha256', $messageBody, $key), $signature)) { return true; } } return false; } public function verify(string $messageBody, string $signature): bool { foreach ($this->keys as $key) { if (hash_equals(hash_hmac('sha256', $messageBody, $key), $signature)) { return true; } } return false; } Conclusion Security is rarely about a single silver bullet; it is about reducing surface area and removing assumptions. By implementing message signing, we remove the dangerous assumption that our transport layer is inviolable. We transform our consumers from blind executors into skeptical gatekeepers, ensuring that every command processed carries the cryptographic seal of approval from your application kernel. While Symfony 7.4 will bring native, streamlined support for this pattern, the implementation strategies outlined above prove that you don’t need to wait to secure your infrastructure. The tools — Serializer, Messenger, and Middleware — are already in your hands. The only missing piece was the pattern, and now you have it. As distributed systems and microservices become the standard, the integrity of the messages flowing between them becomes just as critical as the code itself. Don’t leave your queues vulnerable to injection or tampering. Let’s Harden Your Architecture Implementing cryptographic security in high-throughput systems requires precision. If you are looking to audit your current Symfony Messenger architecture or need assistance implementing Zero Trust patterns in your distributed application, I would love to hear from you. https://www.linkedin.com/in/matthew-mochalkin/ to discuss how we can secure your Symfony application’s future, one message at a time. https://www.linkedin.com/in/matthew-mochalkin/ https://www.linkedin.com/in/matthew-mochalkin/ https://www.linkedin.com/in/matthew-mochalkin/