Virtru-sdk NPM

Virtru SDK for JavaScript

The Virtru SDK allows developers to securely and easily encrypt and manage access to sensitve data. This comprehensive documentation serves as the source of truth for the functionality and usage of the Virtru JavaScript SDK.

TDF Architecture

For more information, please see the Virtru Developer Hub or join us on Slack.

Core Concepts

The SDK

TDF Ciphertext - Ciphertext encrypted using the open TDF standard. Each TDF Ciphertext is encrypted with a unique data key and managed with independent access controls. See the Developer Hub and TDF whitepaper for more information.
Virtru Policy - An policy specifying access controls to enforce on encrypted data, such as expiry and ACL.
User - An entity authenticated with Virtru. SDK users can allow other users access to encrypted data. For instance, bob@virtru.com can authorize alice@virtru.com to access some encrypted data at either encryption-time or any time afterwords.

Getting Started

Currently the SDK is available in minified, Web-ready form via a Virtru CDN. It can be included via a <script> tag as shown below:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Virtru SDK for JavaScript - Sample Application</title>
    <script src="https://sdk.virtru.com/js/latest/virtru-sdk.min.js"></script>
</head>


<body>
  <script type="text/javascript">
    var client = new window.Virtru.Client.VirtruClient();
    document.body.innerHTML = `Version: ${client.getClientVersion()}<br/>Your page is now configured to use the Virtru Data Protection JS SDK!`; 
  </script>
</body>
</html>

In the near future, an npm distribution will also be available for use. Stay tuned.

Authentication

The SDK accepts an AuthProvider which handles authenticating to Virtru for all backend service calls. Several auth schemes are supported, including federated auth (shown below) and custom Virtru credentials. The AuthProvider is a required configuration property for all client operations (excluding getClientVersion(), as shown above.

// Set the AuthProvider during client construction.
const email = "alice@virtru.com"
const client = new Virtru.Client({authProvider: new Virtru.ClientAuth.Providers.GoogleAuthProvider({email})});

The Virtru Client will continue to use the federated Google identity to authenticate to the Virtru backend, refreshing credentials internally as necessary.

Encrypting Data

Once the client is constructed you can use it to start encrypting data.

// Configure and execute an encrypt.
// The creator (alice@virtru.com) always has access, so we don't need to specify her in the ACL.
const encryptParams = new Virtru.EncryptParamsBuilder()
  .withStringSource("Sokath, his eyes opened!")
  .withUsersWithAccess(["bob@virtru.com"]) 
  .build();
const ct = await client.encrypt(encryptParams);

You can use standard stream processing methods to handle the returned Readable stream.

// Write the TDF ciphertext to stdout, node style.
ct.pipe(process.stdout);

Or you can just use the built in helper methods to write out the TDF ciphertext contents.

// Write the TDF ciphertext to the console.
console.log(await ct.toString());

Decrypting Data

You can also start decrypting data with the client. If the authenticated user is authorized, this returns a Readable stream containing the decrypted plaintext and helper methods for writing.

// Configure the parameters to decrypt a local file.
const decryptParams = new Virtru.DecryptParamsBuilder()
  .withFileSource("plain.tdf")
  .build();

// Run the decrypt.
const pt = await client.decrypt(decryptParams);

// Write the result to a local file.
await pt.toFile("plain.txt");

Common Use-Cases

This section lists some example usages using the Virtru SDK. See the Developer Hub for examples of a wide range of common use-cases.

Example: Encrypting data with expiration.

// Construct an authorization policy to apply to the encrypted data.
// Note that *expiration only applies to other users*, not the creator.
const policy = new Virtru.PolicyBuilder()
  .enableExpirationDeadlineFromNow(60)
  .build();

// Configure the encrypt parameters to encrypt a provided string.
const encryptParams = new Virtru.EncryptParamsBuilder()
  .withStringSource("I expire in 60 seconds")
  .withUsersWithAccess(["bob@virtru.com", "charlie@virtru.com"])
  .withPolicy(policy)
  .build();

// Run the encrypt and write the result to stdout.
(await client.encrypt(encryptParams)).pipe(process.stdout);

Example: Adding users to the data ACL after encryption.

// Configure the encrypt parameters to encrypt a provided string.
const policyId = uuid.v4();
const encryptParams = new Virtru.EncryptParamsBuilder()
  .withPolicyId(policyId) // can alternatively set on the PolicyBuilder
  .build();

// Run the encrypt and write the result to stdout.
(await client.encrypt(encryptParams)).pipe(process.stdout);

// Time passes...

// Some time later we decide to allow bob access to the data.

// First fetch the Policy. We assume the policyId is already stored: 
// this could be retrived from a separate index, parsed from the TDF ciphertext 
// using the client helper (WS-9400), or pulled from the TDFCiphertextStream returned
// by `encrypt` (WS-9400).
const policy = await client.fetchPolicy(policyId)

// Update the policy locally, adding the new user.
const updatedPolicy = policy.builder().addUsers("bob@virtru.com").build();

// Commit the update to the Virtru backend.
await client.updatePolicy(updatedPolicy);

@opentdf/client formidable

@everything-registry/sub-chunk-3057 @infinitebrahmanuniverse/nolb-vir @virtru/sdk-cli

3 months ago

4 months ago

4 months ago

5 months ago

6 months ago

6 months ago

6 months ago

8 months ago

10 months ago

9 months ago

11 months ago

11 months ago

10 months ago

11 months ago

9 months ago

9 months ago

9 months ago

10 months ago

10 months ago

9 months ago

7 months ago

9 months ago

11 months ago

8 months ago

9 months ago

10 months ago

10 months ago

9 months ago

10 months ago

9 months ago

7 months ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

12 months ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

2 years ago

1 year ago

1 year ago

1 year ago

1 year ago

2 years ago

2 years ago

2 years ago

1 year ago

1 year ago

2 years ago

2 years ago

2 years ago

1 year ago

1 year ago

1 year ago

2 years ago

1 year ago

2 years ago

1 year ago

2 years ago

2 years ago

1 year ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago