EncryptParamsBuilder

A builder capable of constructing the necessary parameters object for an encrypt operation. Must be built before use via the build() function.

The builder may be reused for multiple encrypt operations, for instance, if running in a tight loop.

Note: The built params object (i.e., from build()) should only be used for a single encrypt operation.

Example usage:

 // Construct an authorization policy to expire the encrypted data in five minutes.
 // Note that this only revokes access from shared users - the original creator (owner) still has access.
 const policy = new Virtru.PolicyBuilder()
   .enableExpirationDeadlineFromNow(300)
   .build();

 // Configure the encrypt parameters to encrypt the provided string.
 const encryptParams = new Virtru.EncryptParamsBuilder()
   .withStringSource("I expire in five minutes x.x")
   .withUsersWithAccess(["alice@example.com", "bob@example.com"])
   .withDisplayFilename("message.txt")
   .withPolicy(policy)
   .build();
 
 // Run the encrypt and write the result to a local file.
 const ct = await client.encrypt(encryptParams);
 await ct.toFile("encrypted.html");

Constructor

new EncryptParamsBuilder()

See:

Methods

build()

Generate a parameters object in the form expected by build().

Creates a deep copy to prevent tricky call-by-reference and async execution bugs.

getDisplayFilename() → {string}

Get the filename configured to display in Secure Reader. Secure Reader will use the extension of this filename to render the decrypted data (e.g., .txt will render as plain text in browser).

This value is cosmetic only and does *not* need to match any local filename.

Returns:

Type: string

getMetadata() → {object}

Get the metadata (arbitrary key-value pairs) to be associated with the encrypted blob.

This metadata is encrypted alongside the content and stored in the TDF ciphertext.

Returns:

- object containing metadata as key-value pairs.

Type: object

getPolicy() → {Policy}

See:

Policy

Get the authorization policy which will be applied to the encrypted data.

Returns:

Type: Policy

getStreamWindowSize() → {number}

Get the size of the sliding window to use when writing out the encrypted ciphertext. Used to bound the memory used by the client for large files.

This window will match the "segment size" defined in the TDF spec, so a larger window will result in more compact ciphertext.

Returns:

The sliding window size, in bytes (1MB by default).

Type: number

getUsersWithAccess() → {array}

Get the users configured to access (decrypt) the encrypted data.

Returns:

- array of users (e.g., email addresses).

Type: array

hasHtmlFormat() → {boolean}

Whether the encrypted data should be formatted using html. This allows authorized users to double click and read using the Virtru Secure Reader, at the cost of reduced space efficiency.

This is enabled by default.

Returns:

true if the encrypted data will be in html format.

Type: boolean

hasZipFormat() → {boolean}

Whether the encrypted data should be formatted using zip. This is more space efficient than html, but authorized users must leverage the Virtru SDK to decrypt.

This is disabled by default (html is enabled by default).

Returns:

true if the encrypted data will be in zip format.

Type: boolean

setArrayBufferSource(arraybuffer) → {EncryptParamsBuilder}

Specify the content to encrypt using an ArrayBuffer reference, which must have already loaded the file content. Using the below linked example, e.target.result is the ArrayBuffer.

Example: https://developer.mozilla.org/en-US/docs/Web/API/FileReader/onload

Parameters:

Name	Type	Description
`arraybuffer`	ArrayBuffer	the array buffer containing the file to encrypt.

Returns:

- this object

Type: EncryptParamsBuilder

setBufferSource(buf)

Specify the content to encrypt, in buffer form.

Parameters:

Name	Type	Description
`buf`	Buffer	a buffer to encrypt.

setDisplayFilename(displayFilename)

Set the filename configured to display in Secure Reader. Secure Reader will use the extension of this filename to render the decrypted data (e.g., .txt will render as plain text in browser).

This value is cosmetic only and does *not* need to match any local filename.

Parameters:

Name	Type	Description
`displayFilename`	string	the filename to use.

setFileSource(filepath)

Specify the content to encrypt using a file reference. Only works with node.

Parameters:

Name	Type	Description
`filepath`	string	the location on disk of the file to encrypt.

setHtmlFormat()

Specify that the encrypted data should be formatted using html. This allows authorized users to double click and read using the Virtru Secure Reader, at the cost of reduced space efficiency.

This is enabled by default.

setMetadata(metadata)

Specify the metadata (arbitrary key-value pairs) to be associated with the encrypted blob.

This metadata is encrypted alongside the content and stored in the TDF ciphertext.

Parameters:

Name	Type	Description
`metadata`	object	object containing metadata as key-value pairs.

setPolicy(policy)

See:

Policy

Get the authorization policy which will be applied to the encrypted data.

Optional - if no policy is set then a default one will be generated with new PolicyBuilder.build().

Parameters:

Name	Type	Description
`policy`	Policy	the authorization policy.

