Build with the Virtru Developer Hub

It's Your Data. Protect It. Control It. Everywhere.

Try the Demo          Learn More     

How to Add Virtru Controls

Virtru Developer Platform supports many Information Rights Management (IRM) controls. These controls give you, the developer, fine grained way to control access to the files even after the files have been shared with employees, contractors or partners.

Revoke Revoke

The "Revoke" control allows the owner of the object (or the admin) to revoke access from one or more users on a Virtru protected object. All Virtru clients as well as all the SDKs support the revoke feature. Once the access is revoked on an object, that user can no longer read the file. Even if all the users' access is revoked, the object owner and admin will continue to have access to the object.

This operation is reversible. The owner (or the admin) can change their mind and re-grant access via Virtru Dashboard.

// Assume that a Virtru protected TDF file (with .html encoding) is shared by the 
// owner 'alice@example1.com' with 'bob@example2.com' and 'mallory@example2.com'.
const params = new Virtru.DecryptParamsBuilder()
  .withFileSource("/tmp/darmok.html") 
  .build();

// See the 'Getting Started' pages to see how to get 'client'
// Once you have client, get the policyId embedded in the TDF file (darmok.html)
const policyId = await client.getPolicyId(params);
const origPolicy = await client.fetchPolicy(policyId);

// Now update the policy in Virtru Key Management Infra
const updatedPolicy  = policy.builder().removeUsersWithAccess("mallory@example2.com").build();
await client.updatePolicy(updatedPolicy)

// Now, mallory@example2.com cannot decrypt the file, bob@example2.com still can.

# Assume that a Virtru protected TDF file (with .html encoding) is shared by the 
# owner 'alice@example1.com' with 'bob@example2.com' and 'mallory@example2.com'.

# See 'How to add Authentication' page to see how to get 'client'
# Once you have client, get the policyId embedded in the TDF file (darmok.html)

# Now update the policy in Virtru Key Management Infra
policy = Policy()
policy.remove_users(['mallory@example2.com'])
client.update_policy_for_file(policy, "/tmp/darmok.html")

# Now, mallory@example2.com cannot decrypt the file, bob@example2.com still can
// Assume that a Virtru protected TDF file (with .html encoding) is shared by the 
// owner 'alice@example1.com' with 'bob@example2.com' and 'mallory@example2.com'.

// See 'How to add Authentication' page to see how to get 'client'
// Once you have client, get the policyId embedded in the TDF file (darmok.html)
Policy policy;
policy.removeUsers({"mallory@example2.com"});
client.updatePolicyForFile(policy, "sample.docx.html");

// Now, mallory@example2.com cannot decrypt the file, bob@example2.com still can.

Revoke All Revoke All

The "Revoke All" control allows the owner of the object (or the admin) to revoke access from all users on a Virtru protected object. In other words, any users who were previously granted access to the object will lose access. The owner and the admin will continue to have access to the object. All Virtru clients as well as all the SDKs support the revoke feature.

This operation is reversible. The owner (or the admin) can change their mind and re-grant access via Virtru Dashboard.

// Assume that a Virtru protected TDF file (with .html encoding) is shared by the 
// owner 'alice@example1.com' with 'bob@example2.com' and 'mallory@example2.com'.
const params = new Virtru.DecryptParamsBuilder()
  .withFileSource("/tmp/darmok.html") 
  .build();

// See the 'Getting Started' pages to see how to get 'client'
// Once you have client, get the policyId embedded in the TDF file (darmok.html)
const policyId = await client.getPolicyId(params);

// Now alice@example1.com decides to revoke access. 
// The following line will revoke access to everyone ('bob@example2.com' and 'mallory@example2.com'). 
// However, the owner (alice@example1.com) will continue to have access.
await client.revokePolicy(policyId);
# Assume that a Virtru protected TDF file (with .html encoding) is shared by the 
# owner 'alice@example1.com' with 'bob@example2.com' and 'mallory@example2.com'.

# See 'How to add Authentication' to see how to get 'client'
# Once you have client, get the policyId embedded in the TDF file (darmok.html)

