fix: Overhaul #55

biscoe916 · 2025-04-03T16:39:10Z

Proposed Changes

Checklist

cassandrabailey293

this is looking great! i found a couple things that i wasn't sure we wanted to include but you would know better than I would. left those comments in case, and a few typos/links to fix but otherwise it looks good to me.

cassandrabailey293 · 2025-04-07T16:39:53Z

README.md


-* As a Zip file with extension of `.tdf`. For example, if you are trying to protect a file named `demo.jpeg`, the file will be stored as `demo.jpeg.tdf` after encryption.
-* As a HTML file with extension of `.html`. For example, if you are trying to protect a file named `demo.jpeg`, the file will be stored as `demo.jpeg.html` after encryption. An example HTML file is (here)[https://github.com/opentdf/spec/blob/master/schema/HtmlProtocolExample.html]. 
+OpenTDF represents a modernization of data-centric security concepts originally established in the **IC-TDF** (Intelligence Community Trusted Data Format) specification. While IC-TDF utilized an XML-based structure, OpenTDF adopts a more contemporary approach using JSON for its manifest, enhancing flexibility and ease of integration with modern web technologies.


probably not necessary (or wanted?) but you could link to the ICTDF spec here

cassandrabailey293 · 2025-04-07T16:41:00Z

README.md

+1. **`manifest.json`:** The metadata manifest described in the Key Concepts section. It holds instructions for decryption and access control. 
+2. **`payload`:** The encrypted data payload itself. 
+
+However, a TDF can be encoded in other ways. For example, as an HTML document:


is this "true"? like technically someone could hand roll it but do we want to mention html at all, since i dont think opentdf supports ti directly?

cassandrabailey293 · 2025-04-07T16:41:35Z

README.md

+
+While OpenTDF offers flexibility and rich metadata, NanoTDF prioritizes size efficiency for specific use cases. 
+
+**➡️ For details, please refer to the [NanoTDF Specification](../schema/nanotdf/README.md).** 


getting a 404 on this link

cassandrabailey293 · 2025-04-07T16:41:51Z

README.md

+
+## Contact
+
+For questions regarding OpenTDF, interoperability, or the specification, please reach out to [support@opentdf.io](mailto:support@opentdf.io).


who is on this mailing list?

AFAIK no one yet. We need to set it up.

cassandrabailey293 · 2025-04-07T16:43:14Z

concepts/access_control.md

+*   **Resource Attributes:** Defined within the TDF's [Policy Object](../schema/OpenTDF/policy.md) in the `dataAttributes` array. These specify the attribute instances *required* to access this specific piece of data.
+*   **Policies:** Defined by the combination of:
+    *   The `dataAttributes` required by the specific TDF.
+    *   The optional `dissem` list in the TDF's [Policy Object](../schema/OpenTDF/policy.md) acting as an initial filter.


just checking that we want to talk about dissem, maybe people will want to use it, but wanted to make sure

cassandrabailey293 · 2025-04-07T16:44:26Z

concepts/access_control.md

+
+1.  **Request Initiation:** The client presents the relevant [Key Access Object(s)](../schema/OpenTDF/key_access_object.md) from the TDF manifest to the appropriate KAS, along with the client's credentials and asserted **Entity Entitlements** (Subject Attributes).
+2.  **PEP Evaluation:** The KAS performs the following checks based on the TDF's embedded [Policy Object](../schema/OpenTDF/policy.md) (extracted from the `policy` field):
+    *   **Dissemination Check (if applicable):** If the policy's `dissem` list is present and non-empty, the PEP verifies if the requesting entity's identifier is in the list. If not, access is **denied**.


more mentions of dissem here, maybe we do want to include it but double checking

I believe we want to mention it, but we can run it by @willackerly

cassandrabailey293 · 2025-04-07T16:48:16Z

protocol/protocol.md

+2.  **Encrypt Payload:** Encrypt the original payload data using the DEK and an authenticated encryption mode (e.g., AES-256-GCM), generating an Initialization Vector (IV) and integrity tags per segment. Store the IV and segment information.
+3.  **Define Policy:** Construct the [Policy Object](../schema/OpenTDF/policy.md) JSON defining the required attributes (`dataAttributes`) and optional dissemination list (`dissem`). Base64 encode this JSON string.
+4.  **Generate Policy Binding:** Calculate the policy binding hash: `HMAC(DEK, Base64(policyJSON))` using a standard algorithm like HMAC-SHA256. Base64 encode the resulting hash.
+5.  **Prepare Optional Metadata:** If client-specific metadata needs to be passed securely to the KAS during decryption, prepare this data.


do we want to have an example of what this would be? there are some things in opentdf we ALWAYS pass right? or no?

Yea this is worded poorly. I'll update it.

Technically this is always passed to the KAS, but it's optional in the sense that a user of the SDK doesn't need to put anything in it.

cassandrabailey293 · 2025-04-07T16:50:32Z

protocol/protocol.md

+17. **Decrypt Payload:** Use the plaintext DEK and the parameters from `encryptionInformation.method` (IV) to decrypt the TDF payload. During decryption (especially with AES-GCM or streaming), simultaneously verify the integrity of each segment using the `hash` from the [Segment Object](./opentdf/segment.md) and finally verify the `rootSignature` from [`integrityInformation`](./opentdf/integrity_information.md). If any integrity check fails, abort decryption and report an error.
+18. **Securely Discard DEK:** Once the payload is decrypted or decryption fails, securely erase the plaintext DEK and any intermediate shares from memory.
+
+## Error Handling


we had an adr around this a while back... not sure if we'd wanna include that here, maybe not since we havent implemented against it much . https://github.com/virtru-corp/adr/pull/102

I might forgo linking to this ADR for a couple reasons.

It's not public

The error codes themselves aren't defined by the spec - we only define them for the purposes of our "reference implementation".

What do you think? Should be define the error codes formally here?

cassandrabailey293 · 2025-04-07T16:54:13Z

schema/OpenTDF/attributes.md

@@ -0,0 +1,18 @@
+# Attribute Object (Structure)
+
+This document describes the JSON structure representing an Attribute Instance when embedded within a [Policy Object](./policy.md). For a conceptual overview of attributes, and their role in access control, see [Access Control Concepts](../../concepts/access_control.md.md).


typo here - double .md in the access control link

biscoe916 added 21 commits April 3, 2025 11:52

first draft

c893624

restructure

628a642

new structure

ad28536

nits

ca0923a

wrong header

c71f164

updated a link

24c74d1

fixed a link

f233b17

new readme, updated nav

8105f15

mention html?? not sure.

8a61179

updated the caption

87e74fa

reordered some stuff

e463391

updated readme to include core concepts

cb8d6aa

nav

92cc605

reorg

392ea1c

small reorg

f92b724

changed header

3c4131d

reorg

ab0a3d6

temp remove

dc03122

manifest.md

0dba65e

moved some stuff

840bfe9

new files

0985869

biscoe916 requested a review from a team as a code owner April 3, 2025 16:39

biscoe916 added 8 commits April 3, 2025 12:41

version

30ffe77

removed the contribution section

9520fcc

fixed nav

e60bb1c

added mention of CIA

7548569

link fix

560f3e2

protocol

c5dc1b0

added protocol

9c36cd9

removed a diagram

7975dae

biscoe916 added 13 commits April 4, 2025 16:38

better sid def

f96b8f9

formatting error

fbe0ce9

fixed some links

05d633e

fixed a ton of links

36790f8

Fixed a bunch of links again

33750a8

fixed image

60c59ad

new image

09b7a75

more links

475cec7

removed ghost link

23266a9

Fixed some links

fe52d25

fixed a nother link, I keep thinking it's the last one...

065cc9a

fixed up the concepts docs

dd476f2

removed extra stuff

c4e694a

cassandrabailey293 requested changes Apr 7, 2025

View reviewed changes

biscoe916 added 2 commits April 7, 2025 13:09

fixed typo

d4a5b7a

changed wording around encrypted metadata

270d424

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: Overhaul #55

fix: Overhaul #55

biscoe916 commented Apr 3, 2025

cassandrabailey293 left a comment

cassandrabailey293 Apr 7, 2025

cassandrabailey293 Apr 7, 2025

cassandrabailey293 Apr 7, 2025

cassandrabailey293 Apr 7, 2025

biscoe916 Apr 7, 2025

cassandrabailey293 Apr 7, 2025

cassandrabailey293 Apr 7, 2025

biscoe916 Apr 7, 2025

cassandrabailey293 Apr 7, 2025

biscoe916 Apr 7, 2025

cassandrabailey293 Apr 7, 2025

biscoe916 Apr 7, 2025

cassandrabailey293 Apr 7, 2025


		While OpenTDF offers flexibility and rich metadata, NanoTDF prioritizes size efficiency for specific use cases.

		➡️ For details, please refer to the [NanoTDF Specification](../schema/nanotdf/README.md).


		## Contact

		For questions regarding OpenTDF, interoperability, or the specification, please reach out to [support@opentdf.io](mailto:support@opentdf.io).

		@@ -0,0 +1,18 @@
		# Attribute Object (Structure)

		This document describes the JSON structure representing an Attribute Instance when embedded within a [Policy Object](./policy.md). For a conceptual overview of attributes, and their role in access control, see [Access Control Concepts](../../concepts/access_control.md.md).

fix: Overhaul #55

Are you sure you want to change the base?

fix: Overhaul #55

Conversation

biscoe916 commented Apr 3, 2025

Proposed Changes

Checklist

cassandrabailey293 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment