Build with the Virtru Developer Hub

It's Your Data. Protect It. Control It. Everywhere.

Try the Demo          Learn More     

TDF Overview

The Trusted Data Format is a protective wrapper that enables object-level, secure, and auditable information sharing and protection. As an open format created by Virtru Co-Founder and CTO, Will Ackerly, TDF addresses current gaps in security, trust, and ease of use for data sharing and protection, while maintaining privacy. Virtru SDKs help create TDFs and embed them in existing applications for secure data across environments, applications, and devices.


TDF provides persistent protection that travels with the data. With TDF, organizations and data owners can tag, encrypt, revoke, expire, and audit access to data, even after content has been accessed. TDF has now been adopted across the U.S. Government as well as in enterprises—ranging from financial institutions to major media and entertainment companies —and thousands of small and medium businesses, as well as by millions of individuals to secure and audit structured and unstructured data.

Initially created for the intelligence community as IC-TDF, today TDF has evolved in sync with the modern data environment while maintaining interoperability with IC-TDF. TDF now includes more efficient encoding support (e.g., JSON and binary) and is optimized to support very large files and streaming data. These updates are described in more detail below.

How It Works

Trusted Data Format (TDF) is an open, interoperable, JSON-encoded data format for implementing object-level data protection—such as for files or emails. Virtru SDKs help implement the TDFs. A TDF file at rest can be in one of 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 an 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.

Attribute-Based Access Control (ABAC) provides persistent protection so you can implement granular policies and rules. TDF is agentless and allows file locking, content expiration, and access revocation for both structured and unstructured data. It can be invoked by users, administrators, or as part of an automated process.

Components of a TDF file

As the image below depicts, TDF protected data always takes the form of a zip or an HTML file. Regardless of which form you choose, there are always two components in a TDF file:

  • A manifest.json component. The manifest.json data structure contains all the information required to request access to the decryption key. Check out TDF3 Specification for a detailed reference on manifest.json
  • An Encrypted Payload component. This is simply the encrypted version of the protected object (e.g., a file or email).
TDFs either take the form of a zip file or an HTML file

TDFs either take the form of a zip file or an HTML file

There are three principal 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, as it is not a key component to the confidentiality cryptography of TDF as designed. Assertions can be used to add metadata (including search and discovery metadata) about an object, and optionally to cryptographically bind (sign) statements such as authorship, classification, or approval status.

Encryption Information

The encryption information provides the data control and integrity features.

Payload chunk hashes provide:

  • Data-Agnostic Protection: Enables large files encryption/decryption and streaming; encrypting large files into smaller chunks, with the encryption metadata (including integrity) of each chunk being stored in this element. A parent hash strategy against the whole ensures that no segment can be removed or re-ordered.

  • Multi-Level Control Access: Control the confidentiality of separate elements (such as paragraphs) individually, based on specified access, so that different portions of the document can be read by persons with different access levels.

  • Revocation: TDF allows the data owner to revoke or expire access to data, even after it has left your network.

Federated Key Access and Cryptographically-bound Policy provide:

  • Key Server Federation: Two or more organizations control the access keys. An array of objects allows multiple KAS servers to participate in an object key grant. Multiple KAS servers, each hosted by a different organization, can jointly control access to a TDF file. This enables organizations to jointly own, control and audit files.

  • High-Assurance Key Server: Cryptographically-bound policy and wrapped keys provide layered defenses of the key server.

  • Audit Functionality: TDF protocol and infrastructure enables logging every key request for reliable auditing and tracking of access requests. This provides an unprecedented ability to track who accesses what data, at what time, and where. The data audit can not only track by person, but also by location and device. Data can be bound to groups and individuals as well as to devices and locations.

TDF Overview

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.