From f102308a01ed42d6c2534cb139dd22c07aec37ea Mon Sep 17 00:00:00 2001 From: Rob Sessink Date: Thu, 7 Nov 2024 11:19:36 +0100 Subject: [PATCH 1/9] Add data-classification.md extension Signed-off-by: Rob Sessink --- cloudevents/extensions/data-classification.md | 87 +++++++++++++++++++ .../he/extensions/data-classification.md | 2 + .../zh-CN/extensions/data-classification.md | 6 ++ 3 files changed, 95 insertions(+) create mode 100644 cloudevents/extensions/data-classification.md create mode 100644 cloudevents/languages/he/extensions/data-classification.md create mode 100644 cloudevents/languages/zh-CN/extensions/data-classification.md diff --git a/cloudevents/extensions/data-classification.md b/cloudevents/extensions/data-classification.md new file mode 100644 index 00000000..00dbe9f5 --- /dev/null +++ b/cloudevents/extensions/data-classification.md @@ -0,0 +1,87 @@ +# Data Classification Extension + +CloudEvents may contain payload which is subjected to data protection +regulations like GDPR or HIPAA. For intermediaries and consumers knowing how +event payload is classified, which data protection regulation applies and how +payload is categorized, enables compliant processing of an event. + +This extension defines attributes to describe to +[consumers](../spec.md#consumer) or [intermediaries](../spec.md#intermediary) +how an event and its payload is classified, category of the payload and any +applicable data protection regulations. + +These attributes are intended for classification on an event and payload level +and not on `data` field level. Classification on field level is best defined in +the schema specified via the `dataschema` attribute. + +## 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 + +### dataclassification + +- Type: `String` +- Description: Data classification level for the event payload within the + context of a `dataregulation`. Typical labels are: `public`, `internal`, + `confidential`, `restricted`. +- Constraints: + - REQUIRED + - SHOULD be applicable to data protection regulation. + +### dataregulation + +- Type: `String` +- Description: A comma-delimited list of applicable data protection regulations. + For example: `GDPR`, `HIPAA`, `PCI-DSS`, `ISO-27001`, `NIST-800-53`, `CCPA`. +- Constraints: + - OPTIONAL + - if present, MUST be a non-empty string + +### datacategory + +- Type: `String` +- Description: Data category of the event payload within the context of a + `dataregulation` and `dataclassification`. For GDPR personal data typical + labels are: `non-sensitive`, `standard`, `sensitive`, `special-category`. For + US personal data this could be: `sensitive-pii`, `non-sensitive-pii`, + `non-pii`. And for personal health information under HIPAA: `phi`. +- Constraints: + - OPTIONAL + - if present, MUST be a non-empty string + - SHOULD be applicable to data regulation and classification. + +## Usage + +When this extension is used, producers MUST set the value of the +`dataclassification` attribute. When applicable the `dataregulation` and +`datacategory` attributes MAY be set to provide additional details on the +classification context. + +Intermediaries and consumers SHOULD take these attributes into account and act +accordingly to data regulations and/or internal policies when processing the +event and payload. + +Intermediaries SHOULD NOT modify the `dataclassification`, `dataregulation`, and +`datacategory` attributes. + +## Use cases + +Examples where data classification of events can be useful are: + +- When an event contains PII or restricted information and therefore processing + by intermediaries or consumers must adhere to certain policies. For example + having separate processing pipelines by sensitivity or having logging, + auditing and access policies based upon classification. +- When an event payload is subjected to regulation and therefore retention + policies apply. For example, having event retention policies based upon data + classification or to enable automated data purging durable topics. \ No newline at end of file diff --git a/cloudevents/languages/he/extensions/data-classification.md b/cloudevents/languages/he/extensions/data-classification.md new file mode 100644 index 00000000..fd8309c8 --- /dev/null +++ b/cloudevents/languages/he/extensions/data-classification.md @@ -0,0 +1,2 @@ +# Data Classification Extension +מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/data-classification) לבינתיים. \ No newline at end of file diff --git a/cloudevents/languages/zh-CN/extensions/data-classification.md b/cloudevents/languages/zh-CN/extensions/data-classification.md new file mode 100644 index 00000000..d8d8b6d7 --- /dev/null +++ b/cloudevents/languages/zh-CN/extensions/data-classification.md @@ -0,0 +1,6 @@ +# Data Classification Extension + +本文档尚未被翻译，请先阅读英文[原版文档](../../../extensions/data-classification.md) 。 + +如果您迫切地需要此文档的中文翻译，请[提交一个issue](https://github.com/cloudevents/spec/issues) ， +我们会尽快安排专人进行翻译。 \ No newline at end of file From 5d895782e324e915f46bf0681f5415d99ec1cc9d Mon Sep 17 00:00:00 2001 From: Rob Sessink Date: Thu, 14 Nov 2024 08:46:14 +0100 Subject: [PATCH 2/9] FIX based upon PR comments: correct spelling, add link in extensions/README.md and usage of MUST keyword in example use case - Signed-off-by: Rob Sessink --- cloudevents/extensions/README.md | 1 + cloudevents/extensions/data-classification.md | 4 ++-- cloudevents/languages/he/extensions/data-classification.md | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/cloudevents/extensions/README.md b/cloudevents/extensions/README.md index 167edba7..0b66ea88 100644 --- a/cloudevents/extensions/README.md +++ b/cloudevents/extensions/README.md @@ -42,6 +42,7 @@ for more information. - [Auth Context](authcontext.md) - [BAM](bam.md) +- [Data Classification](data-classification.md) - [Dataref (Claim Check Pattern)](dataref.md) - [Deprecation](deprecation.md) - [Distributed Tracing](distributed-tracing.md) diff --git a/cloudevents/extensions/data-classification.md b/cloudevents/extensions/data-classification.md index 00dbe9f5..0fd609b9 100644 --- a/cloudevents/extensions/data-classification.md +++ b/cloudevents/extensions/data-classification.md @@ -1,6 +1,6 @@ # Data Classification Extension -CloudEvents may contain payload which is subjected to data protection +CloudEvents might contain payload which is subjected to data protection regulations like GDPR or HIPAA. For intermediaries and consumers knowing how event payload is classified, which data protection regulation applies and how payload is categorized, enables compliant processing of an event. @@ -79,7 +79,7 @@ Intermediaries SHOULD NOT modify the `dataclassification`, `dataregulation`, and Examples where data classification of events can be useful are: - When an event contains PII or restricted information and therefore processing - by intermediaries or consumers must adhere to certain policies. For example + by intermediaries or consumers MUST adhere to certain policies. For example having separate processing pipelines by sensitivity or having logging, auditing and access policies based upon classification. - When an event payload is subjected to regulation and therefore retention diff --git a/cloudevents/languages/he/extensions/data-classification.md b/cloudevents/languages/he/extensions/data-classification.md index fd8309c8..63cba332 100644 --- a/cloudevents/languages/he/extensions/data-classification.md +++ b/cloudevents/languages/he/extensions/data-classification.md @@ -1,2 +1,2 @@ # Data Classification Extension -מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/data-classification) לבינתיים. \ No newline at end of file +מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/data-classification.md) לבינתיים. \ No newline at end of file From db7fcda94ae13cac4996bde4aaaf4b935fbbc9d9 Mon Sep 17 00:00:00 2001 From: Rob Sessink Date: Sat, 16 Nov 2024 12:40:23 +0100 Subject: [PATCH 3/9] FIX based upon PR comments: improve spelling Signed-off-by: Rob Sessink --- cloudevents/extensions/data-classification.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cloudevents/extensions/data-classification.md b/cloudevents/extensions/data-classification.md index 0fd609b9..64cfe97b 100644 --- a/cloudevents/extensions/data-classification.md +++ b/cloudevents/extensions/data-classification.md @@ -10,9 +10,9 @@ This extension defines attributes to describe to how an event and its payload is classified, category of the payload and any applicable data protection regulations. -These attributes are intended for classification on an event and payload level -and not on `data` field level. Classification on field level is best defined in -the schema specified via the `dataschema` attribute. +These attributes are intended for classification at an event and payload level +and not at a `data` field level. Classification at a field level is best defined +in the schema specified via the `dataschema` attribute. ## Notational Conventions From b22870d9e808841494eea4a762d02e39893d3cf7 Mon Sep 17 00:00:00 2001 From: Rob Sessink Date: Wed, 20 Nov 2024 13:46:21 +0100 Subject: [PATCH 4/9] FIX based upon PR comments: improve description around recommended labels, remove 'applicability constraints', extend usage section. - Signed-off-by: Rob Sessink --- cloudevents/extensions/data-classification.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/cloudevents/extensions/data-classification.md b/cloudevents/extensions/data-classification.md index 64cfe97b..97157cfb 100644 --- a/cloudevents/extensions/data-classification.md +++ b/cloudevents/extensions/data-classification.md @@ -32,11 +32,12 @@ is being used. - Type: `String` - Description: Data classification level for the event payload within the - context of a `dataregulation`. Typical labels are: `public`, `internal`, - `confidential`, `restricted`. + context of a `dataregulation`. In situations where `dataregulation` is + undefined or the data protection regulation does not define any labels, then + recommended labels are: `public`, `internal`, `confidential`, or + `restricted`. - Constraints: - REQUIRED - - SHOULD be applicable to data protection regulation. ### dataregulation @@ -58,7 +59,6 @@ is being used. - Constraints: - OPTIONAL - if present, MUST be a non-empty string - - SHOULD be applicable to data regulation and classification. ## Usage @@ -67,9 +67,11 @@ When this extension is used, producers MUST set the value of the `datacategory` attributes MAY be set to provide additional details on the classification context. -Intermediaries and consumers SHOULD take these attributes into account and act -accordingly to data regulations and/or internal policies when processing the -event and payload. +When an implementation supports this extension, then intermediaries and +consumers MUST take these attributes into account and act accordingly to data +regulations and/or internal policies in processing the event and payload. If +intermediaries or consumers cannot meet such requirements, they MUST reject or +ignore the event. Intermediaries SHOULD NOT modify the `dataclassification`, `dataregulation`, and `datacategory` attributes. From 7d3f27b774fb3d66cf556263aa4c9814d7521e25 Mon Sep 17 00:00:00 2001 From: Rob Sessink Date: Wed, 20 Nov 2024 17:12:59 +0100 Subject: [PATCH 5/9] FIX based upon PR comments: improve wording and usage of notational conventions - Signed-off-by: Rob Sessink --- cloudevents/extensions/data-classification.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/cloudevents/extensions/data-classification.md b/cloudevents/extensions/data-classification.md index 97157cfb..baeca61f 100644 --- a/cloudevents/extensions/data-classification.md +++ b/cloudevents/extensions/data-classification.md @@ -1,9 +1,9 @@ # Data Classification Extension -CloudEvents might contain payload which is subjected to data protection +CloudEvents might contain payloads which are subjected to data protection regulations like GDPR or HIPAA. For intermediaries and consumers knowing how -event payload is classified, which data protection regulation applies and how -payload is categorized, enables compliant processing of an event. +event payloads are classified, which data protection regulation applies and how +payloads are categorized, enables compliant processing of events. This extension defines attributes to describe to [consumers](../spec.md#consumer) or [intermediaries](../spec.md#intermediary) @@ -34,7 +34,7 @@ is being used. - Description: Data classification level for the event payload within the context of a `dataregulation`. In situations where `dataregulation` is undefined or the data protection regulation does not define any labels, then - recommended labels are: `public`, `internal`, `confidential`, or + RECOMMENDED labels are: `public`, `internal`, `confidential`, or `restricted`. - Constraints: - REQUIRED @@ -46,7 +46,8 @@ is being used. For example: `GDPR`, `HIPAA`, `PCI-DSS`, `ISO-27001`, `NIST-800-53`, `CCPA`. - Constraints: - OPTIONAL - - if present, MUST be a non-empty string + - if present, MUST be a non-empty string without internal spaces. Leading and + trailing spaces around each entry MUST be ignored. ### datacategory @@ -81,7 +82,7 @@ Intermediaries SHOULD NOT modify the `dataclassification`, `dataregulation`, and Examples where data classification of events can be useful are: - When an event contains PII or restricted information and therefore processing - by intermediaries or consumers MUST adhere to certain policies. For example + by intermediaries or consumers need to adhere to certain policies. For example having separate processing pipelines by sensitivity or having logging, auditing and access policies based upon classification. - When an event payload is subjected to regulation and therefore retention From de8f7a5efc0747ebc84fd43162dc2d62fd157d97 Mon Sep 17 00:00:00 2001 From: Rob Sessink Date: Thu, 21 Nov 2024 08:23:55 +0100 Subject: [PATCH 6/9] FIX: add missing 'of' Signed-off-by: Rob Sessink --- cloudevents/extensions/data-classification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cloudevents/extensions/data-classification.md b/cloudevents/extensions/data-classification.md index baeca61f..bb01190c 100644 --- a/cloudevents/extensions/data-classification.md +++ b/cloudevents/extensions/data-classification.md @@ -87,4 +87,4 @@ Examples where data classification of events can be useful are: auditing and access policies based upon classification. - When an event payload is subjected to regulation and therefore retention policies apply. For example, having event retention policies based upon data - classification or to enable automated data purging durable topics. \ No newline at end of file + classification or to enable automated data purging of durable topics. \ No newline at end of file From a1b3ae73beb92f3bc76928fc24ee24aff87deca5 Mon Sep 17 00:00:00 2001 From: Rob Sessink Date: Thu, 28 Nov 2024 21:18:02 +0100 Subject: [PATCH 7/9] FIX based upon PR comments: extend usage section to state expectations when intermediaries/consumers encounter unknown attribute values. - Signed-off-by: Rob Sessink --- cloudevents/extensions/data-classification.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/cloudevents/extensions/data-classification.md b/cloudevents/extensions/data-classification.md index bb01190c..5667c420 100644 --- a/cloudevents/extensions/data-classification.md +++ b/cloudevents/extensions/data-classification.md @@ -74,6 +74,11 @@ regulations and/or internal policies in processing the event and payload. If intermediaries or consumers cannot meet such requirements, they MUST reject or ignore the event. +If intermediaries or consumers are unsure on how to interpret these attributes, +for example when they encounter an unknown classification level or data +regulation, they must assume they cannot meet requirements and MUST reject or +ignore the event. + Intermediaries SHOULD NOT modify the `dataclassification`, `dataregulation`, and `datacategory` attributes. From c4c2ca136d632fad55f11568144ff3d9a7e01f2d Mon Sep 17 00:00:00 2001 From: Rob Sessink Date: Thu, 28 Nov 2024 21:24:32 +0100 Subject: [PATCH 8/9] FIX: must -> MUST Signed-off-by: Rob Sessink --- cloudevents/extensions/data-classification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cloudevents/extensions/data-classification.md b/cloudevents/extensions/data-classification.md index 5667c420..8cd99549 100644 --- a/cloudevents/extensions/data-classification.md +++ b/cloudevents/extensions/data-classification.md @@ -76,7 +76,7 @@ ignore the event. If intermediaries or consumers are unsure on how to interpret these attributes, for example when they encounter an unknown classification level or data -regulation, they must assume they cannot meet requirements and MUST reject or +regulation, they MUST assume they cannot meet requirements and MUST reject or ignore the event. Intermediaries SHOULD NOT modify the `dataclassification`, `dataregulation`, and From c280ffd0cc04e1b85969c6712461cd75cc9fdbfb Mon Sep 17 00:00:00 2001 From: Rob Sessink Date: Thu, 5 Dec 2024 20:58:38 +0100 Subject: [PATCH 9/9] FIX based upon PR comments: in Usage section change 'ignore event' into 'report error'. Signed-off-by: Rob Sessink --- cloudevents/extensions/data-classification.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cloudevents/extensions/data-classification.md b/cloudevents/extensions/data-classification.md index 8cd99549..3b107117 100644 --- a/cloudevents/extensions/data-classification.md +++ b/cloudevents/extensions/data-classification.md @@ -71,13 +71,13 @@ classification context. When an implementation supports this extension, then intermediaries and consumers MUST take these attributes into account and act accordingly to data regulations and/or internal policies in processing the event and payload. If -intermediaries or consumers cannot meet such requirements, they MUST reject or -ignore the event. +intermediaries or consumers cannot meet such requirements, they MUST reject and +report an error through a protocol-level mechanism. If intermediaries or consumers are unsure on how to interpret these attributes, for example when they encounter an unknown classification level or data -regulation, they MUST assume they cannot meet requirements and MUST reject or -ignore the event. +regulation, they MUST assume they cannot meet requirements and MUST reject the +event and report an error through a protocol-level mechanism. Intermediaries SHOULD NOT modify the `dataclassification`, `dataregulation`, and `datacategory` attributes.