Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding verifiability proposal #1330

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Adding verifiability proposal #1330

wants to merge 1 commit into from

Conversation

xibz
Copy link

@xibz xibz commented Feb 28, 2025

Description

The "CloudEvents Verifiability" proposal introduces a transport protocol-agnostic mechanism to enhance the security of CloudEvents. It enables event producers to sign the events they emit, allowing consumers to cryptographically verify both the authenticity and integrity of the received events. This ensures that consumers can trust the source of the events and be confident that the events have not been tampered with during transit. The primary threats addressed by this proposal are impersonation of event producers and unauthorized modification of events in transit.

This was a team effort here in writing this proposal between me, @xibz, and @jayniz

Proposed Changes

1. Introduction of Event Signatures

  • Define a standard method for producers to attach digital signatures to CloudEvents.
  • Specify the metadata fields required to store signature information within the event structure.

2. Verification Mechanism for Consumers

  • Outline procedures for consumers to verify the authenticity of an event's origin using the attached signature.
  • Provide guidelines on validating the integrity of the event data to ensure it hasn't been altered.

Release Notes

  • Feature Addition: Introduced a verifiability mechanism allowing event producers to digitally sign CloudEvents, enabling consumers to verify the authenticity and integrity of received events.

  • Security Enhancement: Addresses potential security threats by preventing impersonation of event producers and unauthorized modification of events during transit.

This proposal aims to bolster the security framework of CloudEvents by providing a standardized approach to event verifiability, thereby enhancing trust in event-driven systems.

This commit introduces the verifiability proposal which introduces two
new attributes: verificationmaterial and verificationmaterialtype

This only outlines the format for sending verification material, and
does not contain an implementation. At least not yet.

Signed-off-by: benjamin-j-powell <[email protected]>
```
content-length: 209
content-type: application/json
ce-verificationmaterial: ZGM5OGU3MmQwZjk5ODBlODlhZjVmOGU3NjkyZDU4ZDc=
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these should appear in the body along-side the other CE attributes, no?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Depends on if it is structured or binary mode.

By along-side, you are meaning within the payload?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes it depends, but in this example you're using structured based on what i see in the http body. So these new CE attributes should be in the body too. No?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh I see what you mean. Yes, that's a mistake on our end. I'll update after today's SIG.

A consumer then receives the this message and in order to verify, they must look at the `ce-erificationmaterialtype` header to determine whether it knows how to perform the verification. The consumer sees that verification material’s type is `md5`, so they will compute the `md5` of the payload to verify the CloudEvent contained in the message:

```
$ echo -n '{
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since some CE attributes might be modified by intermediaries, I wonder if there should be a mechanism by which the producer can indicate which CE attributes are part of the verification.

Also, might need to talk about whether the data needs to be normalized (or not)... or do you think that's part of the implementation specific details of the chosen verification algorithm? Kind of related... what if someone sends JSON but an intermediary converts it to XML or protobuf? Do you see this being used for e2e processing even if the format changes or just single-format transmissions?

Copy link
Author

@xibz xibz Mar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since some CE attributes might be modified by intermediaries, I wonder if there should be a mechanism by which the producer can indicate which CE attributes are part of the verification.

For things like DSSE, that is easily done and possible. The goal is to have an DSSE implementation proposal after this one which will cover headers and how those can be included in verification.

Also, might need to talk about whether the data needs to be normalized

Yes, these would be considered implementation specific because for some signing algorithms like DSSE, it completely avoids normalization.

For ones that requires normalization, like JWT, then it would need to have some form of normalization to work appropriately. I think for those situations, we can either leave it up to the implementation or try to come up with and end all be all way of normalizing if it is relevant for the signing algorithm. However, my example of JWT already defines how it normalizes, hence why having it in the implementation may make sense.

The benefit of having implementation specific is that it allows for the implementing algorithm utilize it's signing procedures to figure out what's best for normalizing. However, this also means we'd have multiple ways of normalizing across implementations. In addition, we should always recommend to not normalize

what if someone sends JSON but an intermediary converts it to XML or protobuf?

For DSSE this isn't an issue as long as the payload isn't touched. If it's just the encoding, then DSSE will be able to handle that. However for other signing algorithms, the implementation would need to specify how it handles normalization. However, if something is being changed like a key or value, then the manipulator needs to re-sign.

@erikerikson
Copy link
Member

A top level comment with only a suggestion. In the past when the group has discussed this sort of thing, we have thought that it would start as an official extension. You may want to consider moving these into the extensions folder because this will provide a lower probability of rejection and a perhaps lower bar for acceptance. We will, of course, do our best to provide sufficient constructive criticism to yield a more useful result.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants