Trusted Data Format Specification

Trusted Data Format (TDF) is an Open, Interoperable data format for implementing Data Centric Security for objects (such as files or emails). This repository specifies the protocols and schemas required for TDF operation. Versioning of this spec follows the Semver standard.

OpenTDF derives its modern JSON-encoded format from the TDF XML Specification. If you are interested in interoperability between OpenTDF and Base TDF XML or community-specific implementations, please contact us.

Documentation

• Schema - Schema definitions for common TDF data objects.
• Protocol - High-level design of the TDF architecture and process workflows.

Contributions

Please see the contribution guidelines for proposing changes and submitting feedback.

Features and Capabilities

1. Strong Encryption

TDF supports strong encryption of the data as well as strong protections for the encryption keys.

2. Attribute Based Access Control (ABAC)

TDF protocol supports ABAC. This allows TDF protocol to implement policy driven and highly scalable access control mechanism.

3. Control

TDF allows the data owner (or org's administrator) to revoke or expire access to data, even after it has left your org's boundaries.

4. End to end auditability

TDF protocol and infrastructure enables logging every key request - effectively adding the most reliable auditing and tracking of access requests.

5. Streaming and Support for Large Files

TDF supports protection (encryption and decryption) of very large files. This is done by supporting streaming.

6. Policy Binding

TDF format provides support for cryptographic binding between payload and metadata via public key-based signatures. This guarantees that the Policy Object has not been tampered with.

7. Offline Create

Thanks to the assurances provided by Policy Binding described above, TDF-enabled clients can create TDFs without actively connecting to the key server (in other words, no access to the internet). The offline created TDF can be sent to anyone via offline methods or when the device has access to internet again.

8. Key Server Federation

Multiple KAS servers, each hosted by a different organization, can jointly control access to a TDF file. This enables organizations to jointly own, control, audit files in a zero trust manner.

Meet TDF

A TDF file at rest can be in one of the two forms:

• 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].

Components of a TDF file

Irrespective of whether the TDF file is composed as a Zip or HTML, there are always two components in a TDF file:

• A manifest.json component. The manifest.json data structure has all the information anyone would need to request access to decryption key. Be sure to check out the TDF3 Schemas for a detailed reference on manifest.json
• Encrypted Payload component. This is simply the encrypted version of the object (say a file or email) being protected.

TDF composed as Zip and HTML file.

Principle Elements in manifest.json file

There are three principle element types within a TDF's manifest.json component:

• Encryption Information: for encrypting, signing, or integrity binding of Payloads and Assertions
• Payload Reference(s): reference(s) to the encrypted payload
• Assertion(s): statement(s) about payload(s); this is optional and not shown below.

A TDF file with manifest.json component and encrypted payload component.

What's new in TDF3? A deeper look.

TDF's newest version, TDF3 adds powerful new features on top of existing capabilities. Below is a summary of what capabilities are unlocked by each new top level element within encryption information.

1. Streaming and Support for Large Files"

In order to support large file use cases, including streamability with high integrity, we added integrityInformation as an element to Encryption Information. Below is a look at what it looks like in TDF3 manifest.json file.

2. Policy Binding and Offline Create

With embedding cryptographically bound policy and wrapped keys, we enable a high assurance key server.

3. Key Server Federation

Want to protect files such that two (or more) organizations control the keys? It is now possible with TDF3. keyAccess object in particular allows for array of objects, which can allow for multiple KAS servers to participate in an object key grant.