# Now alice@example1.com decides to revoke access. 
# The following line will revoke access to everyone ('bob@example2.com' and 'mallory@example2.com'). 
# However, the owner (alice@example1.com) will continue to have access.
client.revoke_file("/tmp/darmok.html")
// Assume that a Virtru protected TDF file (with .html encoding) is shared by the 
// owner 'alice@example1.com' with 'bob@example2.com' and 'mallory@example2.com'.

// See 'How to add Authentication' to see how to get 'client'
// Once you have client, get the policyId embedded in the TDF file (darmok.html)


// Now alice@example1.com decides to revoke access. 
// The following line will revoke access to everyone ('bob@example2.com' and 'mallory@example2.com'). 
// However, the owner (alice@example1.com) will continue to have access.
client.revokeFile("/tmp/darmok.html");

Disable Re-Share Disable Re-Share

The "Disable Re-Share" control allows the owner of the object (or the admin) to disable the users from further sharing the object with new user(s). Currently this has no bearing on data authorization, but in the near future this will disallow authorized users from further resharing data they have access to. This is similar to "Disable Forwarding" control in Virtru's email products.

This operation is reversible. The owner (or the admin) can change their mind and allow the users from sharing the object with new users.

const policy = new Virtru.PolicyBuilder()
  .disableReshare() // disable re-sharing of the file
  .build();

// Configure and execute an encrypt.
const encryptParams = new Virtru.EncryptParamsBuilder()
  .withFileSource("/tmp/taxes.pdf")
	.withUsersWithAccess(["bob@example2.com"]) 
  .withPolicy(policy)
	.build();
const stream = await client.encrypt(encryptParams);
// Write the ciphertext in HTML format to a local file with .html extension.
await stream.toFile("/tmp/taxes.pdf.html");

// Bob will not be able t re-share the file further to mallory
// Alice can enable re-share after some time by calling Policy.enableReshare()
# Disable re-sharing of the file
policy = Policy()
policy.share_with_users(["bob@example2.com"])
policy.disable_reshare()

param = EncryptFileParam(in_file_path = "/tmp/taxes.pdf",
                         out_file_path = "/tmp/taxes.pdf.html")
param.set_policy(policy)

# Encrypt the file.
client.encrypt_file(encrypt_file_param = param)

# Bob can not re-share the file further to mallory
# Alice can enable re-share after some time by calling Policy.enableReshare()
// Disable re-sharing of the file
Policy policy;
policy.shareWithUsers({"bob@example.com"});
policy.disableReshare();

// Create the encrypt params with simple policy
EncryptFileParam param {"/tmp/taxes.pdf", "/tmp/taxes.pdf.html"};
param.setPolicy(policy);

// encrypt and save file.
client.encryptFile(param);

// Bob can not re-share the file further to mallory
// Alice can enable re-share after some time by calling Policy.enableReshare()

"Disable Re-Share" control can be added post encryption like this:

// File was encrypted a while ago and 'bob@example.com' was given authoriztion to decrypt.
// Now the owner (or admin) wants to disable re-sharing by the sharees.
const params = new Virtru.DecryptParamsBuilder()
  .withFileSource("/tmp/taxes.pdf.html")
  .build();

// See 'How to add Authentication' page to see how to get 'client'
// Once you have client, get the policyId embedded in the TDF file (taxes.pdf.html)
const policyId = await client.getPolicyId(params);
const origPolicy = await client.fetchPolicy(policyId);

// Now update the policy in Virtru Key Management Infra
const updatedPolicy  = (origPolicy.builder())
  .disablereshare() // disable re-share
  .build();
await client.updatePolicy(updatedPolicy)
// Now 'bob@example.com' will not be able to share (or forward) the policy to mallory.
# File was encrypted a while ago and 'bob@example.com' was given authoriztion to decrypt.
# Now the owner (or admin) wants to disable re-sharing by the sharees.


# See 'How to add Authentication' page to see how to get 'client'
# Once you have client, get the policyId embedded in the TDF file (taxes.pdf.html)

# Now update the policy in Virtru Key Management Infra
policy = Policy()
policy.disable_reshare()
client.update_policy_for_file(policy, "/tmp/taxes.pdf.html")

