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]

Can you rebase? These are not part of your PR

[duglin]

extra line

[duglin]

Please wrap entire doc at 80 chars

[duglin]

So, if there are CE extensions but they're not verified, they're silently dropped?
Is this what we want instead of rejecting the event? I'm wondering if the presence of extra stuff is sign that someone is trying to mess with things and we need to play it safe.

[jskeet]

I'm concerned about this too. I'd far rather be able to keep everything, but make it easy to determine which extensions were signed and which weren't.

[duglin]

Some errors from the tooling:

cloudevents/extensions/verifiability.md: cloudevents/extensions/verifiability.md does not contain '#protocol-1' segment
cloudevents/extensions/verifiability.md: line 141: 'required' MUST be capitalized ('REQUIRED')
cloudevents/extensions/verifiability.md: line 141: 'optional' MUST be capitalized ('OPTIONAL')
cloudevents/extensions/verifiability.md: line 281: 'Optional' MUST be capitalized ('OPTIONAL')
cloudevents/extensions/verifiability.md: line 416: 'should' MUST be capitalized ('SHOULD')
cloudevents/extensions/verifiability.md: line 440: 'should' MUST be capitalized ('SHOULD')
cloudevents/extensions/verifiability.md: line 473: 'must' MUST be capitalized ('MUST')
cloudevents/extensions/verifiability.md: line 482: 'must' MUST be capitalized ('MUST')
cloudevents/extensions/verifiability.md: title ('# extension: Verifiable CloudEvents with DSSE') does not match the title of cloudevents/languages/he/extensions/verifiability.md ('# Verifiable CloudEvents with DSSE')
cloudevents/extensions/verifiability.md: title ('# extension: Verifiable CloudEvents with DSSE') does not match the title of cloudevents/languages/zh-CN/extensions/verifiability.md ('# Verifiable CloudEvents with DSSE')

You may want to squash and rebase

[duglin]

We agreed to try to vote on this next week so:

• @xibz please try to address all open comments and CI issues
• everyone else PLEASE review and comment ASAP so @xibz can respond with enough time for folks to review his responses before next week's call

[jskeet]

I'm not sure what "cryptographic agility" is - is that a term most folks in the relevant audience would understand? (It's entirely possible.)

[jskeet]

Can we capitalize these for consistency with VERIFICATION_MATERIAL, KEY_ID and SIGNATURE? Aside from anything else, that makes it easier to tell that they're not expected to be attribute names.

[jskeet]

It's not clear to me why this is a string and specified as base64. If the intention is to transport arbitrary bytes, I think it should be of type Binary, which would happen to be base64-encoded in the JSON CloudEvents format, but not necessarily in other formats.

I think it would be better to make it Binary, and explicitly state that logically it's a string, but binary is used to avoid the restrictions on the String type. Alternatively, would it be reasonable to put the JSON on a single line and have it as a string without any additional encoding? I suspect the only character disallowed in https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#type-system that causes a problem at the moment is for the line break.

[jskeet]

I think we need more clarity here. Effectively I'd suggest a whole separate section about how each type is hashed, and then use that for both the core and extension attributes.

(I'd also suggest that when hashing a binary value, there's no point in converting it to base64 first - likewise we could use simple encodings for Integer and Boolean values.)

[jskeet]

This is where I think we need to be clear that the verifier must know the types of the extension attributes in order to verify them. The overall result of verification could be:

