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
Encryption Information
- Method
- Integrity Information
  - Segment

If you'd like to see a real manifest created using the TDF client, check it out here.

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.

"payload": {
    "type": "reference",
    "url": "0.payload",
    "protocol": "zip",
    "isEncrypted": true,
    "mimeType": "application/pdf",
    "tdf_spec_version:": "x.y.z"
}

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. Default is `application/octet-stream`.	No
`tdf_spec_version`	String	Semver version number of the TDF spec.	No

encryptionInformation

Contains information describing the method of encryption. As well as information about one or more Key Access Servers which own the TDF.

"encryptionInformation": {
    "type": "split",
    "keyAccess": [<Key Access Object>],
    "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
`method`	Object	The encryption method object is defined below: method
`integrityInformation`	Object	`integrityInformation` is defined below in its own section: integrityInformation
`policy`	String	The policy object which has been JSON stringified, then base64 encoded. The policy object is described in its own section: Policy Object

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.

"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.

"integrityInformation": {
  "rootSignature": {
    "alg": "HS256",
    "sig": "M2E2MTI5YmMxMWU0ODIzZDA4YTdkNTY2MzdlNDM4OGRlZDE2MTFhZjU1YTY1YzBhYWNlMWVjYjlmODUzNmNiZQ=="
  },
  "segmentHashAlg": "GMAC",
  "segments": [<Segment Object>],
  "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
`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.

{
  "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.

Authentic Manifest

Here is the JSON from an actual .tdf file, created by the TDF client.

{
  "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": "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="
  }
}

Summary​

Payload​

encryptionInformation​

encryptionInformation.method​

encryptionInformation.integrityInformation​

encryptionInformation.integrityInformation.segment​

Authentic Manifest​