# Now 'bob@example.com' will not be able to share (or forward) the policy to mallory.
// File was encrypted a while ago and 'bob@example.com' was given authoriztion to decrypt.
// Now the owner (or admin) wants to disable re-sharing by the sharees.

// See 'How to add Authentication' page to see how to get 'client'
// Once you have client, get the policyId embedded in the TDF file (taxes.pdf.html)

// Now update the policy in Virtru Key Management Infra
Policy policy;
policy.disableReshare();
client.updatePolicyForFile(policy, "/tmp/taxes.pdf.html");

// Now 'bob@example.com' will not be able to share (or forward) the policy to mallory.

Expire Expire

The "Expire" control allows the owner (or the admin) to set an expiration date/time on an object. After the expiration date/time has passed, any users who were previously granted access will be unable to read the object. The owner and the admin will continue to have access to the object. All Virtru clients as well as all the SDKs support the expire feature. The expiration date can be set either at
encryption-time or any time later (using updatePolicy).

This operation is reversible. The owner (or the admin) can change their mind and remove expiration control. The owner (or the admin) can also update the expiration date.

Expiration date can be added at the time of encryption like this:

const policy = new Virtru.PolicyBuilder()
  .enableExpirationDeadlineFromNow(60*10) // expire 10 minutes from now
  .build();

// Configure and execute an encrypt.
const encryptParams = new Virtru.EncryptParamsBuilder()
  .withFileSource("/tmp/taxes.pdf")
  .withUsersWithAccess(["bob@example2.com"]) 
  .withPolicy(policy)
  .build();
const stream = await client.encrypt(encryptParams);
// Write the ciphertext in HTML format to a local file with .html extension.
await stream.toFile("/tmp/taxes.pdf.html");

// Bob can not decrypt this file after 10 minutes

# expire in 10 mins
policy = Policy()
policy.expire_in_mins(mins = 10) 

# create the encrypt params with simple policy
param = EncryptFileParam(in_file_path = "/tmp/taxes.pdf",
                         out_file_path = "/tmp/taxes.pdf.html")
param.set_policy(policy)

# encrypt the file.
client.encrypt_file(encrypt_file_param = param)

# Bob can not decrypt this file after 10 minutes
// expire 10 minutes from now
Policy policy;
policy.expireInMins(10);

// Create the encrypt params with simple policy
EncryptFileParam param {"/tmp/taxes.pdf", "/tmp/taxes.pdf.html"};
param.setPolicy(policy);

client.encryptFile(param);

// Bob can not decrypt this file after 10 minutes

Or it can be added after encryption:

// File was encrypted a while ago. Now the owner (or admin) wants to expire the file.
const params = new Virtru.DecryptParamsBuilder()
  .withFileSource("/tmp/taxes.pdf.html") // 
  .build();

// See 'How to add Authentication' page to see how to get 'client'
// Once you have client, get the policyId embedded in the TDF file (taxes.pdf.html)
const policyId = await client.getPolicyId(params);
const origPolicy = await client.fetchPolicy(policyId);

// Now update the policy in Virtru Key Management Infra
const updatedPolicy  = origPolicy.builder()
  .enableExpirationDeadlineFromNow(30) // Expire content in 30 seconds.
  .build();
await client.updatePolicy(updatedPolicy)

// Now none of the participants have access to the file.
# File was encrypted a while ago. Now the owner (or admin) wants to expire the file.

# See 'How to add Authentication' page to see how to get 'client'
# Now update the policy in Virtru Key Management Infra
policy = Policy()
policy.expire_in_days(1); # expire in a day
client.update_policy_for_file(policy, "/tmp/taxes.pdf.html")

# all participants will lose access in 1 day from now.
// File was encrypted a while ago. Now the owner (or admin) wants to expire the file.

// See 'How to add Authentication' page to see how to get 'client'
// Once you have client, get the policyId embedded in the TDF file (taxes.pdf.html)

// Now update the policy in Virtru Key Management Infra
Policy policy;
policy.expireInDays(1);
client.updatePolicyForFile(policy, "/tmp/taxes.pdf.html");