• Verified both core and extensions
• Verified core, there were no signed extensions
• Verified code, can't verify extensions due to at least one extension attribute's type not being known
• Verification failed (one of the signatures doesn't match)

[jskeet]

I'm concerned about this too. I'd far rather be able to keep everything, but make it easy to determine which extensions were signed and which weren't.

[jskeet]

I've stopped reviewing at this point as I suspect changes above will affect the text below.

[jskeet]

Note either here or elsewhere that extension attributes with a known value but not a known type (which could happen in some SDK implementations if this is an event which has been received and is being propagated) cannot be signed.

[xibz]

@duglin @jskeet - I forgot an important commit T-T. i was so confused why you kept mentioning types because I was like "I thought that was in the proposal". Turns out I forgot to push that commit. Sorry about that :(

[jskeet]

I'm not sure what this means - there's no concept of an attribute which exists but isn't of a supported type.

If this is intended to mean that the signer knows the type of the attribute, that's slightly different. I think I'd probably talk about that separate from this bullet list though.

[jskeet]

Not sure what this list is intended for, but I think we can just remove the line (and move the period to the line above)

[xibz]

It's mostly cause security typically wants things to be VERY clear. No way to interpret anything.

[jskeet]

Hmm... this could be tricky. I've been focused on the representations of the attributes, but data is a whole other tricky story. What is the "raw byte representation" of an in-memory CloudEvent which has a JSON object as its data? If this is intended to be "the bytes that appear in the serialized form" then that gets us back to implementation difficulties.

(Historically, attributes have been relatively straightforward - we've had many, many discussions about the nature of data, particularly for event formats which can represents certain data types in a different way, e.g. where the data for a JSON-formatted event is itself a JSON object...)

[xibz]

This only applies to event.data, not to context attributes. Context attributes use semantic canonicalization (Option 3 from our email thread), which you described as having “really significant benefits: Signature doesn’t change based on format, Much simpler implementation than either 1 or 2”, and that’s what the spec implements for all typed attributes (UTF8(s) for strings, RFC3339(UTC(t)) for timestamps, etc.).

For event.data, raw bytes are unavoidable: there is no CE type system for event data, so we cannot apply semantic canonicalization. The note at lines 327–328 calls this out explicitly, any intermediary that reserializes event data (whitespace changes, key reordering) must re-sign. This is the same trade-off you acknowledged in the email when discussing Option 2: “That’s ‘only’ inefficient rather than particularly difficult, but it does mean that support for this extension needs to be built into every event formatter.” We avoided that for attributes via Option 3; for data there is no equivalent.

[jskeet]

Again, I'd separate out "here's how you hash a value" (on a per type basis) from the uses of it. That way you don't need any repetition, and key implementation details (e.g. how to hash a timestamp value) aren't buried in the list.

[jskeet]

A string value can't be hashed, as hashing is an operation on binary data. I suspect we want to say you hash the UTF-8-encoded form of the string.

[jskeet]

It's not RFC3339 which limits us to second precision - it's interoperability. We don't know what degree of precision any given consumer will use, so it's simplest to truncate to the second.

[xibz]

Good call out. I remember there's a timestamp RFC that is specifically second precisions, but I may be misremembering or blurring RFCs.

But good callout

[jskeet]

This comes back to what "the exact byte representation of the event data" is, and how tricky that could be for implementations...

[xibz]

Same answer as above

This applies only to event.data, not to context attributes. For context attributes the spec uses semantic canonicalization (Option 3 from our March 11 discussion), which you preferred precisely because it avoids the wire-bytes implementation pain you described: “often the bytes that were on the wire aren’t known by the time you’re dealing with the parsed representation... the JSON event formatter reads the whole body as a document. At that point, the original bytes on the wire have gone.”

For event.data we cannot apply the same trick, there is no CE type for data. Signing requires stable bytes, and the spec documents the consequence clearly (lines 327–328): intermediaries that reserialize data must resign. SDK authors should sign as close to the wire as possible. Happy to add a note in the spec making this explicit for SDK implementors.

[jskeet]

Right - sorry for missing this before. I think in many cases this may make implementation close to infeasible, unfortunately.

For example in https://github.com/cloudevents/sdk-csharp/blob/main/src/CloudNative.CloudEvents.SystemTextJson/JsonEventFormatter.cs#L138 (and similar event formatters) the first thing that's done is to read the event as a JSON document. At that point, we simply don't have the original bytes. So to read the wire data, we'd probably have to maintain our own very low-level JSON parser in order to get the raw bytes.

I hate to be a downer, but I think for at least a lot of languages, this will simply break any layered architecture of the SDK. It may be feasible in some other languages of course.

[xibz]

For event.data I want to acknowledge you raised this in our March email too, and at the time you said "That feels somewhat reasonable as a spec, but a real pain to implement in an SDK." We proceeded on that basis, and the spec documents the consequence clearly. So I dont think it was missed, per se.

On the C# SDK example: the formatter reading the whole JSON document before the raw bytes are available is a real constraint, but the solution is to capture the bytes during parsing rather than after. System.Text.Json exposes raw UTF-8 bytes for a value node via GetRawText() or an equivalent reader-level API, no custom low-level parser needed. The SDK would need to thread this through the signing path, which is additional work, but it's the same class of work any checksum/integrity system requires.

The alternative, defining a canonical serialization for event.data, would require specifying rules for every possible content type (JSON, XML, binary, protobuf, etc.), which is far out of scope. Raw bytes is the only content-type-agnostic option.

Producers typically sign before serialization where raw bytes are always available. For SDKs that receive-and-propagate, capturing bytes at the formatter layer is the right integration point. We can capture that in the spec if needed

[jskeet]

but the solution is to capture the bytes during parsing rather than after. System.Text.Json exposes raw UTF-8 bytes for a value node via GetRawText() or an equivalent reader-level API, no custom low-level parser needed.

I may have chosen a bad example - it's possible that we can do this for System.Text.Json without very many changes. I think I'd need to check it really carefully for every format - for example, in protobuf it may be feasible due to parsing effectively preserving everything we need.

At the very least, I think it'll mean work on a "per language, per format" basis, and in a way which makes the implementation significantly more complex. That may well be unavoidable, and I acknowledge that there's probably no better approach - but with our current state of SDKs being "it's hard to find maintainers at all" that may well mean we end up with an extension that is very spottily implemented :(

[xibz]

As someone who used to maintain SDKs, I understand the pain :(.

I will have to check with legal, but we may be able to help with some implementations, e.g., golang, java, python.

C# is a little out of skillset though ><. At this point it seems like figuring out the best path to get this implemented.

I will have a commit that updates the other points, e.g., the duplicated canonicalization stuff, type lists, etc, soon

[clemensv]

DSSE JSON envelope (like below)

[clemensv]

"Zulu" is mentioned once in RFC3339, but it will be helpful to show a formatted datetime example of what you mean here and also link to the RFC. That's a good potential source of hours of debugging fun if one misses this detail.

[clemensv]

We should assume that all timezone-less datetime values are UTC.

[clemensv]

I am in favor of merging this once the remaining raised issues are addressed, which all seem editorial. The mechanism is clearly explained.