From 62abbf797b3c8d0e45e8adfe12efcadc22d9e127 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Tue, 16 Jul 2024 15:46:39 +0000 Subject: [PATCH] Provide some guidance on how security can be layered on top of CE Fixes #1290 Fixes #1288 Signed-off-by: Doug Davis --- .../bindings/kafka-protocol-binding.md | 3 +- cloudevents/primer.md | 105 +++++++++++++++--- cloudevents/spec.md | 6 +- 3 files changed, 99 insertions(+), 15 deletions(-) diff --git a/cloudevents/bindings/kafka-protocol-binding.md b/cloudevents/bindings/kafka-protocol-binding.md index 929a4fe0f..8c4d3749e 100644 --- a/cloudevents/bindings/kafka-protocol-binding.md +++ b/cloudevents/bindings/kafka-protocol-binding.md @@ -196,7 +196,8 @@ message will represent a _tombstone_ record, as described in the #### 3.2.3. Metadata Headers All [CloudEvents][ce] attributes and -[CloudEvent Attributes Extensions](../primer.md#cloudevent-extension-attributes) +[CloudEvent Attributes +Extensions](../primer.md#cloudevents-extension-attributes) with exception of `data` MUST be individually mapped to and from the Header fields in the Kafka message. Both header keys and header values MUST be encoded as UTF-8 strings. diff --git a/cloudevents/primer.md b/cloudevents/primer.md index 587ca8894..728fbbafe 100644 --- a/cloudevents/primer.md +++ b/cloudevents/primer.md @@ -5,10 +5,10 @@ ## Abstract This non-normative document provides an overview of the CloudEvents -specification. It is meant to complement the CloudEvent specification to provide -additional background and insight into the history and design decisions made -during the development of the specification. This allows the specification -itself to focus on the normative technical details. +specification. It is meant to complement the CloudEvents specification to +provide additional background and insight into the history and design +decisions made during the development of the specification. This allows the +specification itself to focus on the normative technical details. ## Table of Contents @@ -17,8 +17,9 @@ itself to focus on the normative technical details. - [Design Goals](#design-goals) - [Architecture](#architecture) - [Versioning of CloudEvents](#versioning-of-cloudevents) -- [CloudEvent Core Attributes](#cloudevent-core-attributes) -- [CloudEvent Extension Attributes](#cloudevent-extension-attributes) +- [CloudEvents Core Attributes](#cloudevents-core-attributes) +- [CloudEvents Extension Attributes](#cloudevents-extension-attributes) +- [CloudEvents with Security](#cloudevents-with-security) - [Creating CloudEvents](#creating-cloudevents) - [Qualifying Protocols and Encodings](#qualifying-protocols-and-encodings) - [Proprietary Protocols and Encodings](#proprietary-protocols-and-encodings) @@ -197,7 +198,7 @@ by the components implemented by the implementor of the specification themselves. However, if the community observes a pattern in usage of certain extension attributes, as a standard way to deal with the topic of data integrity. In that case, such extension attributes can be declared as official -extensions to the CloudEvent specification. +extensions to the CloudEvents specification. ## Architecture @@ -317,10 +318,10 @@ When a CloudEvent's data changes in a backwardly-incompatible way, the value of `dataschema` attribute should generally change, along with the `type` attribute as described above. -## CloudEvent Core Attributes +## CloudEvents Core Attributes This section provides additional background and design points related to some of -the CloudEvent core attributes. +the CloudEvents core attributes. ### id @@ -346,11 +347,11 @@ then some additional data within the CloudEvent would be used for that purpose. In this respect, while the exact value chosen by the event producer might be some random string, or a string that has some semantic meaning in some other -context, for the purposes of this CloudEvent attribute those meanings are not +context, for the purposes of this CloudEvents attribute those meanings are not relevant and therefore using `id` for some other purpose beyond uniqueness checking is out of scope of the specification and not recommended. -## CloudEvent Extension Attributes +## CloudEvents Extension Attributes In order to achieve the stated goals, the specification authors will attempt to constrain the number of metadata attributes they define in CloudEvents. To that @@ -380,7 +381,7 @@ be included at all, the group uses use-cases and user-stories to explain the rationale and need for them. This supporting information will be added to the [Prior Art](#prior-art) section of this document. -Extension attributes to the CloudEvent specification are meant to be additional +Extension attributes to the CloudEvents specification are meant to be additional metadata that needs to be included to help ensure proper routing and processing of the CloudEvent. Additional metadata for other purposes, that is related to the event itself and not needed in the transportation or processing of the @@ -448,6 +449,84 @@ serialization for unknown, or even new, properties. It was also noted that the HTTP specification is now following a similar pattern by no longer suggesting that extension HTTP headers be prefixed with `X-`. +## CloudEvents with Security + +The core CloudEvents specification purposely does not address security beyond +suggesting that preexisting security mechanisms should be used. For example, +the use of TLS when using HTTP. The CloudEvents specification authors did not +see the need to invent something new, rather composition with existing +technologies that are already being used seemed more appropriate. + +With that in mind, below are a few CloudEvent serializations that are composed +with popular encryption technologies to give a non-normative examples of how +security may be layered on top of a CloudEvent: + +- a JSON serialization CloudEvent composed with the + [JOSE](https://datatracker.ietf.org/doc/rfc7516) specification (line-breaks + are added for display purposes only): + +```json +{ + "specversion" : "1.0", + "type" : "PAYMENT.AUTHORIZATION.CREATED", + "source" : "https://paymentprocessor.example.com/", + "subject" : "c7bbb040-d458-4d47-82a8-45413f9f2d33", + "id" : "a978702e-ef48-4032-ac18-a057e0104076", + "time" : "2024-05-30T17:31:00Z", + "datacontenttype" : "application/jose", + "data_base64" : "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. + OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe + ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb + Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV + mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 + 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi + 6UklfCpIMfIjf7iGdXKHzg. + 48V1_ALb6US04U3b. + 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji + SdiwkIr3ajwQzaBtQD_A. + XFBoMYUZodetZdvTiFvSkQ" +} +``` + +- an XML serialized CloudEvent composed with XML Signature +```xml + + + + application/xml + 000-1111-2222 + urn:uuid:123e4567-e89b-12d3-a456-426614174000 + SOME.EVENT.TYPE + + + 51.509865 + -0.118092 + + + + + + + + + + + + + + + + + DCDNxibEA3BHpFMtzvj7hxd7p5A= + + + jocgUrZPKR8jvery4gG4V34qx7/yxOESPJq//iS3Q5Ps7lPADNBEVK4Y50HIdrkodcYLZjBkvuGMT89nTeT24W/Dw/XEeMWXRmy/Mj1/rza8JMaP46F+2MZ6tlGWlyA2tRZNExe5TPA8Wo6jTSN3KX3aLoLkwRsLBt50Zr8zz8xFtadZciNWnsD6y/UgQzNYfLovMw54AHGk+5FzRWMgwtTseISWxSF+9zsgiQStrrXzy1SaRycQTAjz4PF6HebGWJcECLa+r/iLtigbTmgL3Mj7mkmw90M3mNncqZKBFmjNxTZCPiMQHbSvTgOBe8REwCrclHJkyYP14NsxEg6LZQ== + + +``` + ## Creating CloudEvents The CloudEvents specification purposely avoids being too prescriptive about how @@ -614,7 +693,7 @@ links to all specs. ## Prior Art This section describes some of the input material used by the group during the -development of the CloudEvent specification. +development of the CloudEvents specification. ### Roles diff --git a/cloudevents/spec.md b/cloudevents/spec.md index 17a433e04..2ba5d1cc8 100644 --- a/cloudevents/spec.md +++ b/cloudevents/spec.md @@ -503,7 +503,7 @@ messages if the copied values differ from the cloud-event serialized values. #### Defining Extensions See -[CloudEvent Attributes Extensions](primer.md#cloudevent-extension-attributes) +[CloudEvent Attributes Extensions](primer.md#cloudevents-extension-attributes) for additional information concerning the use and definition of extensions. The definition of an extension SHOULD fully define all aspects of the @@ -610,6 +610,10 @@ Consider the following to prevent inadvertent leakage especially when leveraging Protocol level security SHOULD be employed to ensure the trusted and secure exchange of CloudEvents. +See the [CloudEvents Primer](primer.md#cloudevents-with-security) for more +information about how existing security mechanisms can be used with +CloudEvents. + ## Example The following example shows a CloudEvent serialized as JSON: