diff --git a/README.md b/README.md index af64dc3..30ba4d5 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,134 @@ -# Trusted Data Format Specification +# OpenTDF 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](https://semver.org/). +**The Open, Interoperable Standard for Data-Centric Security** -OpenTDF derives its modern JSON-encoded format from the [TDF XML Specification](https://www.dni.gov/index.php/who-we-are/organizations/ic-cio/ic-cio-related-menus/ic-cio-related-links/ic-technical-specifications/trusted-data-format). If you are interested in interoperability between OpenTDF and Base TDF XML or community-specific implementations, please [contact us](mailto:support@opentdf.io). +[![SemVer](https://img.shields.io/badge/SemVer-4.3.0-brightgreen.svg)](https://semver.org/spec/v2.0.1.html) +## Introduction -## Documentation -* [Schema](schema/) - Schema definitions for common TDF data objects. -* [Protocol](protocol/) - High-level design of the TDF architecture and process workflows. +OpenTDF (Trusted Data Format) defines an open and interoperable format for embedding data protection directly into data objects themselves (like files or emails). This enables robust **data-centric security**, ensuring data remains protected wherever it travels. -## Contributions -Please see the [contribution guidelines](CONTRIBUTING.md) for proposing changes and submitting feedback. +This repository contains the official specification for OpenTDF, including the data format, cryptography, and protocols. It serves as the definitive reference for: -## Features and Capabilities +* **Developers** building applications or SDKs that create, consume, or manage TDF objects. +* **Organizations** implementing data protection solutions needing a standard for interoperability and integration. +* **Partners** participating in federated ecosystems where consistent data protection across organizational boundaries is crucial. -### 1. Strong Encryption -TDF supports strong encryption of the data as well as strong protections for the encryption keys. +[Client SDKs and server-side services](https://github.com/opentdf/platform) can be built upon this OpenTDF specification, ensuring standards-based security and enabling seamless interaction between different systems and organizations in a federated environment. -### 2. Attribute Based Access Control (ABAC) -TDF protocol supports ABAC. This allows TDF protocol to implement policy driven and highly scalable access control mechanism. +OpenTDF derives its modern JSON-encoded format from the original [TDF XML Specification](https://www.dni.gov/index.php/who-we-are/organizations/ic-cio/ic-cio-related-menus/ic-cio-related-links/ic-technical-specifications/trusted-data-format). For details on interoperability with legacy TDF XML formats, please [contact us](mailto:support@opentdf.io). -### 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. +**Versioning:** This specification adheres to the [Semantic Versioning 2.0.0](https://semver.org/) standard. -### 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. +## Navigation -### 5. Streaming and Support for Large Files -TDF supports protection (encryption and decryption) of very large files. This is done by supporting streaming. +- [Specification Details](#specification-details) + - [Schema (`schema/`)](schema/) + - [Protocol (`protocol/`)](protocol/protocol.md) + - [Concepts (`concepts/`)](concepts/) +- [Lineage and Usage](#lineage-and-usage) +- [Key Concepts](#key-concepts) +- [Core Features & Capabilities](#core-features--capabilities) +- [Security Principles: The C.I.A. Triad](#security-principles-the-cia-triad) +- [TDF Structure](#tdf-structure) +- [NanoTDF](#nanotdf-a-compact-binary-format) +- [Reference Implementation & SDKs](#reference-implementation--sdks) +- [Contact](#contact) -### 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. +## Specification Details -### 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. +The detailed technical specification is organized into the following sections: -### 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. +* **[Schema (`schema/`)](schema/):** Defines the JSON schemas for the `manifest.json` and its constituent objects (like `EncryptionInformation`, `KeyAccess`, `PolicyObject`, etc.). This is the reference for the data structure format. +* **[Protocol (`protocol/`)](protocol/):** Describes the high-level architecture, process workflows (e.g., key requests, unwrapping), and interactions between clients, Key Access Servers (KAS), and Identity Providers. +* **[Concepts (`concepts/`)](concepts/):** Contains detailed explanations of core concepts including access control and security principles. +Developers should consult these sections for implementation details regarding data formats, cryptographic operations, and protocol interactions. -## Meet TDF -A TDF file at rest can be in one of the two forms: +## Lineage and Usage -* 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. -### 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](schema/) 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. - -![zip](https://files.readme.io/5af8aee-Zip_and_HTML.png "Zip and HTML") +Furthermore, OpenTDF serves as the foundational layer for other specialized data formats. Notably, **ZTDF** (Zero Trust Data Format), developed within NATO contexts, builds directly upon the OpenTDF specification. ZTDF extends OpenTDF by mandating the inclusion of specific cryptographic assertions required for NATO use cases, ensuring compliance with their operational requirements. -_TDF composed as Zip and HTML file._ +The detailed specifications for IC-TDF and ZTDF are maintained separately and are not covered within this document. -### Principle Elements in manifest.json file +## Key Concepts -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. +At its core, OpenTDF wraps sensitive data within a protective layer. This layer includes: -![comps](https://files.readme.io/05edbb5-Screen_Shot_2018-12-10_at_9.08.21_AM.png "Components") +1. **Encrypted Payload:** The original data, strongly encrypted. +2. **Metadata Manifest:** A `manifest.json` file containing crucial information, such as: + * How the payload was encrypted. + * Where to retrieve the decryption key (Key Access information). + * The access control policy governing the data. + * Optionally, cryptographic assertions about the data or policy. -_A TDF file with manifest.json component and encrypted payload component._ +This structure allows fine-grained control and auditing, independent of underlying storage or transport systems. +To learn more about access control, and what makes OpenTDF secure, reference the following sections: +* [Access Control](./concepts/access_control.md) +* [Security](./concepts/security.md) -## 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. +## Core Features & Capabilities -### 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. +OpenTDF is designed to provide comprehensive data security through the following features: -![streaming](https://files.readme.io/d84d456-Screen_Shot_2018-12-10_at_9.12.05_AM.png "Streaming") +* **Strong Encryption:** Utilizes robust, modern cryptographic algorithms to protect both the data payload and the encryption keys themselves. +* **Attribute-Based Access Control (ABAC):** Enables highly scalable and flexible access control based on attributes of users, data, and the environment, defined within the TDF's policy. +* **Persistent Policy Enforcement:** Access policies are bound to the data, allowing data owners or administrators to manage access even after the data has been shared outside organizational boundaries. +* **End-to-End Auditability:** The protocol facilitates comprehensive logging of key requests, providing a reliable audit trail of data access attempts. +* **Large File & Streaming Support:** Efficiently handles large data objects through secure streaming mechanisms, maintaining integrity throughout the process. +* **Policy Integrity:** Cryptographically binds the access policy defined in the manifest to the key access information, preventing policy tampering after creation. +* **Offline Creation:** Allows TDF objects to be created securely by clients even without immediate network connectivity to a key server, thanks to policy binding assurances. +* **Federated Key Management:** Supports scenarios where multiple Key Access Servers (KAS), potentially hosted by different organizations, can collaboratively manage access to a single TDF object, enabling secure cross-domain collaboration in a zero-trust manner. -### 2. Policy Binding and Offline Create -With embedding cryptographically bound policy and wrapped keys, we enable a high assurance key server. +## Security Principles: The C.I.A. Triad -![offline](https://files.readme.io/f5fb283-Screen_Shot_2018-12-10_at_9.15.27_AM.png "Offline create") +OpenTDF is designed with the fundamental security principles of Confidentiality, Integrity, and Availability (C.I.A.) at its core: -### 3. Key Server Federation -Want to protect files such that two (or more) organizations control the keys? It is now possible with TDF3. [keyAccess](schema/tdf/KeyAccessObject.md) object in particular allows for array of objects, which can allow for multiple KAS servers to participate in an object key grant. +* **Confidentiality:** Ensures that sensitive data is only accessible to authorized users through strong encryption and attribute-based access control. +* **Integrity:** Maintains data authenticity and prevents unauthorized modifications through cryptographic binding of policies and payloads. +* **Availability:** Enables secure access to protected data through distributed key management and offline creation capabilities. + +These principles work together to provide comprehensive data protection while maintaining usability and accessibility for authorized users. + +## TDF Structure + +By default, a TDF object is packaged as a standard Zip archive file, typically using the `.tdf` extension appended to the original filename. This archive contains two primary components: + +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: + +![TDF Structure Illustration](https://files.readme.io/5af8aee-Zip_and_HTML.png "TDF composed as Zip and HTML file") +_A TDF object can be packaged as a standard ZIP, or as an HTML document_ + +## NanoTDF: A Compact Binary Format + +Alongside the primary OpenTDF specification based on JSON manifests, this project also defines **NanoTDF**. NanoTDF is a **compact binary format** designed specifically for resource-constrained environments (e.g., IoT devices, scenarios with limited bandwidth, storage, or processing power) where the overhead of the standard Zip/JSON format might be prohibitive. + +It achieves minimal size by using a highly optimized binary structure and relying exclusively on Elliptic Curve Cryptography (ECC). + +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).** + +## Reference Implementation & SDKs + +A robust, open-source reference implementation of the OpenTDF specification is actively developed and maintained at **[opentdf/platform](https://github.com/opentdf/platform)**. + +This platform provides: + +* **Client SDKs:** Ready-to-use libraries for integrating TDF capabilities into applications: + * **Java** + * **JavaScript** + * **Go** +* **Server Components:** Example implementations of backend services like the Key Access Server (KAS). + +Developers can use this platform as a practical guide, a starting point for their own implementations, or directly leverage the provided SDKs. + +## Contact + +For questions regarding OpenTDF, interoperability, or the specification, please reach out to [support@opentdf.io](mailto:support@opentdf.io). \ No newline at end of file diff --git a/concepts/access_control.md b/concepts/access_control.md new file mode 100644 index 0000000..80f9c0e --- /dev/null +++ b/concepts/access_control.md @@ -0,0 +1,72 @@ +# OpenTDF Access Control Concepts (ABAC) + +OpenTDF implements a sophisticated access control model known as **Attribute-Based Access Control (ABAC)**. This approach provides fine-grained, flexible, and scalable authorization for data protection. + +## What is ABAC? + +Attribute-Based Access Control is a security paradigm where access rights are granted based on the evaluated **attributes** of entities involved in an access request, rather than solely on roles or explicit permissions lists. Key components include: + +* **Subject Attributes:** Characteristics of the entity requesting access (e.g., user's clearance, department, nationality, group memberships). +* **Resource Attributes:** Characteristics of the data or resource being accessed (e.g., data classification, sensitivity level, project code). +* **Policies:** Rules that define allowable actions by comparing subject, resource, and potentially environment attributes (e.g., "Allow access if subject's clearance >= resource's classification AND subject is in department 'X'"). +* **Policy Enforcement Point (PEP):** The logical component that evaluates the policies against the attributes and makes the final access decision (grant or deny). + +ABAC offers significant advantages over traditional models, enabling dynamic access decisions that adapt to changing conditions without needing constant updates to user roles or access control lists (ACLs). + +## OpenTDF's Implementation of ABAC + +OpenTDF embeds ABAC directly into the data's protection layer. Here's how its components map to ABAC concepts: + +* **Subject Attributes:** Represented by **Entity Entitlements**. These are the attribute instances asserted by the identity system or client about the user/entity requesting access. They are provided *to* the PEP during an access request. +* **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. + * **Attribute Definitions** managed externally by Attribute Authorities, which specify the *rules* (e.g., AllOf, AnyOf, Hierarchy) for comparing subject and resource attributes. +* **Policy Enforcement Point (PEP):** Typically resides within the Key Access Server (KAS) or associated logic. It receives the TDF's policy requirements, the subject's entitlements, retrieves the relevant Attribute Definitions, and makes the authorization decision before releasing a key. + +## OpenTDF Attribute Representation + +To ensure interoperability and clarity, OpenTDF represents attributes as **URIs (Uniform Resource Identifiers)**. + +The standard structure is: +`{Attribute Namespace}/attr/{Attribute Name}/value/{Attribute Value}` + +**Components:** + +| Component | Example Value | Description | Globally Unique? | +| :--------------------------- | :----------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :--------------- | +| **Attribute Namespace** | `https://example.com` | Typically a domain controlled by the authoritative source of the attribute definition. Recommended to use a stable, controlled namespace. | No (by itself) | +| **Attribute Canonical Name** | `https://example.com/attr/classification` | Combination of Namespace and Name (`{Namespace}/attr/{Name}`). **This MUST be globally unique** and identifies the specific attribute *type*. | **Yes** | +| **Attribute Instance** | `https://example.com/attr/classification/value/secret` | The full URI (`{Canonical Name}/value/{Value}`). This represents a specific, actionable attribute assertion used in policies or entitlements. | **Yes** | + +## Attribute Definitions (External Rules) + +Crucially, the *rules* governing how attributes are compared are defined in **Attribute Definitions**, which are associated with the globally unique **Attribute Canonical Name**. These definitions are managed by the attribute authority and are stored **outside** the TDF manifest itself. + +An Attribute Definition typically includes: + +* **Rule Type:** How multiple values or comparisons should be handled (e.g., `AllOf` - entity must have all specified values, `AnyOf` - entity must have at least one, `Hierarchy` - values have an order). +* **Allowed Values:** An optional enumeration or pattern restricting valid attribute values. +* **Order/Rank (for Hierarchy):** Defines the relationship between values in a hierarchical attribute (e.g., Confidential < Secret < TopSecret). + +The PEP retrieves these definitions at access decision time based on the Canonical Names found in the TDF's `dataAttributes` and the entity's entitlements. + +## Access Control Flow in OpenTDF + +When an entity requests access to an OpenTDF object: + +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**. + * **Attribute Check:** + * The PEP examines the required `dataAttributes` (Resource Attributes) listed in the policy. + * For each required attribute, it retrieves the corresponding external **Attribute Definition** based on the attribute's Canonical Name. + * It compares the required `dataAttributes` against the provided **Entity Entitlements** using the comparison logic (AllOf, AnyOf, Hierarchy) specified in the retrieved Attribute Definitions. + * If the entity's entitlements **do not satisfy** the requirements of *all* `dataAttributes` according to their rules, access is **denied**. +3. **Key Release (if authorized):** If *both* the Dissemination Check (if applicable) and the Attribute Check pass, the PEP considers the entity authorized. It then proceeds with verifying the [Policy Binding](./security.md#3-policy-binding) and, if valid, unwraps and provides the requested key share(s) to the client. + +> **Policy Logic Clarification:** The relationship between the `dissem` list and the `dataAttributes` is effectively an **AND**. An entity MUST be on the `dissem` list (if it's used) **AND** MUST satisfy the `dataAttributes` requirements. +> If the `dissem` list is empty or omitted, then *only* the `dataAttributes` requirements need to be met. The `dissem` list acts as an additional filter to narrow the audience beyond what the attributes alone define. + +By combining embedded policy requirements with externally defined attribute rules, OpenTDF achieves a powerful and flexible ABAC implementation for data-centric security. \ No newline at end of file diff --git a/concepts/security.md b/concepts/security.md new file mode 100644 index 0000000..10f5720 --- /dev/null +++ b/concepts/security.md @@ -0,0 +1,56 @@ +# OpenTDF Security Concepts + +OpenTDF is designed with security and tamper evidence as core principles, enabling data-centric protection where security travels with the data itself. This document outlines the key conceptual mechanisms that provide these guarantees. + +## 1. Payload Encryption + +The most fundamental layer of protection is **payload encryption**. The original data within a TDF is encrypted using strong, authenticated symmetric encryption algorithms (typically AES-256-GCM). This ensures the confidentiality of the data – it cannot be read without the correct decryption key. The management and protection of this decryption key are handled by other mechanisms described below. + +## 2. Payload Integrity Verification + +While encryption protects confidentiality, it doesn't inherently prevent undetected modification of the *ciphertext*. An attacker could potentially flip bits in the encrypted data. OpenTDF addresses this using the **`integrityInformation`** object within the manifest. + +* **Purpose:** To allow recipients to verify that the encrypted payload has not been altered since its creation. This is especially critical for streamed data. +* **Mechanism:** + 1. **Segmentation:** The plaintext payload is processed in chunks (segments). + 2. **Segment Hashing/Tagging:** As each segment is encrypted (using AES-GCM, for example), a cryptographic integrity tag (like a GMAC) is generated for that encrypted segment using the *payload encryption key*. This tag is stored (as `hash`) in the corresponding [Segment Object](../schema/OpenTDF/integrity_information.md#encryptioninformationintegrityinformationsegment). + 3. **Root Signature:** All the individual segment tags/hashes are concatenated in order. A final HMAC (e.g., HMAC-SHA256) is calculated over this concatenated string of hashes, again using the *payload encryption key*. This result is stored as the `rootSignature.sig`. +* **Result:** Any modification to even a single bit of the encrypted payload will invalidate the integrity tag of the affected segment *and* consequently invalidate the final `rootSignature`. During decryption, the receiving client MUST verify the integrity tag of each segment and the overall `rootSignature`. Failure indicates tampering. + +## 3. Policy Binding + +It's crucial that the access policy defined for a TDF cannot be detached from the key required to decrypt it. An attacker shouldn't be able to take a wrapped key associated with a strict policy and attach it to a TDF manifest that specifies a weaker policy. The **`policyBinding`** object within *each* [Key Access Object](../schema/OpenTDF/key_access_object.md) prevents this. + +* **Purpose:** To cryptographically link the specific access policy (defined in `encryptionInformation.policy`) to a particular wrapped key share held by a specific Key Access Server (KAS). +* **Mechanism:** + 1. The client retrieves the full, Base64-encoded `policy` string from the `encryptionInformation` section of the manifest it is constructing. + 2. For *each* key share it prepares to wrap for a specific KAS, the client takes the *plaintext key share* itself. + 3. It calculates an HMAC (e.g., HMAC-SHA256, specified by `policyBinding.alg`) using the **plaintext key share** as the secret key and the **Base64-encoded policy string** as the message data. + 4. This resulting HMAC hash is Base64 encoded and stored as `policyBinding.hash` within the *same* `keyAccess` object that contains the corresponding wrapped key share. +* **Result:** When a recipient requests key access from a KAS, they provide the `keyAccess` object (including the `policyBinding`). The KAS decrypts the `wrappedKey` to get the plaintext key share. It then *recalculates* the policy binding HMAC using this key share and the policy string provided (or referenced) in the request. If the calculated hash matches the `policyBinding.hash` received from the client, the KAS knows the policy presented corresponds to the one originally bound to this key share. If they don't match, it indicates tampering or a mismatch, and the KAS MUST deny the request. + +## 4. Key Splitting (Multi-Party Access Control) + +To enhance security and enable multi-party control, OpenTDF supports **key splitting**. Instead of a single KAS holding the complete (wrapped) key, the key can be divided into multiple shares distributed across different KAS instances. + +* **Purpose:** To require authorization from multiple, independent KAS entities before a client can reconstruct the full payload decryption key. This prevents a single compromised KAS from leaking the key and enforces multi-party access control logic. +* **Mechanism:** + 1. The client generates the payload encryption key. + 2. It splits the key into multiple cryptographic shares (e.g., using XOR with random nonces such that `Share1 ⊕ Share2 ⊕ ... ⊕ ShareN = FullKey`). + 3. Each share is treated as an independent key: it's wrapped using the public key of its designated KAS and associated with its own [Policy Binding](#policy-binding). + 4. Each wrapped share is stored in a separate [Key Access Object](../schema/OpenTDF/key_access_object.md) within the `encryptionInformation.keyAccess` array. Crucially, each of these objects is assigned a unique **Split ID** (`sid`). + 5. To decrypt, a client must contact *each* KAS responsible for a required share (identified via the `sid` and `url`). + 6. Each KAS independently verifies the request against its bound policy (using the [Policy Binding](#policy-binding)). + 7. If all necessary KASes grant access, the client receives the unwrapped *shares*. + 8. The client reconstructs the full payload key by combining the shares (e.g., XORing them together). +* **Result:** Access requires successfully authenticating and satisfying the policy constraints at *multiple* independent KAS instances. No single KAS holds enough information to decrypt the data alone. + +## Summary: Layered Security + +These mechanisms work together: +* **Encryption** protects confidentiality. +* **Payload Integrity** ensures the encrypted data hasn't been undetectably modified. +* **Policy Binding** ensures the access policy cannot be decoupled from the key access grant for a specific KAS. +* **Key Splitting** enforces multi-party authorization, preventing single points of failure or compromise for key access. + +This layered approach provides robust, data-centric security and tamper evidence for data protected by OpenTDF. \ No newline at end of file diff --git a/diagrams/filecontents.svg b/diagrams/filecontents.svg new file mode 100644 index 0000000..6059a07 --- /dev/null +++ b/diagrams/filecontents.svg @@ -0,0 +1,13 @@ + + + + my_document.ext.tdf (Zip) + + + + manifest.json + + + + 0.payload (Encrypted) + \ No newline at end of file diff --git a/protocol/protocol.md b/protocol/protocol.md new file mode 100644 index 0000000..7baa0c5 --- /dev/null +++ b/protocol/protocol.md @@ -0,0 +1,162 @@ +# OpenTDF Protocols + +This section describes the interaction protocols between OpenTDF clients (SDKs) and Key Access Servers (KAS) for securely managing access to the Data Encryption Keys (DEKs) used to protect TDF payloads. + +## Protocol Selection and Crypto-Agility + +A core design principle of OpenTDF is **crypto-agility**. The specific cryptographic algorithms and protocols used for key wrapping and KAS communication are not rigidly fixed by the core TDF structure. Instead, each [Key Access Object](./opentdf/key_access.md) within a TDF's manifest specifies: + +1. The **URL** of the responsible KAS. +2. The **protocol** identifier (e.g., `wrapped`) indicating how to interact with that KAS. +3. A **Key Identifier (`kid`)** referencing a specific KAS public key. +4. A **Split Identifier (`sid`)** uniquely identifying a key share when the DEK is split across multiple KAS instances for multi-party access control + +This allows different `keyAccess` objects within the *same* TDF to potentially use different key wrapping mechanisms (e.g., one KAS using RSA, another using ECIES based on Elliptic Curve Cryptography) or evolve independently to adopt new algorithms, such as post-quantum cryptography, without breaking the overall TDF format. + +The client SDK MUST interpret the details within a specific `keyAccess` object to determine how to interact with the corresponding KAS. + +## General Interaction Flow + +While specific protocols vary, the high-level interaction generally follows these phases: + +1. **TDF Creation:** The SDK encrypts the payload with a generated DEK, defines the access policy, wraps the DEK using the target KAS's public key(s) according to the chosen protocol(s), calculates policy bindings, and constructs the manifest. +2. **Access Request:** A client SDK parses the TDF manifest, identifies the relevant `keyAccess` object(s), and sends a request to the specified KAS URL(s). This request includes the wrapped key(s), policy binding information, the policy itself, and client authentication/authorization context (including the client's public key for rewrapping). +3. **KAS Verification:** The KAS authenticates the client, decrypts the wrapped DEK share(s) using its private key, validates the policy binding against the provided policy and the decrypted DEK share, and performs the authorization check (evaluating the policy against the client's authenticated attributes). +4. **Key Rewrap & Response:** If all checks pass, the KAS re-encrypts ("rewraps") the DEK share using the client's public key provided in the request and returns it. If any check fails, the KAS returns an error. +5. **Payload Decryption:** The client SDK decrypts the rewrapped DEK share(s) using its private key, reconstructs the full DEK (if key splitting was used), and uses the DEK to decrypt the TDF payload, verifying payload integrity simultaneously. + +## Example Protocol: RSA Key Wrapping + +The [OpenTDF reference implementation (opentdf/platform)](https://github.com/opentdf/platform) demonstrates specific protocols. Below is a detailed example flow using **RSA** for wrapping the DEK. This assumes a scenario with a single KAS for simplicity. + +### TDF Creation (Encryption Flow) + +*Executed by the OpenTDF Client/SDK* + +1. **Generate DEK:** Generate a cryptographically strong symmetric Data Encryption Key (DEK) (e.g., AES-256). +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 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. +6. **Encrypt Optional Metadata:** Encrypt the prepared metadata using the DEK (e.g., AES-GCM). Base64 encode the ciphertext. The encypted metadata is always passed to the KAS for processing, but from the perspective of a developer using the SDK, it is optional. +7. **Fetch KAS Public Key:** Obtain the target KAS's RSA public key (identified by the KAS URL and potentially a `kid`). This might involve a separate discovery step or be pre-configured. +8. **Wrap DEK:** Encrypt the plaintext DEK using the KAS's RSA public key (e.g., using RSAES-OAEP). Base64 encode the resulting ciphertext. +9. **Construct Key Access Object:** Create the [Key Access Object](../schema/OpenTDF/key_access_object.md) including: + * `type`: "wrapped" + * `url`: KAS URL + * `protocol`: "kas" (or a more specific identifier if needed) + * `kid`: Identifier of the KAS key used. + * `wrappedKey`: Base64 encoded wrapped DEK from step 8. + * `policyBinding`: Object containing `alg` (e.g., "HS256") and the Base64 encoded `hash` from step 4. + * `encryptedMetadata`: (Optional) Base64 encoded encrypted metadata from step 6. +10. **Construct Manifest:** Assemble the full `manifest.json` including the `payload`, `encryptionInformation` (containing the `keyAccess` object(s), `method`, `integrityInformation`, and `policy` string), and any `assertions`. +11. **Package TDF:** Create the Zip archive containing `manifest.json` and the encrypted payload file. +12. **Securely Discard DEK:** Erase the plaintext DEK from memory immediately after it has been wrapped and used for metadata encryption/bindings. It should *never* be stored persistently by the encrypting client. + +### TDF Access (Decryption Flow) + +*Involves interaction between Client/SDK and KAS* + +```mermaid +sequenceDiagram + participant ClientSDK as Client SDK + participant KAS + + %% Phase 1: Client Preparation & Request + activate ClientSDK + ClientSDK-->>ClientSDK: Parse Manifest + ClientSDK-->>ClientSDK: Identify KAS Target & Extract Info (WrappedKey, Policy, Binding, etc.) + ClientSDK-->>ClientSDK: Prepare Client Context (Authn, Client PubKey) + ClientSDK-->>ClientSDK: Construct Rewrap Request Body + ClientSDK->>KAS: POST /v1/rewrap (Request Body) + deactivate ClientSDK + + %% Phase 2: KAS Processing & Verification + activate KAS + Note over KAS: Phase 2: KAS Processing + KAS-->>KAS: 7. Authenticate Client Request + alt Authentication Failed + KAS->>ClientSDK: Error Response (401/403 Authn Failure) + end + KAS-->>KAS: 8. Decrypt DEK Share (using KAS Private Key) + KAS-->>KAS: 9. Validate Policy Binding (recalculate HMAC, compare) + alt Policy Binding Invalid + KAS->>ClientSDK: Error Response (400/403 Binding Failure) + end + KAS-->>KAS: 10. (Optional) Decrypt Metadata + KAS-->>KAS: 11. Perform Authorization Check (Evaluate Policy/Attributes) + alt Authorization Failed + KAS->>ClientSDK: Error Response (403 Authz Failure) + end + Note over KAS: All Checks Passed! + KAS-->>KAS: 12. Rewrap DEK Share (using Client Public Key) + KAS->>ClientSDK: 13. Success Response (Rewrapped DEK Share) + deactivate KAS + + %% Phase 3: Client Decryption + activate ClientSDK + Note over ClientSDK: Phase 3: Client Decryption + ClientSDK-->>ClientSDK: 14. Receive & Process Response + alt Success Response + ClientSDK-->>ClientSDK: 15. Decrypt DEK Share (using Client Private Key) + ClientSDK-->>ClientSDK: 16. Reconstruct Full DEK (if key splitting used) + ClientSDK-->>ClientSDK: 17. Decrypt Payload & Verify Integrity + ClientSDK-->>ClientSDK: 18. Securely Discard DEK + else Error Response + ClientSDK-->>ClientSDK: Handle KAS Error + end + deactivate ClientSDK +``` + +**Phase 1: Client Preparation & Request** *(Executed by SDK)* + +1. **Parse Manifest:** Read the TDF's `manifest.json`. +2. **Identify KAS Target(s):** Select the appropriate [Key Access Object](./opentdf/key_access.md)(s) based on desired KAS or required key shares (`sid` if splitting). +3. **Extract Information:** From the selected `keyAccess` object(s), extract the KAS `url`, `wrappedKey`, `policyBinding` object, and optionally `encryptedMetadata`. Extract the Base64 `policy` string from `encryptionInformation`. +4. **Prepare Client Context:** Obtain the client's authentication credentials (e.g., OAuth token) and the client's public key (corresponding to the private key the client will use for decryption). +5. **Construct Rewrap Request:** Create a request payload (typically JSON) containing: + * The `wrappedKey` to be rewrapped. + * The `policyBinding` object (`alg` and `hash`). + * The Base64 `policy` string. + * (Optional) The `encryptedMetadata`. + * The client's public key (for the KAS to rewrap the DEK). + * Client authentication/authorization information (e.g., in HTTP headers). +6. **Send Request:** POST the request payload to the KAS endpoint (e.g., `{KAS_URL}/v1/rewrap`). + +**Phase 2: KAS Processing & Verification** *(Executed by KAS)* + +7. **Authenticate Client:** Verify the client's authentication credentials. If invalid, return an authentication error. +8. **Decrypt DEK Share:** Use the KAS's *private* RSA key (corresponding to the public key used for wrapping, identified by `kid`) to decrypt the `wrappedKey` provided in the request, yielding the plaintext DEK share. +9. **Validate Policy Binding:** + * Recalculate the HMAC: `HMAC(DEK share, policy string from request)` using the algorithm specified in the request's `policyBinding.alg`. + * Compare the recalculated HMAC hash with the `policyBinding.hash` provided in the request. + * If they do not match, return a policy binding error (indicates tampering or mismatch). +10. **(Optional) Decrypt Metadata:** If `encryptedMetadata` was provided, decrypt it using the plaintext DEK share. This metadata might inform policy decisions or logging. +11. **Perform Authorization Check:** + * Retrieve the requesting client's validated attributes/entitlements (based on their authenticated identity). + * Parse the `policy` string from the request to get the required `dataAttributes` and `dissem` list. + * Evaluate the policy rules (potentially retrieving external Attribute Definitions) against the client's attributes. + * Check if the client is in the `dissem` list (if applicable). + * If authorization fails (policy requirements not met), return an authorization error. +12. **Rewrap DEK Share:** If all checks pass, encrypt the plaintext DEK share using the client's public key provided in the request (e.g., using RSAES-OAEP if the client key is RSA). Base64 encode the result. +13. **Send Response:** Return a success response containing the Base64 encoded, rewrapped DEK share. + +**Phase 3: Client Decryption** *(Executed by SDK)* + +14. **Receive Response:** Get the response from the KAS. Check for errors (authentication, binding, authorization failures). +15. **Decrypt DEK Share:** If the request was successful, use the client's *private* key to decrypt the rewrapped DEK share received from the KAS. +16. **(If Key Splitting) Reconstruct DEK:** If multiple shares were required (`sid` was used), combine the decrypted shares (e.g., via XOR) to reconstruct the full plaintext DEK. +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 + +KAS implementations SHOULD return standard HTTP error codes and informative error messages (without revealing sensitive internal state) for failed requests, clearly distinguishing between: + +* Authentication failures (401/403) +* Policy Binding validation failures (e.g., 400 Bad Request or 403 Forbidden) +* Authorization failures (policy denied) (403 Forbidden) +* Invalid input or malformed requests (400 Bad Request) +* Internal server errors (500) + +Clients MUST handle these errors appropriately. \ No newline at end of file diff --git a/schema/OpenTDF/README.md b/schema/OpenTDF/README.md new file mode 100644 index 0000000..1b92b5e --- /dev/null +++ b/schema/OpenTDF/README.md @@ -0,0 +1,50 @@ +# OpenTDF Specification Overview + +This section details the **OpenTDF** format, the primary specification for general-purpose Trusted Data Format (TDF) implementations. It utilizes a JSON-based manifest packaged with the encrypted payload within a standard Zip archive. + +## Core Concepts + +Before diving into specific object definitions, understand these core OpenTDF concepts: + +* **Security:** Learn about what makes OpenTDF secure. See [Security Concepts](../../concepts/security.md). +* **Key Access and Wrapping:** How access control is defined using ABAC. See [Access Control](../../concepts/access_control.md). + +## Format Structure + +An OpenTDF file is a Zip archive, typically using the `.tdf` extension (e.g., `document.pdf.tdf`). It MUST contain the following components: + +1. **`manifest.json`:** A JSON file containing all metadata required for decryption and access control. This is the core of the TDF structure. +2. **`payload`:** The encrypted original data. The filename within the archive is referenced by the `manifest.json` (commonly `0.payload`). + +![img](../../diagrams/filecontents.svg) + +## Key Components of `manifest.json` + +The `manifest.json` file orchestrates the TDF. Its main sections are: + +* **Payload Description:** Information about the encrypted payload (type, reference, protocol, encryption status). See [Payload Object](./payload.md). +* **Encryption Information:** Details on how the payload was encrypted, how to access the key, integrity checks, and the access policy. See [Encryption Information](./encryption_information.md). This includes: + * [Key Access Objects](./key_access_object.md): How and where to get the decryption key. + * [Method](./method.md): Symmetric encryption algorithm details. + * [Integrity Information](./integrity_information.md): Hashes/signatures for payload integrity. + * [Policy](./policy.md): The access control policy (embedded as a Base64 string). +* **Assertions:** Optional, verifiable statements about the TDF or payload. See [Assertions](./assertion.md). + +## Manifest Schema + +Use the links below to explore the detailed structure of each component: + +* [**Manifest Structure (`manifest.json`)**](./manifest.md) +* [Payload Object](./payload.md) +* [Encryption Information Object](./encryption_information.md) + * [Key Access Object](./key_access_object.md) + * [Method Object](./method.md) + * [Integrity Information Object](./integrity_information.md) + * [Segment Object](./segment.md) +* [Assertions](./assertion.md) + * [Statement Object](./assertion_statement.md) + * [Binding Object](./assertion_binding.md) +* [**Conceptual Guides:**](./) + * [Security](../../concepts/security.md) + * [Access Control](../../concepts/access_control.md) + diff --git a/schema/OpenTDF/assertion.md b/schema/OpenTDF/assertion.md new file mode 100644 index 0000000..5deb87c --- /dev/null +++ b/schema/OpenTDF/assertion.md @@ -0,0 +1,31 @@ +# Assertions Array + +The `assertions` array, an optional top-level property in the [manifest](./manifest.md), contains assertion objects. Assertions are verifiable statements about the TDF or its payload, often used for security labeling or handling instructions. + +## Example (Array containing one Assertion Object) + +```json +"assertions": [ + { + "id": "handling-assertion-1", + "type": "handling", + "scope": "payload", + "appliesToState": "encrypted", + "statement": { /* See Statement Object */ }, + "binding": { /* See Binding Object */ } + } +] +``` + +## Assertion Object Structure + +Each object within the assertions array represents a single assertion and has the following fields: + +| Parameter | Type | Description | Required? | +| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| id | String | A unique identifier for this assertion within this TDF manifest. Used for internal referencing. | Yes | +| type | String | Categorizes the assertion's purpose. Common values include handling (e.g., caveats, dissemination controls) or metadata (general information). | Yes | +| scope | String | Specifies whether the assertion applies to the entire TDF object (tdo) or just the payload. | Yes | +| appliesToState | String | Indicates if the assertion's statement applies to the data in its encrypted state or its unencrypted state (after decryption). Default is encrypted. | No | +| statement | Object | The actual content of the assertion. See [Statement Object](./assertion_statement.md). | Yes | +| binding | Object | A cryptographic signature ensuring the assertion's integrity and preventing it from being moved to another TDF. See [Assertion Binding](./assertion_binding.md) | | \ No newline at end of file diff --git a/schema/OpenTDF/assertion_binding.md b/schema/OpenTDF/assertion_binding.md new file mode 100644 index 0000000..1526306 --- /dev/null +++ b/schema/OpenTDF/assertion_binding.md @@ -0,0 +1,19 @@ +# Binding Object (Assertion) + +The `binding` object, nested within an [Assertion Object](./assertion.md), contains a cryptographic signature binding the assertion to the TDF context, ensuring its integrity and preventing replay on other TDFs. + +## Example + +```json +"binding": { + "method": "jws", + "signature": "eyJhbGciOiJSUzI1NiJ9..." // Base64URL encoded JWS string +} +``` + +## Fields + +| Parameter | Type | Description | Required? | +| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| method | String | The cryptographic method used for the signature. jws (JSON Web Signature) is commonly used, implying standard JWS processing rules apply. | Yes | +| signature | String | The Base64URL encoded signature value (e.g., a JWS Compact Serialization string). The signature calculation MUST include the assertion content and sufficient TDF context (like policy or key info hash) to prevent replay. | Yes | \ No newline at end of file diff --git a/schema/OpenTDF/assertion_statement.md b/schema/OpenTDF/assertion_statement.md new file mode 100644 index 0000000..147e5b2 --- /dev/null +++ b/schema/OpenTDF/assertion_statement.md @@ -0,0 +1,25 @@ +# Statement Object + +The `statement` object, nested within an [Assertion Object](./assertion.md), contains the core information or claim of the assertion. + +## Example + +```json +"statement": { + "schema": "urn:nato:stanag:4774:confidentialitymetadatalabel:1:0", + "format": "json-structured", + "value": { + "Xmlns": "urn:nato:stanag:4774:confidentialitymetadatalabel:1:0", + "CreationTime": "2015-08-29T16:15:00Z", + "ConfidentialityInformation": { /* ... specific assertion info ... */ } + } +} +``` + +## Fields + +| Parameter | Type | Description | Required? | +| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| schema | String | An optional URI identifying the schema or standard that defines the structure and semantics of the value. | No | +| format | String | Describes how the value is encoded. Common values: json-structured (value is a JSON object), base64binary (value is Base64 encoded binary), string. | Yes | +| value | Any | The assertion content itself, formatted according to the format field. Can be a string, number, boolean, object, or array (if format is json-structured). | Yes | \ No newline at end of file diff --git a/schema/OpenTDF/attributes.md b/schema/OpenTDF/attributes.md new file mode 100644 index 0000000..8ba481b --- /dev/null +++ b/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). + +An Attribute Object represents a single required attribute instance needed to access the data. + +## Example + +```json +{ + "attribute": "https://example.com/attr/classification/value/topsecret" +} +``` +## Fields + +| Parameter | Type | Description | Required? | +| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| attribute | String | The full Attribute Instance URI, composed of {Namespace}/attr/{Name}/value/{Value}. See [Access Control concepts](../../concepts/access_control.md). | | diff --git a/schema/OpenTDF/encryption_information.md b/schema/OpenTDF/encryption_information.md new file mode 100644 index 0000000..dfde331 --- /dev/null +++ b/schema/OpenTDF/encryption_information.md @@ -0,0 +1,25 @@ +# Encryption Information Object + +The `encryptionInformation` object, part of the [manifest](./manifest.md), aggregates all information related to the encryption of the payload, policy enforcement, and key management. + +## Example + +```json +"encryptionInformation": { + "type": "split", + "keyAccess": [ { /* See Key Access Object */ } ], + "method": { /* See Method Object */ }, + "integrityInformation": { /* See Integrity Information Object */ }, + "policy": "eyJ1dWlkIjoiNGYw...vbSJdfX0=" // Base64 encoded Policy Object JSON +} +``` + +## Fields + +| Parameter | Type | Description | Required? | +| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| type | String | Specifies the key management scheme. split is the primary scheme, allowing key sharing or splitting across multiple keyAccess entries. | Yes | +| keyAccess | Array | An array of one or more [Key Access Objects](./key_access_object.md). Each object describes how to obtain the payload decryption key (or a key split) from a specific Key Access Server (KAS). | Yes | +| method | Object | Describes the symmetric encryption algorithm used on the payload. See [Method Object](./method.md). | Yes | +| integrityInformation | Object | Contains information for verifying the integrity of the payload, especially for streamed TDFs. See [Integrity Information Object](./integrity_information.md). | Yes | +| policy | String | A Base64 encoding of the JSON string representing the [Policy Object](./policy.md). Defines the access control rules for the TDF. For conceptual details, see [Access Control](../../concepts/access_control.md). | | \ No newline at end of file diff --git a/schema/OpenTDF/integrity_information.md b/schema/OpenTDF/integrity_information.md new file mode 100644 index 0000000..e7cfb13 --- /dev/null +++ b/schema/OpenTDF/integrity_information.md @@ -0,0 +1,48 @@ +# Integrity Information Object + +The `integrityInformation` object, nested within [`encryptionInformation`](./encryption_information.md), provides mechanisms to verify the integrity of the encrypted payload, essential for streaming and detecting tampering. + +## Example + +```json +"integrityInformation": { + "rootSignature": { + "alg": "HS256", + "sig": "M2E2MTI5YmMxMW...WNlMWVjYjlmODUzNmNiZQ==" // Base64 encoded signature + }, + "segmentHashAlg": "GMAC", + "segments": [ { /* See Segment Object */ } ], + "segmentSizeDefault": 1000000, + "encryptedSegmentSizeDefault": 1000028 +} +``` + +## Fields + +| Parameter | Type | Description | Required? | +| --------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| rootSignature | Object | Contains a cryptographic signature or HMAC over the combined integrity hashes of all segments, providing overall payload integrity. | Yes | +| rootSignature.alg | String | Algorithm used for the rootSignature.sig. HS256 (HMAC-SHA256 using the payload key) is commonly used. | Yes | +| rootSignature.sig | String | The Base64 encoded signature or HMAC value. Calculated over the concatenation of all segment hashes/tags in order. E.g., Base64(HMAC-SHA256(PayloadKey, Concat(SegmentHash1, SegmentHash2, ...))). | Yes | +| segmentHashAlg | String | The algorithm used to generate the hash for each segment in the segments array. GMAC (using the AES-GCM payload key) is commonly used when method.algorithm is AES-256-GCM. | Yes | +| segments | Array | An array of [Segment Objects](#encryptionInformation.integrityInformation.segment), one for each chunk of the payload if method.isStreamable is true. Order MUST match payload order. | Yes | +| segmentSizeDefault | Number | The default size (in bytes) of the plaintext payload segments. Allows omitting segmentSize in individual segment objects if they match this default. | Yes | +| encryptedSegmentSizeDefault | Number | The default size (in bytes) of the encrypted payload segments (including any authentication tag overhead, like from AES-GCM). Allows omitting encryptedSegmentSize in segments. | | + +## encryptionInformation.integrityInformation.segment + +Object containing integrity information about a segment of the payload, including its hash. + +```json +{ + "hash": "NzhlZDg5OWMwZWVhZDBjMWEzZTQyYmFlODA0NjNlMDM=", + "segmentSize": 14056, + "encryptedSegmentSize": 14084 +} +``` + +|Parameter|Type|Description| +|---|---|---| +|`hash`|String|A hash generated using the specified `segmentHashAlg`.

