EncryptParamsBuilder

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

getMimeType()

Gets the (consumer provided) mime type of the file to be protected

getPolicy() → {Policy}

See:
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

setAttributes(attributes)

Parameters:
Name Type Description
attributes Object
Properties
Name Type Description
attribute String URI of the form `/attr//value/`

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.

setMimeType(mimeType) → {EncryptParamsBuilder}

Sets the mime type of the underlying file.
Parameters:
Name Type Description
mimeType string the content type string to be applied during decrypt
Returns:
- this object.
Type
EncryptParamsBuilder

setPolicy(policy)

See:
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.

setRcaSource(isRcaSource)

Parameters:
Name Type Description
isRcaSource boolean

(async) setRemoteStore(fileName, configopt, credentialURLopt) → {EncryptParamsBuilder}

Specify the remote content to encrypt in stream form. withRemoteStore() has not been implemented because setRemoteStore() is async so withRemoteStore() can't be chained with a build() call.
Parameters:
Name Type Attributes Description
fileName string the name of the remote file to write TDF ciphertext to.
config S3ClientConfig <optional>
the object containing remote storage configuration.
A detailed spec for the interface can be found here
credentialURL string <optional>
the url to request remote storage credentials from.
Credentials can be generated using GetFederationToken
Returns:
- this object.
Type
EncryptParamsBuilder

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)

Validate user accounts are emails before passing to EncryptParamsBuilder
Parameters:
Name Type Description
users Array | string

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()

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

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

withAttributes(attributes) → {EncryptParamsBuilder}

Parameters:
Name Type Description
attributes Object
Properties
Name Type Description
attribute String URI of the form `/attr//value/`
Returns:
with attributes set
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}

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. Returns this object for method chaining.

This is enabled by default.
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

withMimeType(mimeType) → {EncryptParamsBuilder}

Sets the mime type of the underlying file.
Parameters:
Name Type Description
mimeType string the content type string to be applied during decrypt
Returns:
- this object.
Type
EncryptParamsBuilder

withPolicy(policy) → {EncryptParamsBuilder}

See:
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 node 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

withWebStreamSource(readStream) → {EncryptParamsBuilder}

Specify the content to encrypt, in web stream form. Returns this object for method chaining.
Parameters:
Name Type Description
readStream Readable a Readable Stream to encrypt.
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

EncryptParamsBuilder

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

Constructor

new EncryptParamsBuilder()

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

getMimeType()

Gets the (consumer provided) mime type of the file to be protected

getPolicy() → {Policy}

See:
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

setAttributes(attributes)

Parameters:
Name Type Description
attributes Object
Properties
Name Type Description
attribute String URI of the form `/attr//value/`

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.

setMimeType(mimeType) → {EncryptParamsBuilder}

Sets the mime type of the underlying file.
Parameters:
Name Type Description
mimeType string the content type string to be applied during decrypt
Returns:
- this object.
Type
EncryptParamsBuilder

setPolicy(policy)

See:
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.

setRcaSource(isRcaSource)

Parameters:
Name Type Description
isRcaSource boolean

(async) setRemoteStore(fileName, configopt, credentialURLopt) → {EncryptParamsBuilder}

Specify the remote content to encrypt in stream form. withRemoteStore() has not been implemented because setRemoteStore() is async so withRemoteStore() can't be chained with a build() call.
Parameters:
Name Type Attributes Description
fileName string the name of the remote file to write TDF ciphertext to.
config S3ClientConfig <optional>
the object containing remote storage configuration.
A detailed spec for the interface can be found here
credentialURL string <optional>
the url to request remote storage credentials from.
Credentials can be generated using GetFederationToken
Returns:
- this object.
Type
EncryptParamsBuilder

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)

Validate user accounts are emails before passing to EncryptParamsBuilder
Parameters:
Name Type Description
users Array | string

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()

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

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

withAttributes(attributes) → {EncryptParamsBuilder}

Parameters:
Name Type Description
attributes Object
Properties
Name Type Description
attribute String URI of the form `/attr//value/`
Returns:
with attributes set
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}

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. Returns this object for method chaining.

This is enabled by default.
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

withMimeType(mimeType) → {EncryptParamsBuilder}

Sets the mime type of the underlying file.
Parameters:
Name Type Description
mimeType string the content type string to be applied during decrypt
Returns:
- this object.
Type
EncryptParamsBuilder

withPolicy(policy) → {EncryptParamsBuilder}

See:
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 node 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

withWebStreamSource(readStream) → {EncryptParamsBuilder}

Specify the content to encrypt, in web stream form. Returns this object for method chaining.
Parameters:
Name Type Description
readStream Readable a Readable Stream to encrypt.
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