tdf3-js v4.0.0

tdf3-js

A JavaScript client library that can be used to encrypt and decypt files using the TDF3 specification.

Install & Build

First install all packages required:

npm ci

Build:

npm run build. The built file can be found in /build

Note: If running tests, the build is run automatically.

Running Tests

1. Download, and run a KAS (Key Access Server): npm run setup
2. Start the KAS: npm start
3. Build tdf3-js: npm run build
4. Then: npm test

Note: Step 1 grabs master branch of the kas. If you'd like to get a different branch do the following:

BRANCH=<branch name> npm run setup.

To terminate the running kas: npm stop

Example

For a good starting point on how to implement tdf3-js on your own, please see the walkthrough.

Methods

create()

Creates a new instance of TDF.

const tdfInstance = TDF.create();

setProtocol(protocol)

Set the protocol to be used in either encryption or decryption steps.

tdfInstance.setProtocol('zipstream');

protocol

Type: String

Currently only 'zip' and 'zipstream' are implemented. 'zipstream' should be used when reading from/writing to a stream.

setPrivateKey(privateKey)

Sets the private key onto the TDF instance to be used in either the encryption or decryption steps.

tdfInstance.setPrivateKey(privateKey);

privateKey

Type: String

The PEM-encoded private key as a string.

setPublicKey(publicKey)

Sets the public key onto the TDF instance to be used in either the encryption or decryption steps.

tdfInstance.setPublicKey(publicKey);

publicKey

Type: String

The PEM-encoded public key as a string.

setEncryption(encryptionObject)

Set the encryption object onto the TDF instance.

tdfInstance.setEncryption(encryptionObject);

encryptionObject.type

Type: String

The type of encryption, currently the only option is split to represent key splitting

encryptionObject.cipher

Type: String

The type of cipher to use for encryption. Available options are 'aes-256-gcm' and 'aes-256-cbc'.

addKeyAccess(keyAccessObject)

Adds a Key Access Object to a TDF instance.

tdfInstance.addKeyAccess(keyAccessObject);

setPolicy(policyObject)

Sets the Policy Object on a TDF instance.

tdfInstance.setPolicy(policyObject);

setEntity(entityObject)

Set the Entity Object on a TDF instance.

tdfInstance.setEntity(entityObject);

setDefaultSegmentSize(segmentSize)

Sets the default size of each segment, in bytes, onto a TDF instance.

tdfInstance.setDefaultSegmentSize(segmentSize);

segmentSize

Type: Integer

Default is set to 1024 * 1024 if one is not provided.

setIntegrityAlgorithm(integrityAlgorithm, segmentIntegrityAlgorithm optional)

Sets the integrity algorithm and segment integrity algorithms onto a TDF instance.

tdfInstance.setIntegrityAlgorithm(integrityAlgorithm, segmentIntegrityAlgorithm);

integrityAlgorithm

Type: String

The type of algorithm used to create the root signature, found in the manifest integrityInformation. Available options are hs256.

segmentIntegrityAlgorithm

Type: String

The type of algorithm used to creat segment signatures. This parameter is optional, and if one is not provided the integrityAlgorithm will be used. Available options are gmac.

addContentStream(contentStream)

Sets a content stream on a TDF instance. Used during encryption when the library needs to read from a content stream to encrypt stream chunks, eventually to be written as an encrypted file.

tdfInstance.addContentStream(contentStream);

contentStream

The current implementation of the tdf3-js uses Node streams. For example, you can create a readStream that allows tdf3-js to read from a file source:

const contentStream = fs.createReadStream(_my_file_loc, { encoding: 'binary' });

If you are working on a browser-only solution, tdf3-js offers a mock stream that provides a custom in-memory stream that mimicks Node streams.

createMockStream(fileData, isEncryptOperation)

Creates a mocked stream which mimicks a Node stream (tdf3-js's stream implementation) to be used when options are limited via a browser. It provides the library with all necessary callbacks and emitters it expects, but loads the entire file data into memory before processing each chunk of data separately.

fileData

Type: Byte

The file's data, read from a file upload, for example:

const reader = new FileReader();
reader.onload = (e) => {
  const filedata = reader.result;
  //do something with the filedata
};

This value can also be set to null, as would be the case for a writeStream (no data present upon creation).

isEncryptOperation

Type: Boolean

A boolean that describes whether this stream is used for an encryption or decryption operation. This is used by the mock stream in lieu of having separate streams (e.g., createReadStream, createWriteStream)

write()

Writes the encrypted content to memory, which can then be saved using any non-streaming method

const result = await tdfInstance.write();

fs.writeFileSync(_my_filename_, result.binary.asBuffer(), { encoding: 'binary', flag: 'w' });

writeStream(writeStream)

Writes the encrypted content to a write stream provided.

await tdfInstance.writeStream(writeStream);

writeStream

Type: Node stream or MockStream

The stream can be used to write to a file location, or in-memory.

readStream(url, outputStream)

Reads the content at a remote source (a url), and writes to an outputStream, for example a file.

url

Type: String

The URL of the remote resource from which tdf3-js will read data.

outputStream

Type: Node stream or MockStream

The stream can be used to write to a file location, or in-memory.

generatePolicyUuid()

Creates a unique identifier for a policy object. Returns a String.

const uuid = await TDF.generatePolicyUuid();

generateKeyPair()

Uses tdf3-js's built-in crypto services to generate a public and private key pair. Returns an object with privateKey and publicKey properties.

const keyPair = await TDF.generateKeyPair();
const privateKey = keyPair.privateKey;
const publicKey = keyPair.publicKey;

getPublicKeyFromKeyAccessServer(kasURL)

Fetches the public key (or PEM-encoded certificate) from a remote Key Access Server (KAS) server.

const kasPublicKey = await TDF.getPublicKeyFromKeyAccessServer(kasURL);

kasURL

Type: String

The URL of the KAS public key endpoint, for example: http://localhost:4000/kas_public_key

loadTDFStream(url)

Loads a TDF stream by its remote url, placing the manifest JSON and encrypted payload in memory

await tdfInstance.loadTDFStream(url);

loadTDF(tdfPath)

Loads a TDF file by its filename string

await tdfInstance.loadTDF(tdfPath);

sync

Performs a 'syncing' of the symmetric wrapped key and Policy Object. For remote Key Access types, this is performed automatically on encryption.

await tdfInstance.sync();