`Base64.encode(HMAC(segment, payloadKey))`| +|`segmentSize`|Number|The size of the segment. This field is optional. The size of the segment is inferred from 'segmentSizeDefault' defined above, but in the event that a segment were modified and re-encrypted, the segment size would change.| +|`encryptedSegmentSize`|Number|The size of the segment (in bytes) after the payload segment has been encrypted.| \ No newline at end of file diff --git a/schema/tdf/json-schema/schema.json b/schema/OpenTDF/json-schema/schema.json similarity index 100% rename from schema/tdf/json-schema/schema.json rename to schema/OpenTDF/json-schema/schema.json diff --git a/schema/OpenTDF/key_access_object.md b/schema/OpenTDF/key_access_object.md new file mode 100644 index 0000000..1daffbe --- /dev/null +++ b/schema/OpenTDF/key_access_object.md @@ -0,0 +1,44 @@ +# Key Access Object + +A Key Access Object, found within the `keyAccess` array in [`encryptionInformation`](./encryption_information.md), stores information about how a specific payload encryption key (or key split/share) is stored and accessed, typically via a Key Access Server (KAS). + +## Example + +```json +{ + "type": "wrapped", + "url": "https://kas.example.com:5000", + "kid": "6f3b6a82-2f30-4c8a-aef3-57c65b8e7387", // Optional KAS Key ID + "sid": "split-id-1", // Optional Split ID + "protocol": "kas", + "wrappedKey": "OqnOE...B82uw==", // Base64 encoded wrapped key + "policyBinding": { + "alg": "HS256", + "hash": "BzmgoIxZzMmIF42qzbdD4Rw30GtdaRSQL2Xlfms1OPs=" // Base64 encoded hash + }, + "encryptedMetadata": "ZoJTNW24UMhnXIif0mSnqLVCU=" // Base64 encoded encrypted metadata +} +``` + +## Fields + +| Parameter | Type | Description | Required? | +| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| type | String | Specifies how the key is stored/accessed.
**Possible Values:** | Yes | +| url | String | The base URL of the Key Access Server (KAS) responsible for this key or key share. | Yes | +| protocol | String | Protocol used to interact with the url. Currently, only kas is specified. | Yes | +| wrappedKey | String | The Base64 encoded payload symmetric key (or key share), encrypted ("wrapped") using the public key of the KAS identified by url (and optionally kid). | Yes | +| policyBinding | Object | An object containing a keyed hash binding the policy string from [encryptionInformation](./encryption_information.md) to this specific wrappedKey. This prevents policy tampering without access to the key share. | Yes | +| kid | String | Optional. An identifier for the specific public key at the KAS (url) used to wrap the wrappedKey. This could be a key fingerprint, UUID, etc. Aids key rotation. | No | +| sid | String | Optional. A Key Split (or Share) Identifier. If present, it indicates this wrappedKey represents only a share of the full payload key. Multiple keyAccess objects with different sid values (but potentially the same type/url) might need to be combined (e.g., via XOR) by the client after receiving unwrapped shares from respective KASes to reconstruct the final payload key. The encryptionInformation.type (split) governs this behavior. | No | +| encryptedMetadata | String | Optional. Base64 encoded, encrypted metadata associated with this key access entry. Contains client-provided information (e.g., request context) passed to the KAS during rewrap requests. The KAS decrypts this using its private key. The content is freeform and SHOULD NOT be used for primary access decisions. | No | + +## Policy Binding Object (keyAccess.policyBinding) + +This nested object provides the cryptographic binding between the policy and the key share. + +| | | | | +|---|---|---|---| +|Parameter|Type|Description|Required?| +|alg|String|The algorithm used to generate the hash. HS256 (HMAC-SHA256) is commonly used.|Yes| +|hash|String|A Base64 encoding of HMAC(KEY, POLICY), where:
- POLICY: The Base64 encoded policy string from encryptionInformation.policy.
- HMAC: The algorithm specified by alg (e.g., HMAC-SHA256).
- KEY: The plaintext symmetric key corresponding to the wrappedKey in this Key Access Object (i.e., the key share itself). The KAS verifies this binding upon receiving a rewrap request before proceeding.|Yes| \ No newline at end of file diff --git a/schema/OpenTDF/manifest.md b/schema/OpenTDF/manifest.md new file mode 100644 index 0000000..c9ce227 --- /dev/null +++ b/schema/OpenTDF/manifest.md @@ -0,0 +1,105 @@ +# OpenTDF Manifest (`manifest.json`) + +## Summary + +The `manifest.json` file MUST be in JSON format and reside within the root of the OpenTDF Zip archive. It serves as the central metadata component, storing the necessary information for processing the TDF payload and making access decisions by a Policy Enforcement Point (PEP). + +## Top-Level Structure + +The manifest object contains the following top-level properties: + +| Parameter | Type | Description | Required? | +| :---------------------- | :----- | :---------------------------------------------------------------------------------------------------------- | :-------- | +| `tdf_spec_version` | String | Semver version number of the OpenTDF specification this manifest conforms to. | Yes | +| `payload` | Object | Describes the location and characteristics of the encrypted payload. See [Payload Object](./payload.md). | Yes | +| `encryptionInformation` | Object | Contains details about encryption, key access, integrity, and policy. See [Encryption Information Object](./encryption_information.md). | Yes | +| `assertions` | Array | Optional array of verifiable statements about the TDF or payload. See [Assertions Array](./assertion.md). | No | + +## Full Manifest Example + +This example illustrates a complete `manifest.json` structure. Links point to detailed descriptions of each major section. + +```json +{ + "tdf_spec_version": "1.0.0", + // --- Payload Object --- + "payload": { + "type": "reference", + "url": "0.payload", + "protocol": "zip", + "isEncrypted": true, + "mimeType": "application/octet-stream" + }, + // --- Encryption Information Object --- + "encryptionInformation": { + "type": "split", + // --- Key Access Array --- + "keyAccess": [ + { + "type": "wrapped", + "url": "http://kas.example.com:4000", + "protocol": "kas", + "wrappedKey": "YBkqvsiDnyDfw5JQzux2S2IaiClhsojZuLYY9WOc9N9l37A5/Zi7iloxcqgFvBFbzVjGW4QBwAHsytKQvE87bHTuQkZs4XyPACOZE/k9r+mK8KazcGTkOnqPKQNhf2XK4TBACJZ6eItO5Q1eHUQVLKjxUfgyx2TBDfhB/7XifNthu+6lFbKHmPl1q7q1Vaa/rpPRhSgqf89x5fQvcSWdkuOH9Y4wTa8tdKqSS3DUNMKTIUQq8Ti/WFrq26DRemybBgBcL/CyUZ98hFjDQgy4csBusEqwQ5zG+UAoRgkLkHiAw7hNAayAUCVRw6aUYRF4LWfcs2BM9k6d3bHqun0v5w==", + "policyBinding": { + "alg": "HS256", + "hash": "ZGMwNGExZjg0ODFjNDEzZTk5NjdkZmI5MWFjN2Y1MzI0MTliNjM5MmRlMTlhYWM0NjNjN2VjYTVkOTJlODcwNA==" + }, + "encryptedMetadata": "OEOqJCS6mZsmLWJ38lh6EN2lDUA8OagL/OxQRQ==" + } + ], + // --- Method Object --- + "method": { + "algorithm": "AES-256-GCM", + "isStreamable": true, + "iv": "OEOqJCS6mZsmLWJ3" + }, + // --- Integrity Information Object --- + "integrityInformation": { + "rootSignature": { + "alg": "HS256", + "sig": "YjliMzAyNjg4NzA0NzUyYmUwNzY1YWE4MWNhNDRmMDZjZDU3OWMyYTMzNjNlNDYyNTM4MDA4YjQxYTdmZmFmOA==" + }, + "segmentSizeDefault": 1000000, + "segmentHashAlg": "GMAC", + // --- Segments Array --- + "segments": [ + { + "hash": "ZmQyYjY2ZDgxY2IzNGNmZTI3ODFhYTk2ZjJhNWNjODA=", + "segmentSize": 14056, + "encryptedSegmentSize": 14084 + } + ], + "encryptedSegmentSizeDefault": 1000028 + }, + // --- Policy String --- + "policy": "eyJ1dWlkIjoiNjEzMzM0NjYtNGYwYS00YTEyLTk1ZmItYjZkOGJkMGI4YjI2IiwiYm9keSI6eyJhdHRyaWJ1dGVzIjpbXSwiZGlzc2VtIjpbInVzZXJAdmlydHJ1LmNvbSJdfX0=" + }, + // --- Assertions Array --- + "assertions": [ + { + "id": "nato-label-1", + "type": "handling", + "scope": "payload", + "appliesToState": "encrypted", + // --- Statement Object --- + "statement": { + "format": "json-structured", + "schema": "urn:nato:stanag:4774:confidentialitymetadatalabel:1:0", + "value": { + "Xmlns": "urn:nato:stanag:4774:confidentialitymetadatalabel:1:0", + "CreationTime": "2015-08-29T16:15:00Z", + "ConfidentialityInformation": { + "PolicyIdentifier": "NATO", + "Classification": "SECRET", + "Category": { "Type": "PERMISSIVE", "TagName": "Releasable to", "GenericValues": [ "SWE", "FIN", "FRA" ] } + } + } + }, + // --- Binding Object --- + "binding": { + "method": "jws", + "signature": "eyJhbGciOiJIUzI1NiJ9.eyJzY2hlbWEiOiJ1cm46bmF0bzpzdGFuYWc6NDc3NDpjb25maWRlbnRpYWxpdHltZXRhZGF0YWxhYmVsOjE6MCIsImZvcm1hdCI6Impzb24tc3RydWN0dXJlZCIsInZhbHVlIjp7IlhtbG5zIjoidXJuOm5hdG86c3RhbmFnOjQ3NzQ6Y29uZmlkZW50aWFsaXR5bWV0YWRhdGFsYWJlbDoxOjAiLCJDcmVhdGlvblRpbWUiOiIyMDE1LTA4LTI5VDE2OjE1OjAwWiIsIkNvbmZpZGVudGlhbGl0eUluZm9ybWF0aW9uIjp7IlBvbGljeUlkZW50aWZpZXIiOiJOQVRPIiwiQ2xhc3NpZmljYXRpb24iOiJTRUNSRVQiLCJDYXRlZ29yeSI6eyJNeXBlIjoiUEVSTUlTU0lWRSIsIlRhZ05hbWUiOiJSZWxlYXNhYmxlIHRvIiwiR2VuZXJpY1ZhbHVlcyI6WyJTV0UiLCJGSU4iLCJGUkEiXX19fX0.FakeBindingSignatureExample" + } + } + ] +} \ No newline at end of file diff --git a/schema/OpenTDF/method.md b/schema/OpenTDF/method.md new file mode 100644 index 0000000..61737ca --- /dev/null +++ b/schema/OpenTDF/method.md @@ -0,0 +1,21 @@ +# Method Object + +The `method` object, nested within [`encryptionInformation`](./encryption_information.md), describes the symmetric encryption algorithm and parameters used to encrypt the payload. + +## Example + +```json +"method": { + "algorithm": "AES-256-GCM", + "isStreamable": true, + "iv": "D6s7cSgFXzhVkran" // Base64 encoded IV +} +``` + +## Fields + +| Parameter | Type | Description | Required? | +| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| algorithm | String | The symmetric encryption algorithm used. AES-256-GCM is the recommended and commonly implemented algorithm. | Yes | +| isStreamable | Boolean | Indicates if the payload was encrypted in segments suitable for streaming decryption. If true, [integrityInformation](./integrity_information.md) MUST contain segment details. | Yes | +| iv | String | The Base64 encoded Initialization Vector (IV) used with the symmetric algorithm. MUST be unique for each TDF encrypted with the same key. For AES-GCM, typically 12 bytes (96 bits). | Yes | diff --git a/schema/OpenTDF/payload.md b/schema/OpenTDF/payload.md new file mode 100644 index 0000000..b6aea0f --- /dev/null +++ b/schema/OpenTDF/payload.md @@ -0,0 +1,24 @@ +# Payload Object + +The `payload` object within the [manifest](./manifest.md) contains metadata required to locate and process the TDF's encrypted payload. +## Example + +```json +"payload": { + "type": "reference", + "url": "0.payload", + "protocol": "zip", + "isEncrypted": true, + "mimeType": "application/pdf" +} +``` +## Fields + +| Parameter | Type | Description | Required? | +| ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| type | String | Describes how the payload is referenced. Currently, reference (indicating the payload is within the TDF archive) is the only specified type. | Yes | +| url | String | A URI pointing to the location of the payload. For type: reference, this is typically a relative path within the Zip archive (e.g., 0.payload). | Yes | +| protocol | String | Designates the packaging format of the payload within the TDF. Allowed values include zip (for standard files) and zipstream (for streamed files). | Yes | +| isEncrypted | Boolean | Indicates whether the payload referenced by url is encrypted. MUST be true for standard TDFs. Future use may allow false. | Yes | +| mimeType | String | Specifies the MIME type of the original, unencrypted data. If not provided, application/octet-stream SHOULD be assumed. | No | + diff --git a/schema/OpenTDF/policy.md b/schema/OpenTDF/policy.md new file mode 100644 index 0000000..7baf46d --- /dev/null +++ b/schema/OpenTDF/policy.md @@ -0,0 +1,26 @@ +# Policy Object (Structure) + +This document describes the JSON structure of the Policy Object. The entire object is JSON stringified and then Base64 encoded when stored in the `encryptionInformation.policy` field of the [manifest](./manifest.md). For a conceptual overview, see [Access Control Concepts](../../concepts/access_control.md). + +The Policy Object contains the access control rules for the TDF. + +## Example (Decoded JSON Structure) + +```json +{ +"uuid": "1111-2222-33333-44444-abddef-timestamp", +"body": { + "dataAttributes": [], + "dissem": ["user-id@domain.com"] + }, +} +``` + +## Fields + +| Parameter | Type | Description | Required? | +| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| uuid | String | A [UUID](https://www.rfc-editor.org/rfc/rfc4122) uniquely identifying this specific policy instance. | Yes | +| body | Object | Contains the core access control constraints. | Yes | +| body.dataAttributes | Array | An array of [Attribute Objects](./attributes.md). Represents the attributes an entity must possess (according to their definitions and rules) to satisfy the policy's ABAC requirements. | Yes | +| body.dissem | Array | An array of strings, where each string is a unique identifier for an entity (e.g., email address, user ID). If present, an entity requesting access must be included in this list in addition to satisfying the dataAttributes. If empty or omitted, any entity satisfying dataAttributes may be granted access. | No | diff --git a/schema/README.md b/schema/README.md new file mode 100644 index 0000000..eff457e --- /dev/null +++ b/schema/README.md @@ -0,0 +1,8 @@ +# OpenTDF Schema Documentation + +This directory contains the schema documentation for the base OpenTDF, and NanoTDF formats. + +## Specifications + +* [OpenTDF Format](OpenTDF/README.md) - The primary JSON-based TDF specification +* [NanoTDF Format](nanotdf/README.md) - A compact binary format for resource-constrained environments diff --git a/schema/tdf/AttributeObject.md b/schema/tdf/AttributeObject.md deleted file mode 100644 index a73fb3a..0000000 --- a/schema/tdf/AttributeObject.md +++ /dev/null @@ -1,50 +0,0 @@ -# Attribute Object - -## Summary - -An Attribute Object contains attribute information the TDF system uses to enforce attribute-based access control (ABAC). - -Attributes are used in the [Policy Object](PolicyObject.md) to define what an entity "needs" to access data. - -Access decisions compare the attributes an entity has with those required by a data policy. - -- Entity entitlements: Attributes an entity "has." -- Data attributes: Attributes needed to access data, represented by [Data Policy Objects](PolicyObject.md). - -Attributes are represented as URIs. For example: - -`https://demo.com/attr/Blob/value/Green` - -| Name | Example Value | Description | -| ---- | ------------- | ----------- | -| **Attribute Namespace** | `https://demo.com` | Typically a standard DNS name. It is recommended that the root DNS name of the authoritative owner of the attribute be used as the Attribute Namespace. | -| **Attribute Name** | `Blob` | Not globally unique. | -| **Attribute Canonical Name** | `https://demo.com/attr/Blob` | Combination of `Attribute Namespace` and `Attribute Name`, separated by the string `/attr/`. Attribute Canonical Names are the _globally unique_ part of the attribute. | -| **Attribute Value** | `Green` | Not globally unique. | -| **Attribute Instance** | `https://demo.com/attr/Blob/value/Green` | Combination of `Attribute Canonical Name` + a single `Attribute Value`, separated by the string `/value/`. The complete representation of an actionable authorization attribute, as found in data and entity policy documents. | -| **Attribute Definition** | `{rule_type: AllOf, valid_values: [Green, Red, Purple]}` | Authorization-relevant metadata (rule type: AllOf / AnyOf / Hierarchy, allowed values, etc) associated with a specific, globally unique `Attribute Canonical Name`. Stored/managed by the authoritative owner of the attribute, separately from data or entity policy. | - -> Key Point: Attribute Namespaces are not globally unique by themselves. Attribute Names are not globally unique by themselves. The combination of **both Namespace and Value** (the Canonical Name) _must_ be globally unique, and _must_ globally identify the Attribute. - -> Key Point: As Attribute Canonical Names are globally unique, and Attribute Definitions are associated with a specific Attribute Canonical Name, it follows that there can be _only one_ Attribute Definition globally, for a given Canonical Name. - -> Key Point: Only an Attribute Instance (Canonical Name + Value) can used for authorization decisions, or added to [Data Policy Objects](PolicyObject.md) - -When creating a tdf, the client determines which Attribute Instances an entity must have in order to access the payload and append those Attribute Instance URIs to the data's [Data Policy Object](PolicyObject.md). - -When a access decision is requested, the Policy Enforcement Point(PEP) checks the [Data Policy Object](PolicyObject.md) against the entities entitlements from the requesting client to -ensure that the entity Attribute Instances match the data Attribute Instances, using the Attribute Definitions currently associated with each individual data Attribute Instance to determine comparison rules (AnyOf/AllOf/Hierarchy). - -If this check succeeds, the PEP permits access to the tdf. - -## Data policy payload example - -```json -{ - "attribute": "https://example.com/attr/classification/value/topsecret" -} -``` - -|Parameter|Type|Description|Required?| -|---|---|---|---| -|`attribute`|String|The full Attribute Instance (Canonical Name + Value). |Yes| diff --git a/schema/tdf/KeyAccessObject.md b/schema/tdf/KeyAccessObject.md deleted file mode 100755 index 29e2209..0000000 --- a/schema/tdf/KeyAccessObject.md +++ /dev/null @@ -1,338 +0,0 @@ -# Key Access Object - -## Summary - -A Key Access Object stores not only a wrapped (encrypted) key used to encrypt the file's payload, but also additional metadata about _how_ it is stored. - -## Example" - -```json -{ - "type": "wrapped", - "url": "https:\/\/kas.example.com:5000", - "kid": "6f3b6a82-2f30-4c8a-aef3-57c65b8e7387", - "sid": "split-id-1", - "protocol": "kas", - "wrappedKey": "OqnOETpwyGE3PVpUpwwWZoJTNW24UMhnXIif0mSnqLVCUPKAAhrjeue11uAXWpb9sD7ZDsmrc9ylmnSKP9vWel8ST68tv6PeVO+CPYUND7cqG2NhUHCLv5Ouys3Klurykvy8\/O3cCLDYl6RDISosxFKqnd7LYD7VnxsYqUns4AW5\/odXJrwIhNO3szZV0JgoBXs+U9bul4tSGNxmYuPOj0RE0HEX5yF5lWlt2vHNCqPlmSBV6+jePf7tOBBsqDq35GxCSHhFZhqCgA3MvnBLmKzVPArtJ1lqg3WUdnWV+o6BUzhDpOIyXzeKn4cK2mCxOXGMP2ck2C1a0sECyB82uw==", - "policyBinding": { - "alg": "HS256", - "hash": "BzmgoIxZzMmIF42qzbdD4Rw30GtdaRSQL2Xlfms1OPs=" - }, - "encryptedMetadata": "ZoJTNW24UMhnXIif0mSnqLVCU=", -} -``` - -## keyAccess - -| Parameter |Type| Description | Required? | -|---------------------|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------| -| `keyAccess` |Object| KeyAccess object stores all information about how an object key OR key split is stored, and if / how it has been encrypted (e.g., with KEK or pub wrapping key). | Yes | -| `type` |String| Specifies how the key is stored.

