feat: DSSE signing extension

[xibz]

Proposed Changes

feat: Add DSSE-based cryptographic signing for CloudEvents verification

Implements verifiable CloudEvents using DSSE (Dead Simple Signing Envelope) to ensure event authenticity and integrity across untrusted transport layers.

Key features:

• Sign CloudEvents with DSSE v1.0.2 protocol using SHA256 digests
• Transport verification material in 'dssematerial' extension attribute
• Support for binary, structured, and batch CloudEvent modes
• Backward compatible - unsigned events still work, consumers can ignore signatures (but highly inadvisable)

Technical approach:

• Creates SHA256 digest chain of all context attributes and event data
• Wraps digest in DSSE envelope with Base64 encoding
• Verifies by recomputing digests and comparing against signed payload
• Returns only verified data to consumers (strips unverified extensions)

This enables cryptographic proof that events:

1. Were produced by the claimed source (authenticity)
2. Were not modified in transit (integrity)

Does NOT address: event ordering, completeness, replay attacks, or confidentiality

Fixes #1302

Release Note

[duglin]

please wrap all files at 80 chars

[duglin]

s/proposal/extension/

let's be optimistic :-)

[duglin]

remove the " in" at the end.

[duglin]

the "wrong order" problem is mentioned in each of the 3 above sentences... kind of repetitive. I think just once is enough.

[duglin]

Kind of a tease to imply there are solutione so for this. I would recommend mentioning at least one solution (if one exists), or if none, then just say this problem is "out of scope of this specification"

[duglin]

is "signature replays" a "security" phrase? I wonder if everyone will know what's being said here. I'm not sure I do :-) Is it saying "we don't guarantee that replays will look the same", or is it saying "different events with the same id/souce might look the same even if other data is different" ? Or something else?

[duglin]

s/proposal/extension/

[duglin]

The following design constraints are defined:

remove "We have set"

[duglin]

s/can consumer/can consume/

[duglin]

I wonder if it's clear that just because a producer adds the extra verifiable stuff to the CE, the consumer is not required to do anything with it or even know what those extensions mean? Could just be me.

[duglin]

This paragraph, and the pict, are good but it feels a bit awkward to me.

I think it needs to either say:

• that this SDK usage is an example of how the end-to-end flow might look, just for the sake of understanding what the extension is doing
• or move this down into the "examples" section

My concern with how this is presented is that it comes across like it requires an SDK and, at least initially, this doc needs to present the "on the wire" changes that this extension is defining. Meaning, what new CE attributes are defined. How they get into the CE is an implementation detail - and an SDK is one option.

IOW, I think just starting this section with the "The verification material is transported..." sentence below is good enough.

[duglin]

You may want to follow the pattern in other extensions of having an "Attributes" section - see: https://github.com/cloudevents/spec/blob/52387e31cc41688ba1ce56ec8f040554d3517592/cloudevents/extensions/authcontext.md#attributes

[duglin]

I think this is REQUIRED not OPTIONAL.

Let's add in a "Notational Conventions" section like: https://github.com/cloudevents/spec/blob/52387e31cc41688ba1ce56ec8f040554d3517592/cloudevents/extensions/authcontext.md#notational-conventions then you'll see that the last paragraph in there explains why it's REQUIRED not OPTIONAL.

[duglin]

"looks something like" isn't precise enough. Are all of those 5 fields required? If so, then say "MUST adhere to the following form". If the fields can change based on the mechanism used to do the verifying then we'll need to be more creative, so let's discuss because across all mechanisms/formats there MUST be at least one consistent field (payloadType I assume) that people can rely upon to disambiguating them.

[duglin]

Given that extensions are similar to optional spec-defined attributes, should this include extensions?

[duglin]

the JS SDK adds it to outgoing or to incoming CEs? If incoming I think that's a bug. If outgoing, I'm not sure we need to say anything at all since I think the proposal still works, doesn't it?

[xibz]

Ah it's only outgoing, so it just needs to be included in the signature computation.

[duglin]

Why can't we just treat the timestamp as a string? I don't think the exact format (or precision) should impact the verification, should it?

[duglin]

Why not treat it as an opaque string? Then we don't need to worry what TZ it uses.

[xibz]

The time normalization to Zulu is intentional and necessary. Since verification happens after deserialization on the CloudEvent object (not on raw JSON), we need to handle cases where intermediaries deserialize and reserialize events. We did this to ensure flexibility of WHEN verification could happen. Noting @jskeet comment from a couple weeks ago about needing to verify at the raw incoming bytes of the HTTP request, this now can allow for you to deserialize then individually compute the SHA256 because the fields are explicit in which order and say HOW time should be formatted.

