Skip to content

Event Signatures and Validation

This guide outlines best practices for using event signatures in EventSourcingDB. You'll learn when and why to sign events, how to handle verification results, what to avoid when working with signatures, and how to manage signing keys safely over time.

Why Sign Events?

EventSourcingDB signs each event dynamically when returning it from the API – if started with a signing key. These signatures provide cryptographic proof that the event originates from a trusted instance of EventSourcingDB and has not been tampered with.

This is especially important in distributed environments where events may cross system or organizational boundaries. By validating the signature, downstream systems can ensure both the integrity and the authenticity of events – a crucial requirement in regulated domains, multi-party workflows, and security-sensitive architectures.

While hashes already protect against content changes, they say nothing about where the event came from. Signatures close this gap by making the origin verifiable.

When to Validate Signatures?

Signature validation is not always necessary, but it becomes essential when:

  • Events are received from systems outside your trust boundary.
  • Compliance or auditing demands proof of origin.
  • You want to enforce additional checks at the boundaries of your system.
  • Events are cached, delayed, or routed through untrusted intermediaries.

In such cases, validating signatures can prevent unauthorized data injection, detect tampering attempts, and strengthen overall system robustness.

In internal components – such as projections or read model builders – hash validation alone is often sufficient. But for API gateways, ingestion pipelines, or audit services, signature checks can be a vital security measure.

Integrity vs. Authenticity

Hashes prove that the event content has not changed. Signatures prove that the event was generated by a trusted source.

Handling Verification Results

EventSourcingDB includes a hash field in every event and a signature field if signing is enabled. Both values can be used to validate the event at the time of processing.

How this validation is performed depends on your application:

  • If the hash is invalid, the event has been modified or corrupted and should never be accepted.
  • If the signature is invalid, the event may have been spoofed or the signing key has changed.
  • If the signature is missing, and your policy requires one, the event should be rejected.

Unlike the hash, the signature is not persistent and depends on the currently active signing key. This means that signature validation must be done against a freshly fetched event, especially after key rotations.

Where to Perform Validation

Hash validation is lightweight and can be used everywhere – including in projections or read model builders. Signature validation is typically reserved for trust boundaries, such as ingestion pipelines, audit services, or API gateways.

How to Validate Events

See Verifying Event Signatures for step-by-step instructions on how to validate the hash and signature using standard cryptographic tools.

Avoiding Common Pitfalls

One of the most frequent mistakes when using signatures is to cache them long-term. Because EventSourcingDB generates signatures on the fly using the currently active signing key, any key rotation will cause previously cached signatures to become invalid.

To avoid this:

  • Never persist or distribute signatures as permanent values.
  • Always re-fetch events before validating them, especially after a key change.

Another common issue is to skip validation entirely at ingestion time. When integrating events from external systems or asynchronous channels, always verify both the hash and – if configured – the signature.

Also, make sure to handle null signatures correctly. A missing signature does not necessarily indicate an error; it may simply mean that signing was not enabled at the time. Only treat it as a problem if your application explicitly requires signed events.

Cached Signatures Are Not Reliable

If your application caches event payloads or responses, do not assume that the signature remains valid. Always verify the hash and signature at the time of processing using a fresh copy from the database.

Best Practices for Key Management

Signing events introduces the responsibility of managing signing keys over time. To minimize disruption and maintain verifiability:

  • Use strong, unique keys, and store them securely – ideally in an encrypted vault.
  • Document when keys are rotated, and coordinate deployments accordingly.
  • Avoid frequent key changes, unless mandated by compliance requirements.
  • Do not rely on signature persistence. Re-fetch events to obtain up-to-date signatures.
  • Keep the private key confidential. Only the EventSourcingDB instance should have access to it.

By managing keys deliberately and understanding the ephemeral nature of signatures in EventSourcingDB, you can build secure and trustworthy event-driven systems – without introducing unnecessary complexity or risk.