Possible Values:

remote
The wrapped key (see below) is stored using Virtru infrastructure and is thus not part of the final TDF manifest.
wrapped
Default for TDF 3.x and newer, the wrapped key is stored as part of the manifest.
remoteWrapped
Allows management of customer hosted keys, such as with a _Customer Key Server_. This feature is available as an upgrade path.
| Yes | -| `url` |String| A url pointing to the desired KAS deployment | Yes | -| `kid` |String| Identifier for the KAS public key, such as its thumbprint. The current preferred identifier can be looked up using the `kas_public_key` endpoint. For compatibility, our reference implementation uses the associated x509 certificate's fingerprint, although this may be a UUID or other simple string selector. | Yes | -| `sid` |String| A key split (or share) identifier. To allow sharing a key across several access domains, the KAO supports a 'Split Identifier'. To reconstruct such a key, use the `xor` operation to combine one of each separate sid, at least under the current encryption information type (`split`). |Optional|| `protocol` |String|Protocol being used. Currently only `kas` is supported| Yes | -| `wrappedKey` |String| The symmetric key used to encrypt the payload. It has been encrypted using the public key of the KAS, then base64 encoded. | Yes | -| `policyBinding` |Object| An object that contains a keyed hash that will provide cryptographic integrity on the policy object, such that it cannot be modified or copied to another TDF, without invalidating the binding. Specifically, you would have to have access to the key in order to overwrite the policy. | Yes | -| `encryptedMetadata` |String| Metadata associated with the TDF, and the request. The contents of the metadata are freeform, and are used to pass information from the client, and any plugins that may be in use by the KAS. The metadata stored here should not be used for primary access decisions.

