From dffe2ec73449e88a1d960b5f39a87eb69a7684c5 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 10:33:50 -0800 Subject: [PATCH 01/16] feat(docs): expand TDF documentation guide (DSPX-2427) --- docs/sdks/tdf.mdx | 122 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 120 insertions(+), 2 deletions(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index af082cdf..7f71995e 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -1,10 +1,128 @@ --- sidebar_position: 4 +title: TDF --- import EncryptionTDF from '../../code_samples/tdf/encryption_ztdf.mdx' +# TDF Encryption and Decryption -# Creating TDFs +This guide explains how to work with Trusted Data Format (TDF) objects using the OpenTDF SDKs, and when to choose `zTDF` versus the full OpenTDF container format. - \ No newline at end of file +It is intended for developers who need to encrypt data with ABAC policy, decrypt data with entitlement checks, and debug common integration failures. + +## What TDF Gives You + +TDF combines encrypted payload data with policy metadata so access control can travel with the data itself. + +When you create a TDF, you are packaging: + +1. Encrypted payload bytes. +2. Policy metadata (for example attribute value FQNs). +3. Key access metadata used by the KAS to enforce decryption authorization. + +At read time, decryption succeeds only if the caller identity is entitled for the policy encoded in the TDF. + +## Choose the Right Format + +In OpenTDF documentation and code you may see both `zTDF` and TDF terminology. + +| Format | Typical SDK API | When to Use | +| --- | --- | --- | +| Full OpenTDF container (`.tdf`, zip + manifest) | `CreateTDF` / `LoadTDF` | General purpose file/data encryption, richer manifest metadata, cross-system interchange. | +| `zTDF` profile | `createZTDF` (JavaScript naming) and CLI `otdfctl encrypt/decrypt` zTDF flow | Streamlined profile used in many current workflows and examples. | + +If your team says "TDF3", in practice this typically maps to the full OpenTDF container workflow (`CreateTDF`/`LoadTDF`) in the current SDKs. + +## Encryption and Decryption Flow + +```mermaid +flowchart LR + A["Plaintext Input"] --> B["Create TDF / zTDF"] + B --> C["Attach ABAC Policy (Attributes)"] + C --> D["KAS Key Wrapping Metadata"] + D --> E["Encrypted TDF Artifact"] + E --> F["Load TDF"] + F --> G["KAS Rewrap + Policy Decision"] + G --> H["Decrypt Payload (if entitled)"] +``` + +## End-to-End Example (Go, Java, TypeScript) + +The sample below includes encrypt + decrypt flows for all three SDK ecosystems: + + + +## Adding ABAC Attributes at Encryption Time + +Policy is enforced at decrypt time, so getting attribute values right at encryption time is critical. + +Recommended pattern: + +1. Validate attribute values before encryption using [`ValidateAttributes`](/sdks/discovery#validateattributes). +2. Encrypt with those validated FQNs. +3. Ensure a subject mapping exists for identities that should decrypt. + +Related guides: + +- Attribute validation and discovery: [/sdks/discovery](/sdks/discovery) +- Subject mappings and actions: [/sdks/policy](/sdks/policy) +- Permission failure diagnosis: [/sdks/troubleshooting#permission-denied--insufficient-entitlements](/sdks/troubleshooting#permission-denied--insufficient-entitlements) + +## Decryption Patterns + +### In-memory data + +Use in-memory readers/writers when payloads are small and request-scoped. + +### File-based workflow + +Use file streams/channels for larger payloads or asynchronous pipelines (encrypt now, decrypt later in another process). + +### Offline handoff + +You can persist `.tdf` artifacts and decrypt later, as long as the decrypting identity can still reach required platform services (for example KAS and authorization dependencies) and has valid entitlements. + +## Encryption Options You Should Decide Explicitly + +For production use, avoid relying on implicit defaults. + +1. KAS endpoint configuration. +2. Attribute value set (policy scope). +3. Wrapping/encapsulation algorithm choice where supported. +4. Data handling model: in-memory vs stream/file. +5. Expected interoperability target (`zTDF` profile vs full container exchange). + +You can see concrete option usage in these repository code samples: + +- Java full TDF encryption/decryption: `code_samples/java/encrypt-example.mdx` and `code_samples/java/decrypt-example.mdx` +- Java collection nanoTDF samples: `code_samples/java/encrypt-collection-example.mdx` and `code_samples/java/decrypt-collection-example.mdx` + +## Error Handling Patterns + +Treat these as first-class integration paths, not edge cases: + +| Failure Class | Typical Symptom | What to Do | +| --- | --- | --- | +| Authentication | `Unauthenticated`, `401` | Verify credentials and OIDC/client setup. | +| TLS trust | cert validation failures | Trust local CA correctly; avoid disabling verification in production. | +| Missing entitlements | split-key/rewrap failures, `PermissionDenied` | Create/verify subject mappings for required attribute values. | +| Missing attributes | `not_found` during policy resolution | Validate attributes before encryption and create absent values. | + +For concrete SDK-specific error text and commands, use [/sdks/troubleshooting](/sdks/troubleshooting). + +## Best Practices + +1. Validate attribute FQNs before every encryption boundary where user input can influence policy. +2. Keep subject mapping creation idempotent in automation. +3. Store encrypted artifacts separately from entitlement management logic. +4. Log policy FQNs and key access identifiers (not plaintext) for observability. +5. Deactivate attributes instead of deleting them when historical TDF decryptability matters. +6. Add integration tests that perform both encrypt and decrypt with expected allow/deny identities. + +## Related Documentation + +- SDK quickstarts: [/sdks/quickstart](/sdks/quickstart) +- Discovery APIs: [/sdks/discovery](/sdks/discovery) +- Authorization APIs: [/sdks/authorization](/sdks/authorization) +- OpenTDF spec structure: [/spec/schema/opentdf](/spec/schema/opentdf) From 674ad729b0c762a6394ac324a09e26f21a8a967b Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 11:05:20 -0800 Subject: [PATCH 02/16] fix(docs): remove non-existent sample references in TDF guide --- docs/sdks/tdf.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index 7f71995e..16bed02e 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -96,7 +96,6 @@ For production use, avoid relying on implicit defaults. You can see concrete option usage in these repository code samples: - Java full TDF encryption/decryption: `code_samples/java/encrypt-example.mdx` and `code_samples/java/decrypt-example.mdx` -- Java collection nanoTDF samples: `code_samples/java/encrypt-collection-example.mdx` and `code_samples/java/decrypt-collection-example.mdx` ## Error Handling Patterns From 31bcf694e89fe6b6c26af63dd22f44c081c7898a Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 11:13:02 -0800 Subject: [PATCH 03/16] fix(docs): remove repo-path references from TDF guide --- docs/sdks/tdf.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index 16bed02e..db0b35d7 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -93,9 +93,7 @@ For production use, avoid relying on implicit defaults. 4. Data handling model: in-memory vs stream/file. 5. Expected interoperability target (`zTDF` profile vs full container exchange). -You can see concrete option usage in these repository code samples: - -- Java full TDF encryption/decryption: `code_samples/java/encrypt-example.mdx` and `code_samples/java/decrypt-example.mdx` +You can see concrete option usage in the SDK quickstarts and the multi-language end-to-end example above. ## Error Handling Patterns From 98b8bc79317bee1d68ad55f723ce698ec9e9d532 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 11:16:03 -0800 Subject: [PATCH 04/16] fix(docs): neutralize TDF guide branding language --- docs/sdks/tdf.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index db0b35d7..7c400f5c 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -7,7 +7,7 @@ import EncryptionTDF from '../../code_samples/tdf/encryption_ztdf.mdx' # TDF Encryption and Decryption -This guide explains how to work with Trusted Data Format (TDF) objects using the OpenTDF SDKs, and when to choose `zTDF` versus the full OpenTDF container format. +This guide explains how to work with Trusted Data Format (TDF) objects using the SDKs, and when to choose `zTDF` versus the full TDF container format. It is intended for developers who need to encrypt data with ABAC policy, decrypt data with entitlement checks, and debug common integration failures. @@ -25,14 +25,14 @@ At read time, decryption succeeds only if the caller identity is entitled for th ## Choose the Right Format -In OpenTDF documentation and code you may see both `zTDF` and TDF terminology. +In current documentation and code you may see both `zTDF` and TDF terminology. | Format | Typical SDK API | When to Use | | --- | --- | --- | -| Full OpenTDF container (`.tdf`, zip + manifest) | `CreateTDF` / `LoadTDF` | General purpose file/data encryption, richer manifest metadata, cross-system interchange. | +| Full TDF container (`.tdf`, zip + manifest) | `CreateTDF` / `LoadTDF` | General purpose file/data encryption, richer manifest metadata, cross-system interchange. | | `zTDF` profile | `createZTDF` (JavaScript naming) and CLI `otdfctl encrypt/decrypt` zTDF flow | Streamlined profile used in many current workflows and examples. | -If your team says "TDF3", in practice this typically maps to the full OpenTDF container workflow (`CreateTDF`/`LoadTDF`) in the current SDKs. +If your team says "TDF3", in practice this typically maps to the full container workflow (`CreateTDF`/`LoadTDF`) in the current SDKs. ## Encryption and Decryption Flow @@ -122,4 +122,4 @@ For concrete SDK-specific error text and commands, use [/sdks/troubleshooting](/ - SDK quickstarts: [/sdks/quickstart](/sdks/quickstart) - Discovery APIs: [/sdks/discovery](/sdks/discovery) - Authorization APIs: [/sdks/authorization](/sdks/authorization) -- OpenTDF spec structure: [/spec/schema/opentdf](/spec/schema/opentdf) +- TDF schema spec: [/spec/schema/opentdf](/spec/schema/opentdf) From add5bae49d71d201c53149934ee2068f91637503 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 11:50:56 -0800 Subject: [PATCH 05/16] fix(docs): improve TDF mermaid diagram readability --- docs/sdks/tdf.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index 7c400f5c..e7c03c24 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -37,14 +37,14 @@ If your team says "TDF3", in practice this typically maps to the full container ## Encryption and Decryption Flow ```mermaid -flowchart LR - A["Plaintext Input"] --> B["Create TDF / zTDF"] - B --> C["Attach ABAC Policy (Attributes)"] - C --> D["KAS Key Wrapping Metadata"] - D --> E["Encrypted TDF Artifact"] - E --> F["Load TDF"] - F --> G["KAS Rewrap + Policy Decision"] - G --> H["Decrypt Payload (if entitled)"] +flowchart TB + A["1. Plaintext input"] --> B["2. Create TDF or zTDF"] + B --> C["3. Attach ABAC attributes"] + C --> D["4. Add KAS key wrapping metadata"] + D --> E["5. Encrypted TDF artifact"] + E --> F["6. Load artifact for read"] + F --> G["7. KAS rewrap and policy check"] + G --> H["8. Decrypt payload if entitled"] ``` ## End-to-End Example (Go, Java, TypeScript) From 7610238ab1d4e18be3d8e8a4eacef1b93a9fef7a Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 11:55:22 -0800 Subject: [PATCH 06/16] fix(docs): link subject mapping reference in TDF guide --- docs/sdks/tdf.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index e7c03c24..8c8b85a5 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -61,7 +61,7 @@ Recommended pattern: 1. Validate attribute values before encryption using [`ValidateAttributes`](/sdks/discovery#validateattributes). 2. Encrypt with those validated FQNs. -3. Ensure a subject mapping exists for identities that should decrypt. +3. Ensure a [subject mapping](/components/policy/subject_mappings) exists for identities that should decrypt. Related guides: From c6b49bbe6648e4c3d2ac23243c16f4e7bea2ddd4 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 12:10:39 -0800 Subject: [PATCH 07/16] fix(docs): add solution links in TDF error handling table --- docs/sdks/tdf.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index 8c8b85a5..2f81898c 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -101,10 +101,10 @@ Treat these as first-class integration paths, not edge cases: | Failure Class | Typical Symptom | What to Do | | --- | --- | --- | -| Authentication | `Unauthenticated`, `401` | Verify credentials and OIDC/client setup. | -| TLS trust | cert validation failures | Trust local CA correctly; avoid disabling verification in production. | -| Missing entitlements | split-key/rewrap failures, `PermissionDenied` | Create/verify subject mappings for required attribute values. | -| Missing attributes | `not_found` during policy resolution | Validate attributes before encryption and create absent values. | +| Authentication | `Unauthenticated`, `401` | Verify credentials and OIDC/client setup. See [Authentication Failed](/sdks/troubleshooting#authentication-failed). | +| TLS trust | cert validation failures | Trust local CA correctly; avoid disabling verification in production. See [Certificate Errors](/sdks/troubleshooting#certificate-errors-ssltls). | +| Missing entitlements | split-key/rewrap failures, `PermissionDenied` | Create/verify subject mappings for required attribute values. See [Permission Denied](/sdks/troubleshooting#permission-denied--insufficient-entitlements). | +| Missing attributes | `not_found` during policy resolution | Validate attributes before encryption and create absent values. See [ValidateAttributes](/sdks/discovery#validateattributes) and [Resource Not Found](/sdks/troubleshooting#resource-not-found). | For concrete SDK-specific error text and commands, use [/sdks/troubleshooting](/sdks/troubleshooting). From 9b255e2153e9f7dce0b79c665994452ce1c6243b Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 12:13:27 -0800 Subject: [PATCH 08/16] fix(docs): clarify TDF format table method column --- docs/sdks/tdf.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index 2f81898c..b7b74b41 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -27,7 +27,7 @@ At read time, decryption succeeds only if the caller identity is entitled for th In current documentation and code you may see both `zTDF` and TDF terminology. -| Format | Typical SDK API | When to Use | +| Format | Common method names | When to Use | | --- | --- | --- | | Full TDF container (`.tdf`, zip + manifest) | `CreateTDF` / `LoadTDF` | General purpose file/data encryption, richer manifest metadata, cross-system interchange. | | `zTDF` profile | `createZTDF` (JavaScript naming) and CLI `otdfctl encrypt/decrypt` zTDF flow | Streamlined profile used in many current workflows and examples. | From 61446dab2c6d5850be4b9bee7f1eb55b9e84dc3c Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 12:15:14 -0800 Subject: [PATCH 09/16] fix(docs): clarify in-memory decryption pattern examples --- docs/sdks/tdf.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index b7b74b41..e6398410 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -74,6 +74,7 @@ Related guides: ### In-memory data Use in-memory readers/writers when payloads are small and request-scoped. +Examples include `bytes.Buffer` (Go), `ByteArrayInputStream`/`ByteArrayOutputStream` (Java), and `Buffer`/`ReadableStream` (TypeScript). ### File-based workflow From 15d701ee7c1127f4701b88f43d6e49365dfae6cb Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 12:31:36 -0800 Subject: [PATCH 10/16] fix(docs): align TDF claims with merged platform behavior --- docs/sdks/tdf.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index e6398410..a455d814 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -29,8 +29,7 @@ In current documentation and code you may see both `zTDF` and TDF terminology. | Format | Common method names | When to Use | | --- | --- | --- | -| Full TDF container (`.tdf`, zip + manifest) | `CreateTDF` / `LoadTDF` | General purpose file/data encryption, richer manifest metadata, cross-system interchange. | -| `zTDF` profile | `createZTDF` (JavaScript naming) and CLI `otdfctl encrypt/decrypt` zTDF flow | Streamlined profile used in many current workflows and examples. | +| TDF / zTDF workflows | `CreateTDF` / `LoadTDF` | Use for encryption/decryption workflows in the current Go SDK; behavior differs by policy/profile configuration. | If your team says "TDF3", in practice this typically maps to the full container workflow (`CreateTDF`/`LoadTDF`) in the current SDKs. @@ -59,7 +58,7 @@ Policy is enforced at decrypt time, so getting attribute values right at encrypt Recommended pattern: -1. Validate attribute values before encryption using [`ValidateAttributes`](/sdks/discovery#validateattributes). +1. Validate attribute value FQNs before encryption using `GetAttributeValuesByFqns` (or the equivalent helper exposed by your SDK wrapper). 2. Encrypt with those validated FQNs. 3. Ensure a [subject mapping](/components/policy/subject_mappings) exists for identities that should decrypt. @@ -105,10 +104,12 @@ Treat these as first-class integration paths, not edge cases: | Authentication | `Unauthenticated`, `401` | Verify credentials and OIDC/client setup. See [Authentication Failed](/sdks/troubleshooting#authentication-failed). | | TLS trust | cert validation failures | Trust local CA correctly; avoid disabling verification in production. See [Certificate Errors](/sdks/troubleshooting#certificate-errors-ssltls). | | Missing entitlements | split-key/rewrap failures, `PermissionDenied` | Create/verify subject mappings for required attribute values. See [Permission Denied](/sdks/troubleshooting#permission-denied--insufficient-entitlements). | -| Missing attributes | `not_found` during policy resolution | Validate attributes before encryption and create absent values. See [ValidateAttributes](/sdks/discovery#validateattributes) and [Resource Not Found](/sdks/troubleshooting#resource-not-found). | +| Missing attributes | `not_found` during policy resolution | Validate attribute value FQNs before encryption and create absent values. If an attribute definition allows traversal, encryption can proceed with definition-level scope while decryption remains blocked until the specific value exists. See [Discovery APIs](/sdks/discovery) and [Resource Not Found](/sdks/troubleshooting#resource-not-found). | For concrete SDK-specific error text and commands, use [/sdks/troubleshooting](/sdks/troubleshooting). +For the Go SDK specifically, `LoadTDF` parses and prepares the reader. KAS rewrap and policy authorization happen when payload key unwrap is triggered by `Init()`, `Read()`, or `WriteTo()`. + ## Best Practices 1. Validate attribute FQNs before every encryption boundary where user input can influence policy. From 1d61c7d0060a0ef629c71aefc0f44dd2cbdc7dbb Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 12:48:58 -0800 Subject: [PATCH 11/16] fix(docs): replace API wording with SDK terminology on TDF page --- docs/sdks/tdf.mdx | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index a455d814..c48ade1a 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -7,11 +7,9 @@ import EncryptionTDF from '../../code_samples/tdf/encryption_ztdf.mdx' # TDF Encryption and Decryption -This guide explains how to work with Trusted Data Format (TDF) objects using the SDKs, and when to choose `zTDF` versus the full TDF container format. +This page covers TDF encryption/decryption behavior, SDK method usage patterns, and operational checks. -It is intended for developers who need to encrypt data with ABAC policy, decrypt data with entitlement checks, and debug common integration failures. - -## What TDF Gives You +## Overview TDF combines encrypted payload data with policy metadata so access control can travel with the data itself. @@ -23,13 +21,13 @@ When you create a TDF, you are packaging: At read time, decryption succeeds only if the caller identity is entitled for the policy encoded in the TDF. -## Choose the Right Format +## Formats and SDK Methods In current documentation and code you may see both `zTDF` and TDF terminology. | Format | Common method names | When to Use | | --- | --- | --- | -| TDF / zTDF workflows | `CreateTDF` / `LoadTDF` | Use for encryption/decryption workflows in the current Go SDK; behavior differs by policy/profile configuration. | +| TDF / zTDF workflows | `CreateTDF` / `LoadTDF` | Use for encryption/decryption workflows; behavior differs by policy/profile configuration. | If your team says "TDF3", in practice this typically maps to the full container workflow (`CreateTDF`/`LoadTDF`) in the current SDKs. @@ -52,7 +50,7 @@ The sample below includes encrypt + decrypt flows for all three SDK ecosystems: -## Adding ABAC Attributes at Encryption Time +## ABAC Attributes Policy is enforced at decrypt time, so getting attribute values right at encryption time is critical. @@ -83,7 +81,7 @@ Use file streams/channels for larger payloads or asynchronous pipelines (encrypt You can persist `.tdf` artifacts and decrypt later, as long as the decrypting identity can still reach required platform services (for example KAS and authorization dependencies) and has valid entitlements. -## Encryption Options You Should Decide Explicitly +## Encryption Options For production use, avoid relying on implicit defaults. @@ -95,7 +93,7 @@ For production use, avoid relying on implicit defaults. You can see concrete option usage in the SDK quickstarts and the multi-language end-to-end example above. -## Error Handling Patterns +## Error Handling Treat these as first-class integration paths, not edge cases: @@ -104,7 +102,7 @@ Treat these as first-class integration paths, not edge cases: | Authentication | `Unauthenticated`, `401` | Verify credentials and OIDC/client setup. See [Authentication Failed](/sdks/troubleshooting#authentication-failed). | | TLS trust | cert validation failures | Trust local CA correctly; avoid disabling verification in production. See [Certificate Errors](/sdks/troubleshooting#certificate-errors-ssltls). | | Missing entitlements | split-key/rewrap failures, `PermissionDenied` | Create/verify subject mappings for required attribute values. See [Permission Denied](/sdks/troubleshooting#permission-denied--insufficient-entitlements). | -| Missing attributes | `not_found` during policy resolution | Validate attribute value FQNs before encryption and create absent values. If an attribute definition allows traversal, encryption can proceed with definition-level scope while decryption remains blocked until the specific value exists. See [Discovery APIs](/sdks/discovery) and [Resource Not Found](/sdks/troubleshooting#resource-not-found). | +| Missing attributes | `not_found` during policy resolution | Validate attribute value FQNs before encryption and create absent values. If an attribute definition allows traversal, encryption can proceed with definition-level scope while decryption remains blocked until the specific value exists. See [Discovery docs](/sdks/discovery) and [Resource Not Found](/sdks/troubleshooting#resource-not-found). | For concrete SDK-specific error text and commands, use [/sdks/troubleshooting](/sdks/troubleshooting). @@ -122,6 +120,6 @@ For the Go SDK specifically, `LoadTDF` parses and prepares the reader. KAS rewra ## Related Documentation - SDK quickstarts: [/sdks/quickstart](/sdks/quickstart) -- Discovery APIs: [/sdks/discovery](/sdks/discovery) -- Authorization APIs: [/sdks/authorization](/sdks/authorization) +- Discovery docs: [/sdks/discovery](/sdks/discovery) +- Authorization docs: [/sdks/authorization](/sdks/authorization) - TDF schema spec: [/spec/schema/opentdf](/spec/schema/opentdf) From d9a805805b3d49aa9d2a83e58739a224f34dcd18 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 12:53:41 -0800 Subject: [PATCH 12/16] fix(docs): remove TDF vs zTDF format section from TDF page --- docs/sdks/tdf.mdx | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index c48ade1a..56643d6f 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -21,16 +21,6 @@ When you create a TDF, you are packaging: At read time, decryption succeeds only if the caller identity is entitled for the policy encoded in the TDF. -## Formats and SDK Methods - -In current documentation and code you may see both `zTDF` and TDF terminology. - -| Format | Common method names | When to Use | -| --- | --- | --- | -| TDF / zTDF workflows | `CreateTDF` / `LoadTDF` | Use for encryption/decryption workflows; behavior differs by policy/profile configuration. | - -If your team says "TDF3", in practice this typically maps to the full container workflow (`CreateTDF`/`LoadTDF`) in the current SDKs. - ## Encryption and Decryption Flow ```mermaid From bdbfb3ce661e88b9fbed222fabe73eadb721aa69 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 12:55:54 -0800 Subject: [PATCH 13/16] feat(docs): add SDK method reference section to TDF page --- docs/sdks/tdf.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index 56643d6f..eae22aa9 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -21,6 +21,16 @@ When you create a TDF, you are packaging: At read time, decryption succeeds only if the caller identity is entitled for the policy encoded in the TDF. +## SDK Method Reference + +The core methods shown in current SDK docs and samples are: + +| Operation | Go | Java | TypeScript | +| --- | --- | --- | --- | +| Encrypt to TDF | `CreateTDF` | `createTDF` | `createZTDF` | +| Load/read encrypted artifact | `LoadTDF` | `loadTDF` | `read` | +| Emit decrypted payload | `WriteTo` (reader) | `readPayload` (reader) | consume returned `DecoratedStream` | + ## Encryption and Decryption Flow ```mermaid From 6f2b320ce49d59a2f8347d19f1aceecb019297bf Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 12:56:38 -0800 Subject: [PATCH 14/16] feat(docs): add full TDF SDK method inventory --- docs/sdks/tdf.mdx | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index eae22aa9..180868b5 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -23,13 +23,34 @@ At read time, decryption succeeds only if the caller identity is entitled for th ## SDK Method Reference -The core methods shown in current SDK docs and samples are: - -| Operation | Go | Java | TypeScript | -| --- | --- | --- | --- | -| Encrypt to TDF | `CreateTDF` | `createTDF` | `createZTDF` | -| Load/read encrypted artifact | `LoadTDF` | `loadTDF` | `read` | -| Emit decrypted payload | `WriteTo` (reader) | `readPayload` (reader) | consume returned `DecoratedStream` | +### Go SDK (platform code) + +| Method | Purpose | +| --- | --- | +| `SDK.CreateTDF` | Encrypt input and write a TDF artifact. | +| `SDK.CreateTDFContext` | Context-aware version of `CreateTDF`. | +| `SDK.LoadTDF` | Load/parse TDF and return a `Reader`. | +| `TDFObject.Size` | Return generated TDF size. | +| `TDFObject.Manifest` | Return manifest from created TDF object. | +| `Reader.Manifest` | Return loaded manifest. | +| `Reader.Init` | Perform network/key unwrap initialization before reads. | +| `Reader.Read` | Read decrypted payload bytes sequentially. | +| `Reader.Seek` | Move read cursor for `Read`/`WriteTo`. | +| `Reader.WriteTo` | Stream decrypted payload to a writer. | +| `Reader.ReadAt` | Read decrypted payload bytes at offset. | +| `Reader.UnencryptedMetadata` | Return decrypted metadata from manifest. | +| `Reader.Policy` | Return policy object from manifest. | +| `Reader.DataAttributes` | Return data attribute FQNs in policy. | +| `Reader.Obligations` | Return required obligations for access. | +| `Reader.UnsafePayloadKeyRetrieval` | Return payload key (unsafe/debug use). | + +### Java and TypeScript (methods currently documented in this repo) + +| Operation | Java | TypeScript | +| --- | --- | --- | +| Encrypt | `createTDF` | `createZTDF` | +| Load/read encrypted artifact | `loadTDF` | `read` | +| Emit decrypted payload | `readPayload` | consume returned `DecoratedStream` | ## Encryption and Decryption Flow From 95e13f1f4f4598045bab390979374293a18aa3b9 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 12:58:02 -0800 Subject: [PATCH 15/16] feat(docs): add method usage examples to TDF reference --- docs/sdks/tdf.mdx | 50 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index 180868b5..0f55dc06 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -52,6 +52,56 @@ At read time, decryption succeeds only if the caller identity is entitled for th | Load/read encrypted artifact | `loadTDF` | `read` | | Emit decrypted payload | `readPayload` | consume returned `DecoratedStream` | +## Method Details + +### `CreateTDF` / `createTDF` / `createZTDF` + +Encrypts input data and returns/writes a TDF artifact. + +```go +manifest, err := client.CreateTDF(outputWriter, inputReader /* opts... */) +``` + +```java +sdk.createTDF(inputStream, outputStream, tdfConfig); +``` + +```typescript +const tdf = await client.createZTDF(opts); +``` + +### `LoadTDF` / `loadTDF` / `read` + +Loads encrypted TDF content and prepares it for decryption. + +```go +tdfReader, err := client.LoadTDF(bytes.NewReader(tdfBytes) /* opts... */) +``` + +```java +var reader = sdk.loadTDF(fileChannel, readerConfig); +``` + +```typescript +const decoratedStream = await client.read(readOptions); +``` + +### `WriteTo` / `readPayload` / consume `DecoratedStream` + +Produces decrypted payload bytes after key unwrap and policy checks succeed. + +```go +_, err = tdfReader.WriteTo(&decryptedBuffer) +``` + +```java +reader.readPayload(decryptedOutput); +``` + +```typescript +const decrypted = await new Response(decoratedStream).text(); +``` + ## Encryption and Decryption Flow ```mermaid From 755983480293453d7ff2ff3623f4cd55f3afbcf3 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Fri, 27 Feb 2026 13:00:42 -0800 Subject: [PATCH 16/16] fix(docs): use tabbed language format in TDF method examples --- docs/sdks/tdf.mdx | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx index 0f55dc06..319e8ca3 100644 --- a/docs/sdks/tdf.mdx +++ b/docs/sdks/tdf.mdx @@ -4,6 +4,8 @@ title: TDF --- import EncryptionTDF from '../../code_samples/tdf/encryption_ztdf.mdx' +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # TDF Encryption and Decryption @@ -58,50 +60,86 @@ At read time, decryption succeeds only if the caller identity is entitled for th Encrypts input data and returns/writes a TDF artifact. + + + ```go manifest, err := client.CreateTDF(outputWriter, inputReader /* opts... */) ``` + + + ```java sdk.createTDF(inputStream, outputStream, tdfConfig); ``` + + + ```typescript const tdf = await client.createZTDF(opts); ``` + + + ### `LoadTDF` / `loadTDF` / `read` Loads encrypted TDF content and prepares it for decryption. + + + ```go tdfReader, err := client.LoadTDF(bytes.NewReader(tdfBytes) /* opts... */) ``` + + + ```java var reader = sdk.loadTDF(fileChannel, readerConfig); ``` + + + ```typescript const decoratedStream = await client.read(readOptions); ``` + + + ### `WriteTo` / `readPayload` / consume `DecoratedStream` Produces decrypted payload bytes after key unwrap and policy checks succeed. + + + ```go _, err = tdfReader.WriteTo(&decryptedBuffer) ``` + + + ```java reader.readPayload(decryptedOutput); ``` + + + ```typescript const decrypted = await new Response(decoratedStream).text(); ``` + + + ## Encryption and Decryption Flow ```mermaid