But will update point 8 to help clarify

[duglin]

I'm still not following.

"time" is optional and serialized as a string, which means it can't be required to be there for the signing or verification process. So, MUST we touch it at all if present? Why not just pass it along like any other attribute. I would be bothered if my middleware changed my data on me.

[xibz]

We're not changing the time data - we're normalizing it ONLY for signature computation, not in the event itself. (AI helping me with an example, but the last paragraph is the important bit) :)

The event keeps whatever time format it has: 2020-06-18T17:24:53+02:00

But when computing the signature hash, we normalize to Zulu: 2020-06-18T17:24:53Z

This is necessary because:

1. Producer sends "time": "2020-06-18T17:24:53+02:00"
2. Middleware deserializes/reserializes as "time": "2020-06-18T15:24:53Z" (same moment, different string)
3. Consumer receives different string representation

Without normalization for signing:

• Producer signs SHA256("2020-06-18T17:24:53+02:00")
• Consumer verifies SHA256("2020-06-18T15:24:53Z")
• Verification fails even though it's the same timestamp

With normalization:

• Producer signs SHA256("2020-06-18T17:24:53Z") [normalized]
• Consumer verifies SHA256("2020-06-18T17:24:53Z") [normalized]
• Verification succeeds

The actual time attribute in the event is never modified - only the signature computation normalizes it. Think of it like Unicode normalization for signatures - you normalize for comparison but don't change the actual data.

Mind you without this, you lose the flexibility on where verification can happen. Also this assumes you are marshaling and unmarshaling into a structure that uses some time object. If you it is modeled as string, no issues, but generally SDKs model time as some time object.

[duglin]

ok that helps thanks. Then I think the note you have about times only having "second precision" needs to be a normative requirement and not a note otherwise nanoseconds could mess with it, no?

[duglin]

Meaning, add the note text to this bullet with a MUST ??

[duglin]

Not sure what this "note" is trying to say. I think just making each reference to RFC3339 a hyperlink is sufficient.
Same for base64 in the previous bullet

[duglin]

I might have missed it, but how does this proposal handle nested verifications? Eg. middleware adds new attributes, verifies and then removes it.

sender (add verification stuff) -> middleware sender (adds attrs (or not), adds new verify stuff) -> middleware receiver (verifies, removes middleware-specific verify stuff)-> ultimate receiver (verifies stuff).

Related, I think we need to support extension attributes - either a select list or all of them. I think "all" would be easier then we don't need to pass along a list of attributes that are part of the verification. I think it would also simplify the algorithm down to:

• loop over all attributes (in alphabetical order)
  • do the SHA256 stuff above on each one - probably using NAME:VALUE instead of just VALUE

Then there's no special rules for each attribute and if new attributes are added it'll cause the verify to fail - as it should.

[xibz]

Nested verification/attestation chains solve a different problem than what this proposal addresses. This extension is specifically for verifying event authenticity and integrity from producer to consumer.

What you're describing is about building an audit trail of modifications or proving a chain of custody. That's a valuable but completely different use case.

If there's need for modification audit trails or nested attestations, that should be a separate extension proposal. Mixing the two would complicate both use cases.

Also there exists formats like Chain Signatures (Zhou, Redline, 2005) or Git's commit signature chains that could inspire the next proposal that handle chaining of signatures.

[duglin]

No, this isn't about audits or chains... it's about situations where there are environments where messages are sent thru middleware that will sign/verify messages with out the apps on either side knowing about it. Which means if there are multiple layers of that middleware then the design of this needs to support the idea of signing a message that has already been signed. And, of course, this will then also deal with cases where the middleware adds new attributes to the messages that need to be signed

[xibz]

What you're describing IS an attestation chain use case, even if the applications aren't aware of it. The middleware layers are creating a chain of signatures with different scopes.

[duglin]

probably a terminology difference, but they're doing it w/o any real knowledge of someone else already doing it too - beyond perhaps whatever mechanism we have to keep them in order. Both the latest middleware and the previous middleware should do their jobs of signing and verifying (and removing their signatures) without knowledge of the other layers. What your're suggesting, I think, is that there can only ever be one signing middleware in the picture and we can never add attributes to an existing CE that's signed. Seems kind of restrictive.