setStreamSource(readStream)

Specify the content to encrypt, in stream form.

Parameters:

Name	Type	Description
`readStream`	Readable	a Readable Stream to encrypt.

setStreamWindowSize(The)

Set the size of the sliding window to use when writing out the encrypted ciphertext. Used to bound the memory used by the client for large files.

This window will match the "segment size" defined in the TDF spec, so a larger window will result in more compact ciphertext.

Parameters:

Name	Type	Description
`The`	number	sliding window size, in bytes (1MB by default).

setStringSource(string)

Specify the content to encrypt, in string form.

Parameters:

Name	Type	Description
`string`	string	a string to encrypt.

setUsersWithAccess(users)

Specify the full list of users configured to access (decrypt) the encrypted data.

Parameters:

Name	Type	Description
`users`	array	varargs or array of users (e.g., email addresses).

setZipFormat()

withArrayBufferSource(arraybuffer) → {EncryptParamsBuilder}

Specify the content to encrypt using an ArrayBuffer reference. Returns this object for method chaining.

Parameters:

Name	Type	Description
`arraybuffer`	ArrayBuffer	the ArrayBuffer used to load file content from a browser

Returns:

- this object.

Type: EncryptParamsBuilder

withBufferSource(buf) → {EncryptParamsBuilder}

Specify the content to encrypt, in buffer form. Returns this object for method chaining.

Parameters:

Name	Type	Description
`buf`	Buffer	a buffer to encrypt

Returns:

- this object.

Type: EncryptParamsBuilder

withDisplayFilename(displayFilename) → {EncryptParamsBuilder}

Get the filename configured to display in Secure Reader. Secure Reader will use the extension of this filename to render the decrypted data (e.g., .txt will render as plain text in browser). Returns this object for method chaining.

This value is cosmetic only and does *not* need to match any local filename.

Parameters:

Name	Type	Description
`displayFilename`	string	the filename to use.

Returns:

- this object.

Type: EncryptParamsBuilder

withFileSource(filepath) → {EncryptParamsBuilder}

Specify the content to encrypt using a file reference. Only works with node. Returns this object for method chaining.

Parameters:

Name	Type	Description
`filepath`	string	the location on disk of the file to encrypt.

Returns:

- this object.

Type: EncryptParamsBuilder

withHtmlFormat() → {EncryptParamsBuilder}

Returns:

- this object.

Type: EncryptParamsBuilder

withMetadata(metadata) → {EncryptParamsBuilder}

Specify the metadata (arbitrary key-value pairs) to be associated with the encrypted blob. Returns this object for method chaining.

This metadata is encrypted alongside the content and stored in the TDF ciphertext.

Parameters:

Name	Type	Description
`metadata`	object	object containing metadata as key-value pairs.

Returns:

- this object.

Type: EncryptParamsBuilder

withPolicy(policy) → {EncryptParamsBuilder}

See:

Policy

Get the authorization policy which will be applied to the encrypted data. Returns this object for method chaining.

Optional - if no policy is set then a default one will be generated with new PolicyBuilder.build().

Parameters:

Name	Type	Description
`policy`	Policy	the authorization policy.

Returns:

- this object.

Type: EncryptParamsBuilder

withStreamSource(readStream) → {EncryptParamsBuilder}

Specify the content to encrypt, in stream form. Returns this object for method chaining.

Parameters:

Name	Type	Description
`readStream`	Readable	a Readable Stream to encrypt.

Returns:

- this object.

Type: EncryptParamsBuilder

withStreamWindowSize(The) → {EncryptParamsBuilder}

Set the size of the sliding window to use when writing out the encrypted ciphertext. Used to bound the memory used by the client for large files. Returns this object for method chaining.

This window will match the "segment size" defined in the TDF spec, so a larger window will result in more compact ciphertext.

Parameters:

Name	Type	Description
`The`	number	sliding window size, in bytes (1MB by default).

Returns:

- this object.

Type: EncryptParamsBuilder

withStringSource(string) → {EncryptParamsBuilder}

Specify the content to encrypt, in string form. Returns this object for method chaining.

Parameters:

Name	Type	Description
`string`	string	a string to encrypt.

Returns:

- this object.

Type: EncryptParamsBuilder

withUsersWithAccess(users) → {EncryptParamsBuilder}

Specify the full list of users configured to access (decrypt) the encrypted data. Returns this object for method chaining.

Parameters:

Name	Type	Description
`users`	array	varargs or array of users (e.g., email addresses).

Returns:

- this object.

Type: EncryptParamsBuilder

withZipFormat() → {EncryptParamsBuilder}

Whether the encrypted data should be formatted using zip. This is more space efficient than html, but authorized users must leverage the Virtru SDK to decrypt. Returns this object for method chaining.

This is disabled by default (html is enabled by default).

Returns:

- this object.

Type: EncryptParamsBuilder