Client

Client

The Client is the entry point for the major Virtru operations, such as encrypt, decrypt, and Policy management.

Example usage:
 // Construct the client, configuring auth via Google-based OAuth.
 const client = new Virtru.Client({email: "dathon@tamarian.gov", appId: "2173dc5a-1d9e-7fca-9b39-5f4d4f056f4a"});

 // Configure and execute an encrypt, granting another user access to decrypt the ciphertext.
 const encryptParams = new Virtru.EncryptParamsBuilder()
      .withStringSource("Sokath, his eyes open!")
      .withUsersWithAccess(['picard@enterprise.fed'])
      .build();
 const ct = await client.encrypt(encryptParams);

 // Write the ciphertext to the a file.
 await ct.toFile('encrypted.html');
  

Constructor

new Client(configuration)

Construct a new Client using the provided client configuration.

Clients running in a non-browser context pass their Virtru credentials directly into the constructor. There are two types of Virtru credentials, the short-lived appId and the long-lived hmac credential pair. See here for more information on generating and using these credentials.
// Initializing with an appId
const client = new Virtru.Client({email, appId});
// ...

// Initializing with hmac credentials.
const client = new Virtru.Client({email, hmacToken, hmacSecret});
// ...
     
Clients running in a browser context must first authenticate as shown here. The client can then be cosntructed by simply passing in the authenticated email address.
async function afterAuth(email) {
  const client = new Virtru.Client({email});
  // ...
}
     
Parameters:
Name Type Description
configuration object configuration to use for the lifetime of this client instance.
Properties
Name Type Description
email string the email address to authenticate as, using Virtru credentials or preprovisioned via the OAuth flow. Any data you encrypt will be owned by this email address. It will also be used to authorize decrypt access to encrypted data. Required.
appId string the "AppId" credential generated from the Virtru dashboard's. developer settings. Not allowed in browser. Optional.
hmacToken string the long-lived "HMAC" token (appId alternative) generated by contacting Virtru. Must be used along with clientConfig.hmacSecret, and not appId. Not allowed in browser. Optional.
hmacSecret string the long-lived "HMAC" secret (appId alternative) generated by contacting Virtru. Must be used along with clientConfig.hmacToken, and not appId. Not allowed in browser. Optional.

Methods

(async) auth(eoopt, keypairopt)

Parameters:
Name Type Attributes Description
eo object <optional>
Cached EO, if available.
keypair object <optional>
Additional additional keydata associated with EO
Returns:
authentication token and key for private communication with it

(async) decrypt(source, eoopt, keypairopt, outputopt, rcaSourceopt) → {PlaintextStream}

See:
Decrypt TDF ciphertext into plaintext. One of the core operations of the Virtru SDK.
Parameters:
Name Type Attributes Description
object Required. All parameters for the decrypt operation, generated using DecryptParamsBuilder's build().
source object A data stream object, one of remote, stream, buffer, etc. types.
eo object <optional>
Cached EO, if available.
keypair object <optional>
Additional additional keydata.
output object <optional>
A node Writeable; if not found will create and return one.
rcaSource object <optional>
RCA source information
Returns:
- a Readable stream containing the decrypted plaintext.
Type
PlaintextStream

(async) encrypt(scope, source, asHtmlopt, eoopt, keypairopt, metadataopt, mimeTypeopt, offlineopt, outputopt, rcaSourceopt, validateEntityopt, windowSizeopt) → {TDFCiphertextStream}

See:
Encrypt plaintext into TDF ciphertext. One of the core operations of the Virtru SDK.
Parameters:
Name Type Attributes Description
scope object dissem and attributes for constructing the policy
source object nodeJS source object of unencrypted data
asHtml boolean <optional>
If we should wrap the TDF data in a self-opening HTML wrapper
eo object <optional>
Cached EO, if available.
keypair object <optional>
explicit keypair to use to communicate with KAS. Can also be specified in constructor. If not found, generated.
metadata object <optional>
additional non-secret data to store with the TDF
mimeType string <optional>
mime type of source
offline boolean <optional>
Where to store the policy
output object <optional>
output stream. Created and returned if not passed in
rcaSource object <optional>
RCA source information
validateEntity function <optional>
Called on the EO after fetch; return `false` to fail the encrypt, e.g. if the entity has insufficient authN
windowSize number <optional>
segment size in bytes
Returns:
- a Readable stream containing the TDF ciphertext.
Type
TDFCiphertextStream

(async) fetchPolicy(policyId) → {Policy}

Fetch an authorization Policy from the Virtru backend.

The Policy is created automatically through an encrypt, so this can only be run after an encrypt has succeeded. Only the policy owner (creator) may call fetchPolicy.

The policyId for this call is assigned automatically during encrypt setup and must be retrieved in one of two ways.

The first approach is to grab the policyId from the built encrypt params:
// Execute an encrypt normally.
const encryptParams = new Virtru.EncryptParamsBuilder()
     .withStringSource("Sokath, his eyes open!")
     .build();