Note: `encryptedMetadata` is stored as [a base64-encoded string](https://en.wikipedia.org/wiki/Base64#Base64_table). One example of the metadata, decoded and decrypted, could be, depending on specific needs:

{authHeader:"sd9f8dfkjhwkej8sdfj",connectOptions:{url:'http://localhost:4010'}} | Yes | | No | - -## policyBinding -| Parameter | Type | Description | Required? | -|-----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------| -| `alg` | String | The algorithm used to generate the policy binding hash. | Yes | -| `hash` | String | A Base64 encoding of HMAC(POLICY,KEY), where:

POLICY
`base64(policyjson)` that is in the “encryptionInformation/policy”
HMAC
HMAC SHA256 (default, but can be specified in the alg field described above)
KEY
Whichever Key Split or Key that is available to the KAS (e.g. the underlying AES 256 key in the wrappedKey.
- -### Key Sharing - -The `encryptionInformation` field allows storing not just one, but a list of `KeyAccess` objects. -This allows the same data encryption key to be encapsulated by multiple access services, -or for the key to be split using an XOR among two or more access services. - -To support both functionalities together, the `sid` identity field indicates if a split occurs -and allows for selection of the necessary components to reassmble the data encryption key. - -### Examples - - -Sample Key Content -Suppose we have encrypted our payload with a 128 bit AES data encryption key (DEK) of: - -##### Data Encryption Key (DEK) -``` -85 c0 b0 57 5b a0 a8 3c 04 48 b2 f4 85 96 e5 31 -``` - -##### Keys for alpha.kas - -``` ------BEGIN PRIVATE KEY----- -MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCxdjr8vTMO+wij -SaVJOOfiEHYXFkyTNhPG38Wth0rs/hLE3BiMQQbg/ct+FaX9Aa89bO6paRF32gZM -YoRruxsSfzR/Nby/hc5n5Gq7NVn+PyaU2hAJiNoQZEw7I6fxVGpB8T1ZfdwSSdex -3eA7F8vPJvkvXGYT1liw76B1nJc/QTmo9pLoM+3+i8teU8Tfb+I9r+yh0xHnNA5G -2Xl3WTaPZBQCPVn5tJZXgg4EpXhIe7XfykmrGBqMavOTc74xK9E8sw2vqd0uA1dO -VpNruqY6h/nt3hTyu68l4VW1eJlp4BswwePl843cWSmL9CQg1llfWvVH2FPq5zss -JCkyJWWBAgMBAAECggEAApb1eah3qSdt6vcZScIiNST1GjVluOy8OWXc1EFSDTcQ -dk25cHuG8ovVl0GQ3moywNhY+8EoI3n7p0v1P363oIuZbCVQO7HDzzWQvqpixbBt -e1Ta0M7N0tkp2R+WNPH8ynlPIkIRTvWDp6lzmx0n6N4aWw/zv+Sb/voCOxElzmMa -q+8/XNDpWaA4lchsM+8e1Gz8fudsPamHB5NiW202zlHt9ACm1O+pl5+9zdC8ljsZ -UMgl9T2dWWlFbBGpP3zZY/rsyUzj6i9BqNYVxJZxIffM3/JO9JWnrfC2Q/NohhNQ -TJEq7ZkPPC/tYTIBVanmM96qHi0vyVUGT2XiIEUXKQKBgQDlM+gCRBR86lmss/He -KgV0fxXLfqp9CPdNQZMBTpRdGsuF6pEdkaFUrXKkUMDyWlNgJrvf0oJ1ijTVbcAs -pFbIgc2aGmdlOrxUDG/iSzgVehEVUeeKiqjYKiXI1Z+ugeGTXCLqTqqCgS1gcdka -zgKavbhn7N1FLSGz25Tb3XZziQKBgQDGNbS2kT6/u4rD0kw5H+6GF0ClVRonsyt4 -jYNAB/Wa19/rGFjup/wYQ9GIIsRlA8GZ6YP+VhsXVVwjnEswnG6L1llihnTm0M0x -vdZV78Uf6pusf4pKmBeWWOFFbYk5NMtWYCggol0hpCL3vtMwwsELA8Y5NqD+eZB9 -iB4zsXFMOQKBgB9jZ1+AEUo2EcfL8NCa8ppMmSCAHTr4Ul27IDWqnDjP5ZVWVT82 -ZWCiTDPidzn5Ure1Nj9lpcYRAkFEQXAbpWLaG90Bxq0fSRE9jsjvwiN2zwYbbFkV -uh+4TepeDvsoAEtc788krMcoh51QmgnIsqScXLemwXqqvpXR+WXOw1z5AoGAGBSK -QevfbbfBIg04iXAhsFS+29c8+DnCPEElAvB0nD1BzPQGSehKrj//AsUGiycrrCE8 -kfewDuOl8AWa9OrsWzzNWzTumuQfKb3gfkxE7J26D/jmui1EIFXn+GFYXITXd0Tz -WxOesOmZ/fNHAROIFGh++pByergWH8obsTgLhbECgYEAj7IS3itupOyvuacMoJWJ -4yVcspFkc2iOK9oVH8b+mY0hr4Bi0HtM3tCfKC9XCYGvM9nltgaWWJL9JZPOLXhS -iUxl2q3BRO4KsniiF3cXQ2VlCK0UBNUkav+AGzFzMe3ie75Mkd4c8nxaZkiE4UTt -TYfBbQFCijGWZ+BNcIhNFYA= ------END PRIVATE KEY----- - - ------BEGIN PUBLIC KEY----- -MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsXY6/L0zDvsIo0mlSTjn -4hB2FxZMkzYTxt/FrYdK7P4SxNwYjEEG4P3LfhWl/QGvPWzuqWkRd9oGTGKEa7sb -En80fzW8v4XOZ+RquzVZ/j8mlNoQCYjaEGRMOyOn8VRqQfE9WX3cEknXsd3gOxfL -zyb5L1xmE9ZYsO+gdZyXP0E5qPaS6DPt/ovLXlPE32/iPa/sodMR5zQORtl5d1k2 -j2QUAj1Z+bSWV4IOBKV4SHu138pJqxgajGrzk3O+MSvRPLMNr6ndLgNXTlaTa7qm -Oof57d4U8ruvJeFVtXiZaeAbMMHj5fON3Fkpi/QkINZZX1r1R9hT6uc7LCQpMiVl -gQIDAQAB ------END PUBLIC KEY----- - - -``` - - - - -##### Keys for beta.kas - -``` ------BEGIN PRIVATE KEY----- -MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCllv16roMBdCNh -cyZdH/vsCcHDPJUEpnX7ejKtD22TuuX+SwCuOsPX3kUzk/aUhFryrTE2MEZXkF5H -/4tzb41SMaQrUg2QY2f11DOHxTdu0FPWl4hMK+8zrMpoaC6R3+RmXOXjsYsGDzX0 -utSu5nXmhf2xrIak9wPeuKqeQQ+KJjAzK9kkcZgyMX0z50jGgTrHbMxNzq63E6IA -UUTizJoCfAXNhvkkCxbhPyZEP6n8wJyUHj1Lvyz85d7WgJIRZyAV9dwhGsnAXM+m -cn99eUq0cAVjevSF0m48ozDb4OMyaFRlaCYRUyBqPLcnu7GVKT60CtMy17zAnuge -32rh7/lbAgMBAAECggEAHcKhwuNLWz8GvtRlsDX33mewgcjJFYFfUfeX1P+hV3wv -KsFLGYUpPopNkKQGnJGfEN9sqUsK0WD6eOEmLHR/hyax1TFVi7456HYfXsbknA9o -CfjI/7ujrXtgE1yqBgChuX33uTDnBgtEzLupTtfPl8M8IasatdpJQUWaMIAL7W1+ -EgOpto5rhSPcOl+PxlfOV3sJc63eeQHmyZeBbVZy1eG1CBrhXqSDInH13D3f6e+c -BizCKtqsu45DuJVjCgzRP6PKn4G582Z973N1hw1aLO6M8RoislkxsxLbfm0Cct37 -QZfHjK0puX0aKu4kgFBsHY1lv+J+ucnCGVKPOT7qzQKBgQDn//b9vE6IpKRoYqsx -yW1QOzTcnj3gsF+C2v89fvZex4FZZtvB4N5RmMrqJMrPmZwttniTkOuwvhu5hXr8 -XelBIS4MMk05iQKdAW5LpGoFLUAHnag5H8uuYJAGsNjohQlxTUXxWcHoCT5qTb2E -VIxpRyPmFThnOKGecK+zSuvypQKBgQC2uErvM8D+MlV8vyf7bmkiGxUFb/amQTRs -yuBxobe77JT1MavNodTOFiAuS5rildZq+uKAWEY934FtSyxCOGEvjHb/Yjdu32pt -HJdVtcPyGA3RB2fH5W+8q3QZZM0rF/KG59xIa5yDclSVNH0Y0qjM0a9KSRNDfEOU -ZuTMGcR7/wKBgQC5RL+JgYd1t4VTlvf/mkuhdqaQSA5CEJc1eI28HlfA+LFjI7D6 -8wiXQN1Kfnc3sgP2vXEs5t5RFoAtd1rvjk9no4eSVdk1ySQ9HZdm8LV5zNkFO/HL -LIkLiDF8Jl4R0avovzzLsFIZashdPBfMRXib2iPg6bFRPPhT/slQ9NPXwQKBgBeU -zUb1vPCRemrxGK3gX/0g1aOwAXsPaz6nKDRCFL5SGB9U28FcI2S9gkW3SDP59oQ0 -AMtjmR0fHUsHqpyZPiGu1SS8fj724ntWd0l+fd1esVnKxOANglAtKHymf7wSCSDU -B5/pE3f7Z2MiNQrhFRvp69+ActYA0Y/zf4+/u5XtAoGAKKxydBcbPHmyZS8fB0AP -VmAY2SVlTBygmoaZDndClKWzmIUMDrMv2pzeEJtUR25lfbHMoiQNcGQXucS2uYLl -NkQIo2w9qaCNtEV+Ce7jFNUUBdHDRXXmtjSbIaeFPuu0mQxBREyBk5K9Tby/MrE4 -md9VSrOSDbgVkPmnKBfR8tg= ------END PRIVATE KEY----- - - ------BEGIN PUBLIC KEY----- -MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApZb9eq6DAXQjYXMmXR/7 -7AnBwzyVBKZ1+3oyrQ9tk7rl/ksArjrD195FM5P2lIRa8q0xNjBGV5BeR/+Lc2+N -UjGkK1INkGNn9dQzh8U3btBT1peITCvvM6zKaGgukd/kZlzl47GLBg819LrUruZ1 -5oX9sayGpPcD3riqnkEPiiYwMyvZJHGYMjF9M+dIxoE6x2zMTc6utxOiAFFE4sya -AnwFzYb5JAsW4T8mRD+p/MCclB49S78s/OXe1oCSEWcgFfXcIRrJwFzPpnJ/fXlK -tHAFY3r0hdJuPKMw2+DjMmhUZWgmEVMgajy3J7uxlSk+tArTMte8wJ7oHt9q4e/5 -WwIDAQAB ------END PUBLIC KEY----- - - -``` - -##### Keys for local.hsm - -``` ------BEGIN PRIVATE KEY----- -MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDcv14/YES4f5JA -91fN27GDP2z9OzLcpSDubQERdYdb22SoHmGgC0CIODs9TP2DSfxicpBfdR3KHqiD -4MaIBE32YSqbLFO9pvaXQ9UoTyFyBa/fGD5C2Pf/ER1ozqVFthBf++BjWy48/abx -qlw1zXvr/joyA/soyiMlIgIxOCob398dzGIhJmuJLi8VV4YnIX9nalwGhT7Epn0S -B5gjwX2valjXNxTq+eJl5iiOAjqS8UQJ+ySXjgw+PAw5qrSllfWY6Yx4cTKg72fk -8E3PRt82D+gRwCkZkwfFUjhhnd1+AvwhS0+XdXy5C7ynagW4D+0Tn5sHIzlfw/J+ -p9aCMgiNAgMBAAECggEAJXGOfoiJT5RQDhYGfkQoKZ+eEJw0hem6msbBmiEJ60Jd -Igk5PQj7kr+bCMxg6h6oIVjWdWKrwWeO5QPBGTxFryePLxAHSlGiXUkjxHkbrrgZ -O2nk0bj04/6WsvruXNNDlsxmJORIBQ9vfGmNx5CJ1x9h5q73MNWMvZU1svyYY+62 -GY4YsizHwJDNWtN7AoD7yrA5AyjNsGYoSznRF6FSTYok4baTSbl9B/FNibzfwLO1 -oC6zaTupQ9q7o6t9+0Vm55kT1L88N8NQ4AF/7qWNMVJP2BXYxC64+WUyXQxWxOCQ -bXcmu2je0DBlwVpAwQHzeH4PgDmqB35h049e+bzaTwKBgQD+Lcvt6P3W3CITj4Hp -IX5p5DkVEC+ijRsP2zwXueXPj243jF82oNxi8OyM5SOq/IEIhKiSW/UDZ8InFJR8 -/Sv+/qVq3R/jDlQSRkT0yvlvKaWm+i66MSpJBFD4lmbs/FiL8ZN7wBMMui+IwnJ+ -OrEy4BGmBdZGEwNcVyFeEzPFdwKBgQDeVEDWOUyKvhlQ/icAQ99jxaFdi3NJTvrh -uDbjpV3aKMWHzvjeXPsiCsUXW6rQuRMbnejprL+P0iiF2pLwJbR4EhjZqDw6jxUk -bD0zxpvO+ew8l6CFQbQmQRlL/lKLMpyUUWVbUYzUE9Wm/JsWzbxlyl6fFuXYLgLG -ig+kDyazGwKBgCkBoG3QcetQ9lprg4zl72wL+r2QL+8sjpofR3GYdx/mRuTFS7MX -fpajwbX1Xay/Md368Osz1LJo8eS2KEKF4awwzuUPqY5LCHsuRP+tI1KwyF3I7PLy -7Zx8CsggE5jWGT7yiVWkpi4ed367yBbfRykrBw3e0TPa62bhU6vGs0p/AoGBAI81 -KgZTJjCAPoJjEvAix/PWSxicSIhB7WwTYpfD3u41MPdHpBpnPgQxd76R9zc23038 -qxhJg6K6NgvyPI+fWd21mngo25LEs1OgvNNq7NWnOjnVWTo8ljPF3uuKR9UNproK -rATkRJgeppJHSAaqQt42OjizYR2clYEZUPXWJJFdAoGBANp2jTfZAMyEPDf1Cqei -+J92wNCvVEovlGBmkbkGX32NjFSObod7c8kINPXxL3ylgdqq/0Ws1Go0y10eKQok -5mlwwQSULq6pf5dT0JQSjQ73EXXhIGDJFeHMPD1mI3OXfyRBLz61Vq2b6uc70qHY -WRvcu5cqFhx9Fgvs9D5+JA+/ ------END PRIVATE KEY----- - - ------BEGIN PUBLIC KEY----- -MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3L9eP2BEuH+SQPdXzdux -gz9s/Tsy3KUg7m0BEXWHW9tkqB5hoAtAiDg7PUz9g0n8YnKQX3Udyh6og+DGiARN -9mEqmyxTvab2l0PVKE8hcgWv3xg+Qtj3/xEdaM6lRbYQX/vgY1suPP2m8apcNc17 -6/46MgP7KMojJSICMTgqG9/fHcxiISZriS4vFVeGJyF/Z2pcBoU+xKZ9EgeYI8F9 -r2pY1zcU6vniZeYojgI6kvFECfskl44MPjwMOaq0pZX1mOmMeHEyoO9n5PBNz0bf -Ng/oEcApGZMHxVI4YZ3dfgL8IUtPl3V8uQu8p2oFuA/tE5+bByM5X8PyfqfWgjII -jQIDAQAB ------END PUBLIC KEY----- - - -``` - -#### Shared Key Access - -If we want to allow access to the DEK from two different KAS, we can encapsulate -the DEK twice. - -``` -- policyBinding: | - Wm1ReFkyWm1PREk0WldaaU5qQXpOamszTUdJMk5HSXdNREkyTTJGbE1XUXdaVFl6TUdFeU9EWTJO - RE01WVRkaE1EbGpPR0l6TUdVM01qVm1ZVFZrT0E9PQ== - url: alpha.kas - wrappedKey: | - b3FiS2dxSllrYzUydU1FWEFmOXNyWmdUVHo1WU95L1hCWDl3WkdYcDRmbnpRNGVET0ZNS3JYMEVI - djVYUGd0VVBYMHRBTDJHbEZCTnhseTdpMjV4UDl0M25GLzlXOVFNZEU1NmprWm5PT2l1Z3Fjb09i - UDdZMlhCa2JKZXlwcnN4VngwdlovWGxFejlycFZNeUdKQ0JuUGFDM3pQVUhkM1BhQTlucS9xemZE - dmtXTjVBTUVNWkI0L1I4b3Y5L2drN0dBQ0dubzF6V3lnbFhGaUxrVjBQVkYrZnJWOUtnbWJtLy8w - clE2NWxWMnQ3eVpOKzkxOTdhUUpqNmRxOWVwazBMUTY5S0xUWDZ6RVIrS3orWmE1TENoZVlxQWd6 - eUYyUXVwTGMrVTFMdElpNC8rYzhpNGsrUzZQY1JoM1BzbHk0Zlp2YVRrTVh5ZFVMMzVsZGJmTzBR - PT0= -- policyBinding: | - Wm1ReFkyWm1PREk0WldaaU5qQXpOamszTUdJMk5HSXdNREkyTTJGbE1XUXdaVFl6TUdFeU9EWTJO - RE01WVRkaE1EbGpPR0l6TUdVM01qVm1ZVFZrT0E9PQ== - url: beta.kas - wrappedKey: | - V3VJRzQvRXhXL0ExaWZsdVVFNUg5SEdzSGxIM0syb3UzdXYzK1MyU2VLckV2b0xUenZTU1loaUIz - bW1MSVBPU0dUem1naW5tcXkvK3JJSmh3Wk1SNWMyL2pYQks0R2wrVWFwZFAvc09zbi9MWGdvY1FB - Z0pKdlNrS2dKYzV2b1J4cURhTmQrRjVwQ1YvdEpXT0dvQUE1ZkxldmFiTEduS0FhTlR3RVJTRzlU - WXJLM1pQY2ZGQnlUbDBkR2lSdmgyeHZwMmM4MWRja2grQTZ6TkxsRjNTV0t3cW8xeXNSZFk1UXhS - UENHdWlNaUF4RnZNSzVwbjBKZERUSFhwR3NQMUZsOE1UQ1BJWE9vSG92cm9nZDlSZDc5WGt1NVdT - U3F4cTJZc25BMnBMd2FvbWY5UDRYV2J0YWtSOU5OclJUV3JmZVI5RHRTaWg3SU5YcFlqa0w3cjhR - PT0= - -``` - - -#### Split Key Access - -If we want to require two different KASes to approve access to the DEK, we use -a split with each fraction going to a different KAS. Using a nonce with XOR -allows no information to be gained without having (at least some of) each -fraction. - -``` -- policyBinding: | - TkRrNE9HSTRZV001WVROa09HWmhZVGd3TWpOaE5qWTRZMlF3WldZNU4yVmhNRGN3TlRWaE56VTJP - VFpsT0RsaFl6QmhPVEk0TXpVMk5tUm1OVFk0WkE9PQ== - sid: split-alpha.kas - url: alpha.kas - wrappedKey: | - SkxtU2QxVDZwMlhNdmQrd2JHSjRPK3p1d005V2xWQTBvR0pwVThzMTR5RWlMMzlza0NQSG9DaEpr - TXpLTXF1TzdnMUxWS1V3ZUcwa29XTytPNkxvMFhGUnNrTllsdUs1Y1hYRk9CZ1c4MHh4SUtvb2NF - bmtOMGdxRjgrejZtNElQMmJZcTNVYVloand2SFpZTmYxZGo5dXNTeUw1cWJ3d2U2clNaZWdpM0w1 - VE5oY3I4NmxMNFgvOHZ1b3UwbWtaT1Z2N25CamplckdwdVZHZmlrRk0rV1pIczI2WnpCRExycXZL - TTJxQjRFbEFTQ3F4L1NOUno4NUpCVTlDa3NybDZ3OUdQNlNzdk9OV3BBR0xtUndmYzU5bUpaZE9M - cmczSlhaejN6K212R0IzSjdCWkY0NENyWEtZd3BaL0FvRXNHMXRmOUl4SWZJZDU1Z2N4T09rczdB - PT0= -- policyBinding: | - WVRneFpUbGhOelpqWm1JNU16aG1ZemhpWXpWbE5qSXpNakZqWlRBeVpqbGhPR1ExTnpZM1pUZzRO - VGt6WlRRNVlUUTVZelU0Wm1FME5EVXpPRGMzTVE9PQ== - sid: split-beta.kas - url: beta.kas - wrappedKey: | - aDNEOEUvKzRDZzNGVUVjVEhEbDBoS0hxN2FqbUZMVmEyYUh2UHlTVUl5ZlhSY3Q0dFFCSi9MNTB1 - VlBabXQ0RFZRK3NKYm96MXRRaG9mUWwyMjcwYURVMHNPSzZicUdQZVUyVWNka2tFQXVSQlpLcWtx - eHhkR0wzOXFQTUtBSFpBYlZkSkUrSkpNY2d5cFlHemQxdVNlNWFTWEFBRTZ2TTdrQ1ZYbXg2Y3dp - blBQbnF2MFFFOEZDU253b0dPQkw4bnNTWGRiTDVKQkE1S0liZFBMbnVXbW9GNWtmZnFzYngyU1V1 - ZzUxR2tYUjlOYVQxWW1RRDVEU0wrN0ZCQjFXQ3VNKzB5RGhoemZrbFluWVBrdENDTmVlb1RnQkpW - R2NKTGYzUkdLMVIvOTJKdTYrL0JqWE1YdzVmbExIc2FQR0hodGxxZFQyRFNJVW1NTEY2eWxRYzNn - PT0= - -``` - - - -#### Hybrid Key Access - -Another scneario is we want to allow break-glass with a local HSM or KAS cache, -but fall back to remote KASes. This can be accomplished by sharing each split -with the HSM. - -``` -- policyBinding: | - TkRrNE9HSTRZV001WVROa09HWmhZVGd3TWpOaE5qWTRZMlF3WldZNU4yVmhNRGN3TlRWaE56VTJP - VFpsT0RsaFl6QmhPVEk0TXpVMk5tUm1OVFk0WkE9PQ== - sid: a - url: alpha.kas - wrappedKey: | - UVRiUnZteDFFc1I3S3pHenBLeVdncEFnVGt6aW9zVm5vc3NDM05mcVNUOS80cDhvdDZwMTJWQU93 - OVVZRUlVN1NYTVZtU3FoSlVjdDlxUlRzWGEyTkttK3NkVzdYVzNldjg2cDFzdWwyRjc5UXN6N0xM - OTROS2kvelMxQjNDQXBNR1djanhuZ1F4VDNPcVNLRlRRcXBxS2JPYmF1UHhDTGZvZldKazBMVDdF - WStuRTE0Y2FSTTBhbGp5b0FoL3JQYlljQ2EyTjNYNUhqZTR6ejZNRm1ZanVKUTQyS3Z6Nm5VWHpT - TVRoMEpuSGFJOW4xZlBDTWNXd1RQYldFS0I3VWVMUGkvVmY1aEdoTFhUTVE3ZTNMVjdGMnlHNzh6 - d1dWeENkb05MKzdsSTFyVDFXTWc3RmVUR3JSSERyV2hOM091Rjk4Uk9SQlpaS2Jrc1pjTjBnZE9n - PT0= -- policyBinding: | - WVRneFpUbGhOelpqWm1JNU16aG1ZemhpWXpWbE5qSXpNakZqWlRBeVpqbGhPR1ExTnpZM1pUZzRO - VGt6WlRRNVlUUTVZelU0Wm1FME5EVXpPRGMzTVE9PQ== - sid: b - url: beta.kas - wrappedKey: | - SjRlOHNKVDBVNjJ5ODY4NXJqZGMydUhZem5MREc5NEI2YU9ybVgyTHJlazlXa29sVDh5bzZnYjZ4 - RkxGS1pWSzBjV2tpSXR5ZzBBWDVvalBOZWtpM0lEbjlhQnlSQndpWnJ0cjRTNTFPMFZ3bnhXOUc2 - Q21KTWNqQnZQYzJYSGpReUtvOHJIQXhmN3d3WWx3NVU1NXJDdkFRSUEzSHoxQUFjdExLZkVBamh6 - QXhnSTBFVjlPbG5QL0lkMVVtZ2J5ZkRhNTdvTU1MWVlDMXFtem5IVEpZY0dyUUwrTjFpNmxBTUhr - R0xOOVJ3ZFpBTkd6YlJEWFFkYUFvOUgrY2dmMGlrU1lYWkcwNGdHdWJ2WGpEdlo1cFdUaU51MFVG - dmh5cjY4UGZTUmNzVjJiQ29sQWZZTllEc3BvckRyMHZMQUY1aTNpc3ZlNWVjaE1BM2thNzNyNXRB - PT0= -- policyBinding: | - TkRrNE9HSTRZV001WVROa09HWmhZVGd3TWpOaE5qWTRZMlF3WldZNU4yVmhNRGN3TlRWaE56VTJP - VFpsT0RsaFl6QmhPVEk0TXpVMk5tUm1OVFk0WkE9PQ== - sid: a - url: local.hsm - wrappedKey: | - Tnp0U1NXRXVxU0dlVGRLRGJMK3gzMGt6bEsrdE9NdTYyV3lGWFdJbDdNdkx0eHZQWUpCUEhNZG1v - Y0MvekdzOVZyaFU3S2JvV3hzKy9GWXkrTGgvdlR5WEFnQ1IxSGVsSjFTNzdQYWFvbVdSVG1kak5m - Y1VOVEZNTUkxMjdoSGVjN3NHUzRLK3U4TlRxMzlHVHdLR2F4Nm16b2NWVnFRVEtMN2xaUWRxalZq - TzJTejV3YzZ1STlzcHEwYnhKR2piWHlGSkR0V0VqTVowOFRZQ0ROT2N0UmhCT0t5QnA0RVBMVjk2 - dTRSakNvWE0yVWN2aUpkY0doVG9RZjJINnVhb1BSOVcxR2ZNWTdVUDNRSlMyMEpndDdqaG9hcGly - MXlBSGxBVGdZamxhNm1kbjl4MGljdDBXd2Z1Yjc3VERUMy9VR25oRnYvV1BLaFJWM1BUOStqN2Zn - PT0= -- policyBinding: | - WVRneFpUbGhOelpqWm1JNU16aG1ZemhpWXpWbE5qSXpNakZqWlRBeVpqbGhPR1ExTnpZM1pUZzRO - VGt6WlRRNVlUUTVZelU0Wm1FME5EVXpPRGMzTVE9PQ== - sid: b - url: local.hsm - wrappedKey: | - Z0dIRmdRMFZNR042VnpCMTBHTjlUcUlvUUpvU0FyUmR3MXhnZld0UEhBaGlkTTVRVE5nZ3JqYk1D - SFk0MnFidEQrcUErV3lsQmlZdktwMm9QdGU5d1E3T0FONVBRSTlueWpycnp6SCtJd1BkWnI3aXl6 - VzFPL0Nwd0hKblNabXlEOE41UTNna1U2S1lLc0hPdWVsYlYzb2U4OHo1d1UrWTdxbW9PN1B5OHcx - TnpsMnRqcEV1N2w3eE9oVGNySUgrVDhzUkZBcTV3Yit5RzRRdEFTeU9QeEhiMTNDdjlZUUcxL1FZ - bGg3TzlkZjdEL3A5YXlybEt0VFF6RzdOTzEydGFSODY2endmSjVFYXA5Slh6T25TZmt3R0JQRUJx - OVV1WUw4RXR3OFlOOW1TbGxBTmJKblVnVWJ3eENnbDcxQ2JORFRTTGJ1c3FPcGtKakw2SW9naGF3 - PT0= - -``` diff --git a/schema/tdf/Manifest.md b/schema/tdf/Manifest.md deleted file mode 100755 index 2b24c46..0000000 --- a/schema/tdf/Manifest.md +++ /dev/null @@ -1,294 +0,0 @@ -# Manifest - -## Summary - -The `manifest.json` file must be in JSON format. To process a TDF payload (such as an image, text file, etc.), the `manifest.json` is used to store the data needed for a Policy Enforcement Point (PEP) to make an access decision. - -From the top level, the TDF manifest contains only two properties: `payload` and `encryptionInformation`. Each of which are objects, and are decomposed in their own sections below. - -- [Payload](#payload) -- [Encryption Information](#encryptioninformation) - - [Method](#encryptioninformationmethod) - - [Integrity Information](#encryptioninformationintegrityinformation) - - [Segment](#encryptioninformationintegrityinformationsegment) -- [Assertions](#assertions) - -If you'd like to see a real manifest created using the TDF client, check it out [here](#authentic-manifest). - -## TDF Spec Version - -|Parameter|Type|Description|Required?| -|`tdf_spec_version`|String|Semver version number of the TDF spec.|Yes| - -## Payload - -The payload contains metadata required to access the TDF's payload, including _how_ to process it (protocol), and a reference to the local payload file. - -```javascript -"payload": { - "type": "reference", - "url": "0.payload", - "protocol": "zip", - "isEncrypted": true, - "mimeType": "application/pdf", -} -``` - -|Parameter|Type|Description|Required?| -|---|---|---|---| -|`type`|String|Type of payload. The type would be a description of where to get the payload. Is it contained within the TDF or is it stored on a remote server?

Currently a type of `reference` is the only possible type.|Yes| -|`url`|String|A url pointing to the location of the payload. For example, `0.payload`, as a file local to the TDF.|Yes| -|`protocol`|String|Designates which protocol was used during encryption. Currently, only `zip` and `zipstream` are supported and are specified at time of encryption depending on the use of non-streaming vs. streaming encryption.|Yes| -|`isEncrypted`|Boolean|Designates whether or not the payload is encrypted. This set by default to `true` for the time being and is intended for later expansion.|Yes| -|`mimeType`|String|Specifies the type of file that is encrypted. If no `mimeType` is provided then `application/octet-stream` should be assumed. |No| - -## encryptionInformation - -Contains information describing the method of encryption. As well as information about one or more Key Access Servers which own the TDF. - -```json -"encryptionInformation": { - "type": "split", - "keyAccess": [], - "method": {}, - "integrityInformation": {}, - "policy": "eyJ1dWlkIjoiNGYwYWIxMzEtNGRmZS00YmExLTljMDQtZjIzZTE0MDMyNzZhIiwiYm9keSI6eyJhdHRyaWJ1dGVzIjpbXSwiZGlzc2VtIjpbInVzZXJAdmlydHJ1LmNvbSJdfX0=" -} -``` - -|Parameter|Type|Description| -|---|---|---| -|`type`|String|The type of scheme used for accessing keys, and providing authorization to the payload. The schema supports multiple options, but currently the only option supported by our libraries is `split`.| -|`keyAccess`|Array|An array of keyAccess Objects. This object is defined in its own section: [Key Access Object](KeyAccessObject.md)| -|`method`|Object|The encryption method object is defined below: [method](#encryptioninformationmethod)| -|`integrityInformation`|Object|`integrityInformation` is defined below in its own section: [integrityInformation](#encryptioninformationintegrityinformation)| -|`policy`|String|The policy object which has been JSON stringified, then base64 encoded. The policy object is described in its own section: [Policy Object](PolicyObject.md)| - -## encryptionInformation.method - -An object which describes the information required to actually decrypt the payload once the key is retrieved. Includes the algorithm, and iv at a minimum. - -```json -"method": { - "algorithm": "AES-256-GCM", - "isStreamable": true, - "iv": "D6s7cSgFXzhVkran" -} -``` - -|Parameter|Type|Description| -|---|---|---| -|`algorithm`|String|The algorithm used for encryption. Currently the two available options are `aes-256-gcm`.| -|`isStreamable`|Boolean|`isStreamable` designates whether or not a TDF payload is streamable. If it's streamable, the payload is broken into chunks, and individual hashes are generated per chunk to establish integrity of the individual chunks.| -|`iv`|String|The initialization vector for the encrypted payload.| - -## encryptionInformation.integrityInformation - -An object which allows an application to validate the integrity of the payload, or a chunk of a payload should it be a streamable TDF. - -```json -"integrityInformation": { - "rootSignature": { - "alg": "HS256", - "sig": "M2E2MTI5YmMxMWU0ODIzZDA4YTdkNTY2MzdlNDM4OGRlZDE2MTFhZjU1YTY1YzBhYWNlMWVjYjlmODUzNmNiZQ==" - }, - "segmentHashAlg": "GMAC", - "segments": [], - "segmentSizeDefault": 1000000, - "encryptedSegmentSizeDefault": 1000028 -} -``` - -|Parameter|Type|Description| -|---|---|---| -|`rootSignature`|Object|Object containing a signature for the entire payload, and the algorithm used to generate it.| -|`rootSignature.alg`|String|The algorithm used to generate the root signature. `HS256` is the only available option currently.| -|`rootSignature.sig`|String|The signature for the entire payload.
Example of signature generation: `Base64.encode(HMAC(BinaryOfAllHashesCombined, payloadKey))`| -|`segmentHashAlg`|String|The name of the hashing algorithm used to generate the hashes for each segment. Currently only `GMAC` is available.| -|`segments`|Array|An array of objects containing each segment object. A segment is defined in its own section: [segment](#encryptioninformationintegrityinformationsegment)| -|`segmentSizeDefault`|Number|The default size of each chunk, or segment in bytes. By setting the default size here, the segments array becomes more space efficient as it will not have to specify the segment size each time.| -|`encryptedSegmentSizeDefault`|Number|Similar to `segmentSizeDefault` - the default size of each chunk of _encrypted_ data, in bytes.| - -## encryptionInformation.integrityInformation.segment - -Object containing integrity information about a segment of the payload, including its hash. - -```json -{ - "hash": "NzhlZDg5OWMwZWVhZDBjMWEzZTQyYmFlODA0NjNlMDM=", - "segmentSize": 14056, - "encryptedSegmentSize": 14084 -} -``` - -|Parameter|Type|Description| -|---|---|---| -|`hash`|String|A hash generated using the specified `segmentHashAlg`.

`Base64.encode(HMAC(segment, payloadKey))`| -|`segmentSize`|Number|The size of the segment. This field is optional. The size of the segment is inferred from 'segmentSizeDefault' defined above, but in the event that a segment were modified and re-encrypted, the segment size would change.| -|`encryptedSegmentSize`|Number|The size of the segment (in bytes) after the payload segment has been encrypted.| - -## assertions -Assertions contain metadata required to decrypt the TDF's payload, including _how_ to decrypt (protocol), and a reference to the local payload file. - -```javascript -"assertions": [ - { - "id": "123qwerty456", - "type": "handling", - "scope": "payload", - "appliesToState": "encrypted", - "statement": {/* Statement Object */}, - "binding": { - "method": "jws", - "signature": "ZGMwNGExZjg0ODFjNDEzZTk5NjdkZmI5MWFjN2Y1MzI0MTliNjM5MmRlMTlhYWM0NjNjN2VjYTVkOTJlODcwNA==" - } - } -] -``` - -| Parameter |Type| Description |Required?| -|---------------------|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| -| `id` |String| A unique local identifier used for binding and signing purposes. Not guaranteed to be unique across multiple TDOs but must be unique within a single instance. |Yes| |Yes| -| `type` |String| Describes the type of assertion (`handling` or `other`). |Yes| -| `scope` |String| An enumeration of the object to which the assertion applies (`tdo` or `payload`). |Yes| -| `appliesToState` |String| Used to indicate if the statement metadata applies to `encrypted` or `unencrypted` data. |No| -| `statement` |Object| `statement` is defined below in its own section: [statement](#assertionsstatement) |Yes| -| `binding` |Object| Object describing the binding. Contains a hash, and an algorithm used. |Yes| - -## assertions.statement -Object containing information applying to the scope of the assertion. May contain rights, handling instructions, or general metadata. - -```javascript -{ - "schema": "https://someschema.com/schema", - "format": "json-structured", - "value": { - "format": "json-structured", - "value": { - "Xmlns": "urn:nato:stanag:4774:confidentialitymetadatalabel:1:0", - "CreationTime": "2015-08-29T16:15:00Z", - "ConfidentialityInformation": { - "PolicyIdentifier": "NATO", - "Classification": "SECRET", - "Category": { - "Type": "PERMISSIVE", - "TagName": "Releasable to", - "GenericValues": [ - "SWE", - "FIN", - "FRA" - ] - } - } - } - } -} -``` - -|Parameter|Type| Description | -|---|---|----------------------------------------------------------------------------------------------| -|`schema`|String| A reference to the schema used in the statement value | -|`format`|String| Describes the payload content encoding format (`json-structured`, `base64binary`, `string`). | -|`value`|String| Payload content encoded in the format specified. | - -## assertions.binding -Object containing a signature of the assertion that will provide cryptographic integrity on the assertion object, -such that it cannot be modified or copied to another TDF, without invalidating the binding. - -```javascript -{ - "method": "jws", - "signature": "ZGMwNGExZjg0ODFjNDEzZTk5NjdkZmI5MWFjN2Y1MzI0MTliNjM5MmRlMTlhYWM0NjNjN2VjYTVkOTJlODcwNA==" -} -``` -| Parameter |Type| Description | -|-------------|---|-----------------------------------------------------------------------------------------------------------------------| -| `method` |String| The method, or algorithm used to generate the hash usually JWS. |Yes| -| `signature` |String| A base64 represenation of the assertion signature which was created using the method described in the 'method' field. |Yes| - - -## Authentic Manifest - -Here is the JSON from an actual `.tdf` file, created by the TDF client. - -```json -{ - "tdf_spec_version": "1.0" - "payload": { - "type": "reference", - "url": "0.payload", - "protocol": "zip", - "isEncrypted": true - }, - "encryptionInformation": { - "type": "split", - "keyAccess": [ - { - "type": "wrapped", - "url": "http://kas.example.com:4000", - "protocol": "kas", - "wrappedKey": "YBkqvsiDnyDfw5JQzux2S2IaiClhsojZuLYY9WOc9N9l37A5/Zi7iloxcqgFvBFbzVjGW4QBwAHsytKQvE87bHTuQkZs4XyPACOZE/k9r+mK8KazcGTkOnqPKQNhf2XK4TBACJZ6eItO5Q1eHUQVLKjxUfgyx2TBDfhB/7XifNthu+6lFbKHmPl1q7q1Vaa/rpPRhSgqf89x5fQvcSWdkuOH9Y4wTa8tdKqSS3DUNMKTIUQq8Ti/WFrq26DRemybBgBcL/CyUZ98hFjDQgy4csBusEqwQ5zG+UAoRgkLkHiAw7hNAayAUCVRw6aUYRF4LWfcs2BM9k6d3bHqun0v5w==", - "policyBinding": { - "alg": "HS256", - "hash": "ZGMwNGExZjg0ODFjNDEzZTk5NjdkZmI5MWFjN2Y1MzI0MTliNjM5MmRlMTlhYWM0NjNjN2VjYTVkOTJlODcwNA==" - }, - "encryptedMetadata": "OEOqJCS6mZsmLWJ38lh6EN2lDUA8OagL/OxQRQ==" - } - ], - "method": { - "algorithm": "AES-256-GCM", - "isStreamable": true, - "iv": "OEOqJCS6mZsmLWJ3" - }, - "integrityInformation": { - "rootSignature": { - "alg": "HS256", - "sig": "YjliMzAyNjg4NzA0NzUyYmUwNzY1YWE4MWNhNDRmMDZjZDU3OWMyYTMzNjNlNDYyNTM4MDA4YjQxYTdmZmFmOA==" - }, - "segmentSizeDefault": 1000000, - "segmentHashAlg": "GMAC", - "segments": [ - { - "hash": "ZmQyYjY2ZDgxY2IzNGNmZTI3ODFhYTk2ZjJhNWNjODA=", - "segmentSize": 14056, - "encryptedSegmentSize": 14084 - } - ], - "encryptedSegmentSizeDefault": 1000028 - }, - "policy": "eyJ1dWlkIjoiNjEzMzM0NjYtNGYwYS00YTEyLTk1ZmItYjZkOGJkMGI4YjI2IiwiYm9keSI6eyJhdHRyaWJ1dGVzIjpbXSwiZGlzc2VtIjpbInVzZXJAdmlydHJ1LmNvbSJdfX0=" - }, - "assertions": [ - { - "id": "123qwerty456", - "type": "handling", - "scope": "payload", - "appliesToState": "encrypted", - "statement": { - "format": "json-structured", - "value": { - "Xmlns": "urn:nato:stanag:4774:confidentialitymetadatalabel:1:0", - "CreationTime": "2015-08-29T16:15:00Z", - "ConfidentialityInformation": { - "PolicyIdentifier": "NATO", - "Classification": "SECRET", - "Category": { - "Type": "PERMISSIVE", - "TagName": "Releasable to", - "GenericValues": [ - "SWE", - "FIN", - "FRA" - ] - } - } - } - }, - "binding": { - "method": "jws", - "signature": "ZGMwNGExZjg0ODFjNDEzZTk5NjdkZmI5MWFjN2Y1MzI0MTliNjM5MmRlMTlhYWM0NjNjN2VjYTVkOTJlODcwNA==" - } - } - ] -} -``` diff --git a/schema/tdf/PolicyObject.md b/schema/tdf/PolicyObject.md deleted file mode 100755 index 0d3cdf6..0000000 --- a/schema/tdf/PolicyObject.md +++ /dev/null @@ -1,33 +0,0 @@ -# Policy Object - -## Summary - -The Policy Object is defined by the client at the time of the TDF creation. It contains the information required by a Policy Enforcement Point (PEP) to make an access decision. The Policy Object is stored in the [manifest.json](Manifest.md) for a TDF. - -A PEP uses the Policy Object to decide whether to grant access to the TDF payload. The entity or user requesting access must be in the `dissem` (dissemination) list _AND_ must possess entitlements that satisfy all the data [Attributes](AttributeObject.md). - -## Example - -```javascript -{ -"uuid": "1111-2222-33333-44444-abddef-timestamp", -"body": { - "dataAttributes": [], - "dissem": ["user-id@domain.com"] - }, -} -``` - -## uuid - -|Parameter|Type|Description| -|---|---|---| -|`uuid`|String|A unique [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) for the TDF's policy.| - -## body - -|Parameter|Type|Description|Required?| -|---|---|---|---| -|`body`|Object|Object which contains information about the policy required for the PEP to make an access decision.|Yes| -|`body.dataAttributes`|Array|An array of attributes a user needs to request access. An Attribute Object is defined in its own section: [Attribute Object](AttributeObject.md).|Yes| -|`body.dissem`|Array| An array of unique user IDs. It is used to explicitly list users/entities that should be given access to the payload.|Yes| diff --git a/schema/tdf/README.md b/schema/tdf/README.md deleted file mode 100644 index da16f5a..0000000 --- a/schema/tdf/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# TDF Schemas - -Attributes are represented by [Attribute Objects](AttributeObject.md) - -Attributes that entities "need" in order to access data are referred to as "data attributes" and are represented by [Policy Objects](PolicyObject.md) - -A TDF file consists of: - -* Encrypted payload -* [manifest.json](Manifest.md).