diff --git a/cloudevents/extensions/verifiability-flow.jpg b/cloudevents/extensions/verifiability-flow.jpg new file mode 100644 index 000000000..cfa4b07f6 Binary files /dev/null and b/cloudevents/extensions/verifiability-flow.jpg differ diff --git a/cloudevents/extensions/verifiability.md b/cloudevents/extensions/verifiability.md new file mode 100644 index 000000000..f4f00a8e9 --- /dev/null +++ b/cloudevents/extensions/verifiability.md @@ -0,0 +1,269 @@ +# CloudEvents Verifiability Extension + +This proposal introduces a transport protocol agnostic design for verifiable +CloudEvents. It allows producers of CloudEvents to sign the events that they +send and consumers to cryptographically verify the *authenticity and the +integrity* of the events that they receive. Through this process consumers can +be sure that events were in fact produced by the claimed producer +(authenticity), and that the events were received exactly as they were sent, +and not modified in transit (integrity). + +The threats addressed by this proposal are those of malicious actors +impersonating CloudEvent producers and of malicious actors modifying messages +in transit. + +This proposal only applies to individual events. It does not give consumers any +guarantees about the completeness of the event stream or the order of events. + +The threats of malicious actors removing or hiding items from the event stream +as well as swapping their order are not addressed by this proposal. Neither are +the possibilities of messages accidentally getting lost or delivered in the +wrong order. Both can be addressed by producers through means of adding the +necessary information inside the event payloads. + +Further, this proposal only aims at *verifiability*. It does not aim to enable +*confidentiality*. Consequently, it does not address the threat of unauthorized +parties reading CloudEvents that were not meant for them. + +## Notational Conventions + +As with the main [CloudEvents specification](../spec.md), the key words "MUST", +"MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", +"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as +described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + +However, the scope of these key words is limited to when this extension is +used. For example, an attribute being marked as "REQUIRED" does not mean +it needs to be in all CloudEvents, rather it needs to be included only when +this extension is being used. + +## Attributes + +### `verificationmaterial` (Verification Material) + +- **Type:** `String` +- **Description:** + The material consumers use to verify a CloudEvent. For example, this could + be a signature of the event generated using a private key. Consumers would + use the producer’s public key to verify the signature. + + Producers SHOULD avoid relying on canonicalization to minimize the attack + surface. Verification material SHOULD be transported in a detached format + when possible to avoid canonicalization issues. +- **Constraints:** + - REQUIRED + - MUST be base64-encoded + - If present, the `verificationmaterialtype` attribute MUST also be present + - MUST be transported in the same message as the event + - MUST NOT appear more than once in the message (duplication of the attribute + MUST cause failure) + - If `verificationmaterialtype` is missing, the implementation MUST fail + - If the verification material is invalid (e.g., does not match the received + event), the implementation MUST fail + - If the verification material is of an unknown type, the implementation + SHOULD fail + +### `verificationmaterialtype` (Verification Material Type) + +- **Type:** `String` +- **Description:** + Indicates the type of verification material. This high-level category + informs consumers how to interpret and process the verification material. It + can include implementation-specific details such as subtype, version + information, etc. +- **Constraints:** + - REQUIRED + - If present, the `verificationmaterial` attribute MUST also be present + - Producers and consumers MUST agree on the material type to ensure + successful verification + - MUST NOT appear more than once in the message (duplication of the attribute + MUST cause failure) + - If `verificationmaterial` is missing, the implementation MUST fail + - If the material type is unknown to the implementation, it MUST fail + + +## Usage + +When this extension is used, producers MUST set both the `verificationmaterial` +and `verificationmaterialtype` attributes. Consumers can choose whether to +perform verification and how to proceed if verification fails. + +## Assumptions + +This proposal contains a few key assumptions: + +1. SDKs will verify as early as possible which depends on the + verification implementation. +2. Users manage their secrets, e.g. public key infrastructure (PKI). + +## Design + +Verifiability in CloudEvents consists of two steps: + +1. The producer of an event adds verification material to the message +2. The consumer of an event MAY use the verification material to verify the + authenticity and integrity of the event + + +The specifics of what the verification material looks like and how the +verification is performed depends on the *verifiability implementation*. + +For example, in a public/private key based implementation the producer of an +event would add a signature based on their private key as the verification +material, and the consumer of an event could use the corresponding public key +to check if the signature matches the event. + +The flow looks like this: + +![Flow](./verifiability-flow.jpg) + +*Option 1*: useful for verifiability implementations outside of the CE SDK. The +CE SDK merely passes on messages and is not involved in producing verification +material or performing verifications and has no knowledge about the secrets +that the verification is based on (e.g. private keys). Appropriate for tools in +a closed ecosystem like an enterprise system(s) with special requirements that +are not suitable for the CE SDK. + +*Option 2*: useful for verifiability implementations that are directly +supported by the CE SDK. The CE SDK has to be provided with the secrets (e.g. +private key for producer and public key for consumers) and will create the +verification material on the producer side and also perform the verification on +the consumer side. This is the appropriate choice for any type of tool that is +used by other entities, for example open source. + +**Notes:** If an intermediary party modifies an event, they are considered the +producer of a new event. They MUST create an updated verification material and +the consumer(s) MUST recognize them as a trustworthy producer. + +The choice between Option 1 and Option 2 can be made independently by each +system. For example, a producer might follow Option 1 while a consumer uses +Option 2, depending on their requirements and trust boundaries. + +## Verifiability Implementation Proposals + +A proposal for adding a verifiability implementation to the CE SDK **MUST:** + +* provide specs on how to implement verification +* provide test vectors +* provide a verification coverage table (see Verification coverage table) + +Test vectors ensure that implementations are consistent which does NOT affect +verifiability. + +A proposal for adding a verifiability implementation to the CE SDK **SHOULD:** + +* provide information about how they handle attributes, and if relevant, normalization + +## Example + +To illustrate, let’s walk through how to implement a verification +implementation + +### Verification Implementation + +This is an example message containing a CloudEvent directly from the spec. It +happens to be an HTTP structured mode message in JSON format. Our goal is to +come up with the most insecure but also most concise verification +implementation imaginable: one based on a reversed digest which we will call +`rev`! The `rev` implementation will only verify whether or not the +payload, `data`, is valid and not whether the other context attributes are +valid, for the sake of simplicity. + +Here is how a message containing that CloudEvent might look: + +``` +content-length: 209 +content-type: application/json + +{ + "specversion" : "1.0", + "type" : "com.example.someevent", + "source" : "/mycontext", + "subject": null, + "id" : "D234-1234-1234", + "time" : "2018-04-05T17:31:00Z", + "data" : "I'm just a string" +} +``` + +In order to make this event verifiable, the reversed value of the 'data' field +is computed and base64-encoded: `Z25pcnRzIGEgdHN1aiBtJ0kK`. +This value will then be base64 encoded and added as the `verificationmaterial` +context attribute: + +``` +content-length: 209 +content-type: application/json + +{ + "specversion" : "1.0", + "type" : "com.example.someevent", + "source" : "/mycontext", + "subject": null, + "id" : "D234-1234-1234", + "time" : "2018-04-05T17:31:00Z", + "data" : "I'm just a string", + "verificationmaterial": "Z25pcnRzIGEgdHN1aiBtJ0kK", + "verificationmaterialtype": "rev" +} +``` + +A consumer then receives this message and in order to verify, they would look +at the `verificationmaterialtype` attribute to determine whether it knows how +to perform the verification. The consumer sees that verification material’s +type is `rev`, so they will compute the `rev` of the payload to verify the +CloudEvent contained in the message: + +``` +$ echo -n "I'm just a string" | rev +gnirts a tsuj m'I +``` + +The consumer can then confirm that the verification material matches the rev +output and conclude that the CloudEvent’s authenticity and integrity are +"guaranteed". + +Now, since we want to make our fantasy verification implementation into a +proposal to be included in the CE SDK, we will need to define test vectors and +a verification coverage table. + +### Test Vectors + +An example test vector is defined below: + +``` +[ + "input": { + { + "specversion" : "1.0", + "type" : "com.example.someevent", + "source" : "/mycontext", + "subject": null, + "id" : "D234-1234-1234", + "time" : "2018-04-05T17:31:00Z", + "data" : "I'm just a string" + } + }, + "expectedVerificationMaterialType": "rev", + "expectedVerificationMaterial": "Z25pcnRzIGEgdHN1aiBtJ0kK" +] +``` + +SDKs and implementers can then use the vectors to ensure that any +implementation is correct and verifiable across different languages and +systems. + +### Verification Coverage Table + +The table below outlines which parts of a CloudEvent for our imaginary `rev` +based verification implementation would cover: + +|Verifiable information |binary-mode |structured-mode |comment | +|--- |--- |--- |--- | +|data/payload |✅ |✅ | | +|mandatory context attributes |❌ |❌ |The `rev` verification implementation only looks at the payload, not at any context attributes. | +|permissive context attributes |❌ |❌ | +|extension attributes |❌ |❌ | + +Again, `rev` was chosen because it makes for an easily readable example. It is +wildly insecure and not suitable for actual verifiability. diff --git a/cloudevents/languages/he/extensions/verifiability.md b/cloudevents/languages/he/extensions/verifiability.md new file mode 100644 index 000000000..2ba5ed934 --- /dev/null +++ b/cloudevents/languages/he/extensions/verifiability.md @@ -0,0 +1,3 @@ +# CloudEvents Verifiability Extension +מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/verifiability.md) לבינתיים. + diff --git a/cloudevents/languages/zh-CN/extensions/verifiability.md b/cloudevents/languages/zh-CN/extensions/verifiability.md new file mode 100644 index 000000000..bae4142e8 --- /dev/null +++ b/cloudevents/languages/zh-CN/extensions/verifiability.md @@ -0,0 +1,7 @@ +# CloudEvents Verifiability Extension + +本文档尚未被翻译,请先阅读英文[原版文档](../../../extensions/verifiability.md) 。 + +如果您迫切地需要此文档的中文翻译,请[提交一个issue](https://github.com/cloudevents/spec/issues) , +我们会尽快安排专人进行翻译。 +