✨ Initial import of virtru/tdf-spec

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+### Proposed Changes
+
+*
+
+### Checklist
+
+- [ ] A clear description of the change has been included in this PR.
+- [ ] Spec Semver version has been updated in the VERSION file
+- [ ] Tagged this branch with new semver version and an annotation describing the change (ex: `git tag -s 4.1.0 -m "Spec version 4.1.0 - did a thing"`)
+- [ ] All schema validation tests have been updated appropriately and are passing.
+- [ ] Version numbers have been updated as per the [Versioning Guidelines](../CONTRIBUTING.md#verison-changes).
+- [ ] Major/minor version changes only: A writeup has been included discussing the motivation and impact of this change.
+- [ ] Major/minor version changes only: The minimum wait time has elapsed.
+- [ ] Project version changes only: I have updated both the `VERSION` file and the `git tag`.
+- [ ] This change otherwise adheres to the project [Contribution Guidelines](../CONTRIBUTING.md).
+- [ ] Every item in this checklist has been completed.

.gitignore

@@ -0,0 +1,2 @@
+*~
+.DS_Store

AttributeObject.md

@@ -0,0 +1,47 @@
+# Attribute Object
+
+## Summary
+An Attribute Object contains attribute information the TDF3 system uses to enforce attribute-based access control (ABAC). Attributes are used in both the [PolicyObject](PolicyObject.md) to define the attributes that a subject "needs" to gain access in an ABAC sense, and in the [ClaimsObject](ClaimsObject.md) to assert the attributes that an actor "has".
+Access decisions are made by comparing the attributes a subject has with the attributes a policy requires.
+
+Attributes that a subject (or actor, or entity) "has" are referred to as "subject attributes".
+
+Attributes that subjects "need" in order to access data are referred to as "object attributes".
+
+The _attribute_ field must be both unique and immutable as it is the reference id for the attribute. All of the other fields are mutable. The attribute string contains three pieces of information - the authority namespace, the attribute name, and the attribute value.
+
+When encrypting, the client determines which attributes a subject must have in order to decrypt the payload and applies those attributes to the file's [Policy Object](PolicyObject.md).
+
+When a decrypt is requested, the KAS checks the [Policy Object](PolicyObject.md) against the [Claims Object](ClaimsObject.md) from the requesting client to 
+ensure the attributes that an entity "has" satisfies those that an entity "needs".
+
+If this check succeeds, the KAS permits a decrypt operation and returns a valid key which the client can decrypt and use to expose the file contents.
+
+The public key is used to wrap the object key or key splits on TDF3 file creation. On decrypt, the kasUrl defines where this key or key split can be rewrapped.
+
+The AttributeObject alone does not define how the KAS will compare a subject attribute to an object attribute when making an access decision.
+The KAS uses the namespaced object attributes in the [PolicyObject](PolicyObject.md) look up attribute policies from the cognizant authority
+to make its policy decisions. Clients writing policies should use best available information from their organizations to select which AttributeObjects to include to protect the policy.
+
+## Example
+
+```javascript
+{
+  "attribute": "https://example.com/attr/classification/value/topsecret",
+  "isDefault": true,
+  "displayName": "classification",
+  "pubKey": "pem encoded public key of the attribute",
+  "kasUrl": "https://kas.example.com/",
+  "tdfVersion:": "x.y.z"
+}
+```
+
+|Parameter|Type|Description|Required?|
+|---|---|---|---|
+|`attribute`|String|Also known as the "attribute url."  The unique resource name for the attribute represented as a case-insensitive URL string. This field must be both unique and immutable as it is the reference id for the attribute. The attribute URL string contains three pieces of information - in the above example, the authority namespace (https://example.com), the attribute name (classification), and the attribute value (topsecret). |Yes|
+|`isDefault`|Boolean|If "true" this flag identifies the attribute as the default attribute. If missing (preferred) or false then the attribute is not the default attribute.|No|
+|`displayName`|String|A human-readable nickname for the attribute for convenience.|Yes|
+|`pubKey`|PEM|PEM encoded public key for this attribute. Often other attributes will use the same pubKey.|Yes|
+|`kasUrl`|URL|Base URL of a KAS that can make access control decisions for this attribute.|Yes|
+|`tdf_spec_version`|String|Semver version number of the TDF spec.|No|
+

CODEOWNERS

@@ -0,0 +1 @@
+*  @opentdf/developers

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contribution guidelines
+
+Contributions to the TDF3 specification are welcome! Please be sure to follow these guidelines when proposing changes or submitting feedback.
+
+## Proposing Changes
+
+All changes must be proposed using a pull request against this repo. See the GitHub [howto](https://help.github.com/en/articles/about-pull-requests) for more information about publishing a PR from a fork. The PR template checklist must be satisfied before review can take place (with the exception of blocking items like wait time).
+
+Changes must update version numbers as required (see [guidelines](#version-changes)).	
+
+* _Major_ version changes must include a detailed writeup motivating the change and its impact. These PRs must be left open for review for at least 7 days.
+* _Minor_ version changes must include a brief writeup motivating the change and its impact. These PRs must be left open for review for at least 3 days.
+
+### Version Changes
+
+We follow the [semver](https://semver.org/spec/v2.0.0.html) guidelines on version changes, although reviewers may exercise their discretion on individual PRs.
+
+* _Major_ version revs when a backwards-incompatible change is made. (Example: new required manifest fields or new required API call.)
+* _Minor_ version revs when backwards-compatible functionality is added. (Example: new optional API parameter.)
+* _Patch_ version revs when a change does not affect functionality but could affect how readers interpret the spec. (Example: Substantive new diagram illustrating a previously poorly-documented protocol interaction.)
+* Cosmetic changes should _not_ affect the version number. (Example: Fixing typos, reformatting docs.)
+
+The spec version is this repo's most recent semver Git tag - this means that if the spec version is 4.1.0, then the protocol version and all associated schema versions are also 4.1.0
+
+Any changes that affect _project_ version must update both `git tag` and the [VERSION](VERSION) file.
+
+#### Tracking Versions
+Rather than use a CHANGELOG file, we ask that you use annotated `git tags` when bumping the spec Semver, and use the annotation message to describe the change.
+> Example: `git tag -s 4.1.0 -m "Spec version 4.1.0 - twiddled a doohickey"`)
+
+Please use the raw semver when tagging - no `v4.1.0`, just `4.1.0`
+
+A list of `git tag` versions and their annotations can be generated at will via `git tag -n`
+
+To create a CHANGELOG file, run the following command
+
+`git tag -n --sort=-v:refname > CHANGELOG`
+
+## Asking Questions & Submitting Feeback
+
+Please use GitHub issues to ask questions, submit suggestions, or otherwise provide feedback. Thank you!

ClaimsObject.md

@@ -0,0 +1,58 @@
+# Claims Object
+
+## What is this?
+
+The Claims Object is a JSON object used to ensure that subjects
+attempting to decrypt an encrypted file under the Trusted Data Format
+have all permissions required to do so.
+
+The term `Subject` is a generic term that refers to both Person Entities (PE)
+and Non-Person Entities (NPE). Subjects are also sometimes referred to as "actors"
+in ABAC systems.
+
+## How does it work?
+
+When a subject wishes to decrypt a file, the following steps using
+the Claims Object are made:
+
+1. The TDF client requests an OIDC Bearer Token by first authenticating via the
+OpenID Connect (OIDC) Identity Provider (IdP) with Custom Claims
+support (in this case Keycloak), and if subject authentication succeeds, a
+[TDF Claims Object](../schema/ClaimsObject.md) is obtained from
+Attribute Provider and signed by the IdP.  The signed OIDC Bearer Token is
+returned to the client with the Claims Object inside. The Claims
+Object contains [AttributeObjects](AttributeObject.md) the subject has
+been entitled with.
+
+2. The client requests a decrypt from the Key Access Server (KAS), 
+presenting the OIDC Bearer Token (containing the Claims Object) to the KAS. 
+The KAS ensures that the requestor has the correct permissions to access
+the contents of the file by:
+
+- Examining the validity of the OIDC Bearer Token signature.
+- Validating that the Claims Object contains the client's public signing key.
+- Validating that the request signature in the client payload can be validated
+with the client's public signing key embedded in the OIDC Bearer Token
+- Determining if the TDF Client has all the required Attributes and is on
+  the [Policy Object](PolicyObject.md).
+
+If these requirements are met, the KAS will permit a decrypt of the file.
+
+## Example
+
+```javascript
+{
+  "subject_attributes": [
+    {"attribute": "https://example.com/attr/Classification/value/S", "displayName": "classification"},
+    {"attribute": "https://example.com/attr/COI/value/PRX", "displayName": "category of intent"}
+  ],
+  "client_public_signing_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy18Efi6+3vSELpbK58gC\nA9vJxZtoRHR604yi707h6nzTsTSNUg5mNzt/nWswWzloIWCgA7EPNpJy9lYn4h1Z\n6LhxEgf0wFcaux0/C19dC6WRPd6 ... XzNO4J38CoFz/\nwwIDAQAB\n-----END PUBLIC KEY-----",
+  "tdf_spec_version:": "x.y.z"
+}
+```
+
+|Parameter|Type|Description|Required?|
+|---|---|---|---|
+|`subject_attributes`|Array|An array of [Attribute Objects](AttributeObject.md) that entitle the subject.
+|`client_public_signing_key`|String|The TDF Client's public signing key, in a PEM-encoded format. |Yes|
+|`tdf_spec_version`|String|Semver version number of the TDF spec.|No|