// all participants will lose access in 1 day from now.

Watermark Watermark

The watermark control provides persistent control and individualized tracking for sensitive documents. Watermark is applied when the file is read via Virtru's Secure Reader. Watermark control can be set either during the encryption like this:

Important Note about Watermarks

If the watermark control is set, attempting to decrypt the file via Virtru SDK will fail. Only Virtru Secure Reader can decrypt and render the Watermark

const policy = new Virtru.PolicyBuilder()
  .enableWatermarking()
  .build();

// Configure and execute an encrypt.
const encryptParams = new Virtru.EncryptParamsBuilder()
  .withFileSource("/tmp/taxes.pdf")
  .withPolicy(policy)
  .build();
const stream = await client.encrypt(encryptParams);
// Write the ciphertext in HTML format to a local file with .html extension.
await stream.toFile("/tmp/taxes.pdf.html");

// File is shared with Bob via some channel.
// When bob views the document in Virtru Secure Reader, it will have the watermark "bob@example.com"
# See 'How to add Authentication' page to see how to get 'client'
# Once you have client, get the policyId embedded in the TDF file (taxes.pdf.html)

# create a simple policy and share with bob@example.com
policy = Policy()
policy.enable_watermarking()

# create the encrypt params with simple policy
param = EncryptFileParam(in_file_path = "/tmp/taxes.pdf",
                         out_file_path = "/tmp/taxes.pdf.html")
param.set_policy(policy)

# encrypt the file.
client.encrypt_file(encrypt_file_param=param)

# File is shared with Bob via some channel.
# When bob views the document in Virtru Secure Reader, it will have the watermark "bob@example.com"
// See 'How to add Authentication' page to see how to get 'client'
// Once you have client, get the policyId embedded in the TDF file (taxes.pdf.html)

// Create a simple policy, share with bob@example.com and enable watermarking
Policy policy;
policy.enableWatermarking();

// Create the encrypt params with simple policy
EncryptFileParam param {"/tmp/taxes.pdf", "/tmp/taxes.pdf.html"};
param.setPolicy(policy);

client.encryptFile(param);

// File is shared with Bob via some channel.
// When bob views the document in Virtru Secure Reader, it will have the watermark "bob@example.com"

Watermark control can be set post encryption like this:

// File was encrypted a while ago and 'bob@example.com' was given authoriztion to decrypt.
// Now the owner (or admin) wants to add watermarking support.
const params = new Virtru.DecryptParamsBuilder()
  .withFileSource("/tmp/taxes.pdf.html") // 
  .build();

// See 'How to add Authentication' page to see how to get 'client'
// Once you have client, get the policyId embedded in the TDF file (taxes.pdf.html)
const policyId = await client.getPolicyId(params);
const origPolicy = await client.fetchPolicy(policyId);

// Now update the policy in Virtru Key Management Infra
const updatedPolicy  = origPolicy.builder()
  .enableWatermarking() // add watermarking
  .build();
await client.updatePolicy(updatedPolicy)
// Now 'bob@example.com' will be able view the file only in Virtru Secure Reader // with watermark prominently displayed on the file. 
# File was encrypted a while ago. Now the owner (or admin) wants to add watermark to the file

# See 'How to add Authentication' page to see how to get 'client'
# Now update the policy in Virtru Key Management Infra
policy = Policy()
policy.enable_watermarking() # add watermarking
client.update_policy_for_file(policy, "/tmp/taxes.pdf.html")

# Now 'bob@example.com' will be able view the file only in Virtru Secure Reader
# with watermark prominently displayed on the file. 
// File was encrypted a while ago. Now the owner (or admin) wants to add watermark to the file

// See 'How to add Authentication' page to see how to get 'client'
// Now update the policy in Virtru Key Management Infra

Policy policy;
policy.enableWatermarking ();
client.updatePolicyForFile(policy, "/tmp/taxes.pdf.html");

// Now 'bob@example.com' will be able view the file only in Virtru Secure Reader
// with watermark prominently displayed on the file.

The owner can also disable watermarking by calling policy.disableWatermarking()

How to Add Virtru Controls


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.