const ct = await client.encrypt(encryptParams);

const policyId = encryptParams.getPolicyId();
const policy = await client.fetchPolicy(policyId);
// Now you can update and revoke using this fetched policy.
     
The second approach is to parse the policyId from the encrypted TDF ciphertext.
// Execute an encrypt normally.
const encryptParams = new Virtru.EncryptParamsBuilder()
     .withStringSource("Sokath, his eyes open!")
     .build();
const ct = await client.encrypt(encryptParams);
// Write the ciphertext to a file as per typical usage.
await ct.toFile('darmok.html');

 // Time passes...
 // Some time later we decide to update the policy (e.g., to give a new user access).

 const decryptParams = new Virtru.DecryptParamsBuilder()
    .withFileSource('darmok.html')
    .build();
 const policyId = await client.getPolicyId(decryptParams);
 const policy = await client.fetchPolicy(policyId);
 // Now you can update and revoke using this fetched policy.
     
Parameters:
Name Type Description
policyId string the unique identifier of the policy.
Returns:
A Policy object.
Type
Policy
WARNING: if the stream has not ended, this method will fail
Parameters:
Name Type Description
stream PlaintextStream
Returns:
for decrypting in secure reader
Type
string

getClientVersion() → {string}

Get the current version of this SDK.
Returns:
the SDK version, in semver form (e.g., "1.2.1").
Type
string
Parameters:
Name Type Description
rcaLink string RCA link for decryption

(async) getPolicyId(source) → {string}

See:
Get the unique policyId associated with TDF ciphertext. Useful for managing authorization policies of encrypted data.

The policyId is embedded in the ciphertext so this is a local operation.
Parameters:
Name Type Description
source object Required. TDF data stream, generated using DecryptParamsBuilder's build().
Returns:
- the unique policyId, which can be used for tracking purposes or policy management operations.
Type
string

(async) revokePolicy(policyId)

"Revoke" an authorization Policy in the Virtru backend. This will disable access to the Policy (and thus prevent decrypt) for all authorized users except the owner. Only the policy owner (creator) may call revokePolicy.

This operation is not irrevocable - revoked policies may be re-enabled in the dashboard by the policy owner.

Idempotent, succeeds if the policy does not already exist.
Parameters:
Name Type Description
policyId string the unique identifier of the policy.
Returns:
nothing.

(async) updatePolicy(policy)

Push an authorization Policy update to the Virtru backend.

The Policy must first be fetched through fetchPolicy. Only the policy owner (creator) may call updatePolicy.
// Some time after encryption we decide to give a new user access to the data.
const decryptParams = new Virtru.DecryptParamsBuilder()
   .withFileSource('darmok.html')
   .build();
const policyId = await client.getPolicyId(decryptParams);
const policy = await client.fetchPolicy(policyId);
const newPolicy = policy.builder()
  .addUsersWithAccess('picard@enterprise.fed')
  .build();
await client.updatePolicy(newPolicy);
// Now the new user can decrypt the file!
     
Parameters:
Name Type Description
policy Policy the updated policy to push.
Returns:
nothing.

Client

An abstraction for protecting and accessing data using TDF3 services.

Constructor

new Client(config)

Configure a TDF3 client to connect to the requested EAS.
Parameters:
Name Type Description
config Object configuration parameters
Properties
Name Type Attributes Description
authProvider AuthProvider | function <optional>
auth request interceptor
easEndpoint string <optional>
root path for Entity Attribute Service (deprecated)
entityObjectEndpoint string <optional>
Entity Object path on an Entity Attribute Service
kasEndpoint string <optional>
root path for Key Access Service
keyRewrapEndpoint string <optional>
full path on the KAS to the rewrap endpoint
keyUpsertEndpoint string <optional>
full path on the KAS to the key+policy upsert endpoint
keypair object <optional>
explicit keypair to use to communicate with KAS
readerUrl object <optional>
associated TDF reader service
userId object <optional>
a user id to send to EAS, useful in debug mode
validateEntity function <optional>
validate entity by backend

Methods

(async) auth(eoopt, keypairopt)

Parameters:
Name Type Attributes Description
eo object <optional>
Cached EO, if available.
keypair object <optional>
Additional additional keydata associated with EO
Returns:
authentication token and key for private communication with it

(async) decrypt(source, eoopt, keypairopt, outputopt, rcaSourceopt) → {PlaintextStream}

See:
Decrypt TDF ciphertext into plaintext. One of the core operations of the Virtru SDK.
Parameters:
Name Type Attributes Description
object Required. All parameters for the decrypt operation, generated using DecryptParamsBuilder's build().
source object A data stream object, one of remote, stream, buffer, etc. types.
eo object <optional>
Cached EO, if available.
keypair object <optional>
Additional additional keydata.
output object <optional>
A node Writeable; if not found will create and return one.
rcaSource object <optional>
RCA source information
Returns:
- a Readable stream containing the decrypted plaintext.
Type
PlaintextStream

