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

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
clientConfig 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) decrypt(params) → {PlaintextStream}

See:
Decrypt TDF ciphertext into plaintext. One of the core operations of the Virtru SDK.
Parameters:
Name Type Description
params object Required. All parameters for the decrypt operation, generated using DecryptParamsBuilder's build().
Returns:
- a Readable stream containing the decrypted plaintext.
Type
PlaintextStream

(async) encrypt(params) → {TDFCiphertextStream}

See:
Encrypt plaintext into TDF ciphertext. One of the core operations of the Virtru SDK.
Parameters:
Name Type Description
params object Required. All parameters for the encrypt operation, generated using EncryptParamsBuilder's build().
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

getClientVersion() → {string}

Get the current version of this SDK.
Returns:
the SDK version, in semver form (e.g., "1.2.1").
Type
string

(async) getPolicyId(params) → {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
params object Required. Parameters specifying the ciphertext for which to get the policyId, 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.