(async) encrypt(scope, source, asHtmlopt, eoopt, keypairopt, metadataopt, mimeTypeopt, offlineopt, outputopt, rcaSourceopt, validateEntityopt, windowSizeopt) → {TDFCiphertextStream}

See:
Encrypt plaintext into TDF ciphertext. One of the core operations of the Virtru SDK.
Parameters:
Name Type Attributes Description
scope object dissem and attributes for constructing the policy
source object nodeJS source object of unencrypted data
asHtml boolean <optional>
If we should wrap the TDF data in a self-opening HTML wrapper
eo object <optional>
Cached EO, if available.
keypair object <optional>
explicit keypair to use to communicate with KAS. Can also be specified in constructor. If not found, generated.
metadata object <optional>
additional non-secret data to store with the TDF
mimeType string <optional>
mime type of source
offline boolean <optional>
Where to store the policy
output object <optional>
output stream. Created and returned if not passed in
rcaSource object <optional>
RCA source information
validateEntity function <optional>
Called on the EO after fetch; return `false` to fail the encrypt, e.g. if the entity has insufficient authN
windowSize number <optional>
segment size in bytes
Returns:
- a Readable stream containing the TDF ciphertext.
Type
TDFCiphertextStream

(async) fetchPolicy(policyId) → {Policy}

Fetch an authorization Policy from the Virtru backend.

The Policy is created automatically through an encrypt, so this can only be run after an encrypt has succeeded. Only the policy owner (creator) may call fetchPolicy.

The policyId for this call is assigned automatically during encrypt setup and must be retrieved in one of two ways.

The first approach is to grab the policyId from the built encrypt params:
// Execute an encrypt normally.
const encryptParams = new Virtru.EncryptParamsBuilder()
     .withStringSource("Sokath, his eyes open!")
     .build();
const ct = await client.encrypt(encryptParams);

const policyId = encryptParams.getPolicyId();
const policy = await client.fetchPolicy(policyId);
// Now you can update and revoke using this fetched policy.
     
The second approach is to parse the policyId from the encrypted TDF ciphertext.
// Execute an encrypt normally.
const encryptParams = new Virtru.EncryptParamsBuilder()
     .withStringSource("Sokath, his eyes open!")
     .build();
const ct = await client.encrypt(encryptParams);
// Write the ciphertext to a file as per typical usage.
await ct.toFile('darmok.html');

 // Time passes...
 // Some time later we decide to update the policy (e.g., to give a new user access).

 const decryptParams = new Virtru.DecryptParamsBuilder()
    .withFileSource('darmok.html')
    .build();
 const policyId = await client.getPolicyId(decryptParams);
 const policy = await client.fetchPolicy(policyId);
 // Now you can update and revoke using this fetched policy.
     
Parameters:
Name Type Description
policyId string the unique identifier of the policy.
Returns:
A Policy object.
Type
Policy
WARNING: if the stream has not ended, this method will fail
Parameters:
Name Type Description
stream PlaintextStream
Returns:
for decrypting in secure reader
Type
string

getClientVersion() → {string}

Get the current version of this SDK.
Returns:
the SDK version, in semver form (e.g., "1.2.1").
Type
string
Parameters:
Name Type Description
rcaLink string RCA link for decryption

(async) getPolicyId(source) → {string}

See:
Get the unique policyId associated with TDF ciphertext. Useful for managing authorization policies of encrypted data.

The policyId is embedded in the ciphertext so this is a local operation.
Parameters:
Name Type Description
source object Required. TDF data stream, generated using DecryptParamsBuilder's build().
Returns:
- the unique policyId, which can be used for tracking purposes or policy management operations.
Type
string

(async) revokePolicy(policyId)

"Revoke" an authorization Policy in the Virtru backend. This will disable access to the Policy (and thus prevent decrypt) for all authorized users except the owner. Only the policy owner (creator) may call revokePolicy.

This operation is not irrevocable - revoked policies may be re-enabled in the dashboard by the policy owner.

Idempotent, succeeds if the policy does not already exist.
Parameters:
Name Type Description
policyId string the unique identifier of the policy.
Returns:
nothing.

(async) updatePolicy(policy)

Push an authorization Policy update to the Virtru backend.

The Policy must first be fetched through fetchPolicy. Only the policy owner (creator) may call updatePolicy.
// Some time after encryption we decide to give a new user access to the data.
const decryptParams = new Virtru.DecryptParamsBuilder()
   .withFileSource('darmok.html')
   .build();
const policyId = await client.getPolicyId(decryptParams);
const policy = await client.fetchPolicy(policyId);
const newPolicy = policy.builder()
  .addUsersWithAccess('picard@enterprise.fed')
  .build();
await client.updatePolicy(newPolicy);
// Now the new user can decrypt the file!
     
Parameters:
Name Type Description
policy Policy the updated policy to push.
Returns:
nothing.