Node.js

Encrypting/Decrypting data with our backend SDKs may expose you to greater compliance burden because your server needs to handle plaintext data. Instead, we recommend using Relay or our Client-Side SDKs to encrypt data.

Getting started

Install the SDK

First, let's install the Evervault SDK using your package manager of choice.

1npm install @evervault/node

Initialize the SDK

Now, let's initialize the SDK using our App's ID and our App's API key. If you don't have an API key yet, you can get one by creating an App in the Evervault Dashboard.

1const Evervault = require("@evervault/sdk");
2const evervault = new Evervault("<APP_ID>", "<API_KEY>");

Relay proxies

SDKs that support using proxies can be configured to use Relay, use the createRelayHttpsAgent() function to return a pre-configured HTTPSProxyAgent. The Agent will use the HTTP CONNECT protocol to establish a connection to Relay. Below is how you would configure Relay with the Stripe Node.js SDK.

1const httpsAgent = evervault.createRelayHttpsAgent();
2
3const stripe = Stripe("sk_test_...", {
4  maxNetworkRetries: 1,
5  httpAgent: httpsAgent,
6  timeout: 1000,
7  host: "api.example.com",
8  port: 123,
9  telemetry: true,
10});

The HTTPSProxyAgent can also be used with popular HTTP clients like axios. Its important to note that the URL of the request is not the Relay URL but the URL of the target.

1// Send a singular request with encrypted data to a third-party API
2const httpsAgent = evervault.createRelayHttpsAgent();
3const payload = { sensitiveField: "sensitive value" };
4const response = await axios.post("https://example.com", payload, {
5  httpsAgent,
6  headers: {
7    "Content-Type": "application/json",
8  },
9});

Reference

Evervault

The SDK constructor accepts two parameters; your App's ID and your App's API key.

1const Evervault = require("@evervault/sdk");
2const evervault = new Evervault("<APP_ID>", "<API_KEY>");

Parameters

appIdRequiredString
Your Evervault App's ID.
apiKeyRequiredString
Your Evervault App's API Key.

encrypt()

Encrypts data using Evervault Encryption.

To encrypt strings using the Node.js SDK, simply pass a String or an Object into the evervault.encrypt() function. To encrypt a file, pass a Buffer.

The encrypted data can be stored in your database or file storage as normal. Evervault Strings can be used across all of our products. Evervault File Encryption is currently in Beta, and files can only be decrypted with Relay.

1const Evervault = require("@evervault/sdk");
2const evervault = new Evervault("<APP_ID>", "<API_KEY>");
3
4// encrypt a string
5const encrypted = await evervault.encrypt("Hello, world!");
6
7// encrypt a file
8const fileContents = fs.readFileSync("<input-file>");
9const encryptedFile = await evervault.encrypt(fileContents);
10fs.writeFileSync("<output-file>", encryptedFile);

Parameters

dataRequiredString | Boolean | Number | Object | Buffer
The data to encrypt.

decrypt()

Decrypts data previously encrypted with the encrypt() function or through Relay. An API key with the decrypt permission must be used to perform this operation.

1const Evervault = require("@evervault/sdk");
2const evervault = new Evervault("<APP_ID>", "<API_KEY>");
3
4const encrypted = await evervault.encrypt("Hello, world!");
5const decrypted = await evervault.decrypt(encrypted);
6console.log(decrypted);
7// Hello, world!

Parameters

dataRequiredString | Object | Buffer
The data to decrypt.

PCI Compliance

Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases. Instead you can:

Use Relay to decrypt data before it reaches third-party services.
Use Functions or Enclaves to process encrypted data.

createClientSideDecryptToken()

Client Side Decrypt Tokens are versatile and short-lived tokens that frontend applications can utilise to decrypt data previously encrypted through Evervault. Client Side Decrypt Tokens are restricted to specific payloads.

By default, a Client Side Decrypt Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future.

1const encryptedData = await evervault.encrypt("foo");
2const now = new Date();
3const timeInFiveMinutes = now.setMinutes(now.getMinutes() + 5);
4
5const token = await evervault.createClientSideDecryptToken(
6  encryptedData,
7  timeInFiveMinutes
8);

Parameters

payloadRequiredString | Object | Buffer
The payload containing the encrypted data that the token will be used to decrypt.
timeToLiveNumber
The time the token will expire. Defaults to 5 minutes in the future.

run()

Lets you invoke an Evervault Function with a given payload.

1const Evervault = require("@evervault/sdk");
2const evervault = new Evervault("<APP_ID>", "<API_KEY>");
3
4const result = await evervault.functions.run("hello-function", {
5  name: "Claude Shannon",
6  ssn: "ev:encrypted_string",
7});

Parameters

functionNameRequiredString
The name of the function to invoke.
dataRequiredObject
The payload to pass to the function.

Successful Function runs will return an object containing a Function Run ID and the result from your Function in the following format:

1{
2  "id": "func_run_09413338da56",
3  "status": "success",
4  "result": {
5    "message": "Hello from a Function! It seems you have 14 letters in your name",
6    "name": "ev:RFVC:TTLHY04oVJlBuvPx:A7MeNriTKFES0Djl9uKaPvHCAn9PjSfOHu7tswXFCHF9:jwYKE13o3iQlr6Dn/DRk80XpNOGb:$"
7  }
8}

createRunToken()

Creates a single use, time bound token (5 minutes) for invoking an Evervault Function with a given payload. Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.

1const Evervault = require("@evervault/sdk");
2const evervault = new Evervault("<APP_ID>", "<API_KEY>");
3
4const runToken = await evervault.createRunToken("hello-function", {
5  name: "Claude Shannon",
6  ssn: "ev:encrypted_string",
7});

Parameters

functionNameRequiredString
The name of the function to invoke.
dataObject
The data you want to send to the function. If not provided, a run token will be created, and the payload will not be validated when the function is executed.

When you create a Run Token, the SDK will return a JSON object containing your token.

1{
2  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsInZlciI6IjAuMCJ9.eyJhcHBVdWlkIjoiYXBwX2RmZGE3MmUwMTZiMCIsImZ1bmN0aW9uTmFtZSI6ImhlbGxvLWNhZ2UtdGFsbC13YWxscy10cmF2ZWwiLCJydW5JZCI6IjRiMjhmMzNlLWU3NjYtNDI2OC1iNmY2LTUyYzZkM2VmMGQzYyIsImV4cCI6MTY2Nzg3Njc2Nn0.gCiFw7UJ8gjZfeXNEaqX4H1Y9HBX9avjioZ4yDU8PTtmGT4QTzVOhnDV46v_yyXLxpO1BgzoBRpYbLciiW1_QXSLmx6cCuJy4vHUZwssHT13vB7AXIl_88Ab5R7w9vpOQIDoCjhPVWJsolwUiiGh_5yE4wGv6WPTIfSv249_hpJLMz3AAffXUckiLPxFporY73KXtTANQH_zniivB91KdBnyGhle7gTs1EXWLqpdMIrqOz9cmoXU31DGd-AgeMzM082s_XtdCFq7FNLLtg6Nx8Mx8Bjl0cKV41R-jbTpHSXxutLX-PSDmWn5wSqDhlQoEWdTLsoS6xp7qhZ2urYyYg"
3}

Run Tokens can then be used to authenticate Function runs from the client-side.

1fetch("https://api.evervault.com/functions/[function-name]/runs", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: `RunToken [run-token]`,
6  },
7  body: JSON.stringify({
8    payload: {
9      ssn: "encrypted_string",
10    },
11  }),
12});

enableOutboundRelay()

We recommend using the createRelayHttpsAgent() function instead of this function if the SDK you are using supports proxy agents.

Automatically configures your application to proxy requests through Relay when making requests to domains you have configured Relays for inside of the Evervault Dashboard. See Relay to learn more.

1await evervault.enableOutboundRelay();

Parameters

options.decryptionDomainsString[]
Requests sent to any of the domains listed will be proxied through Relay. This will override the configuration created in the Evervault dashboard.
options.debugRequestsBoolean
Output request domains and whether they were sent through Relay.

createRelayHttpsAgent()

The HTTPSProxyAgent allows for more granular control over what requests gets sent through Relay. This can be passed to any client that supports the Node.js Agent as a parameter.

1const axios = require("axios");
2const httpsAgent = evervault.createRelayHttpsAgent();
3const payload = { sensitiveField: "sensitive value" };
4const response = await axios.post("https://example.com", payload, {
5  httpsAgent,
6  headers: {
7    "Content-Type": "application/json",
8  },
9});

createEnclaveHttpsAgent()

Returns a HTTPS Agent which can be used to attest all TLS connections to your Evervault Enclave. See Enclave's TLS Attestation to learn more.

1const AttestationBindings = require("@evervault/attestation-bindings");
2
3const enclaveHttpsAgent = await evervault.createEnclaveHttpsAgent(
4  {},
5  AttestationBindings
6);
7
8const response = await axios.post(
9  "https://my-enclave.my-app.enclave.evervault.com",
10  encrypted,
11  {
12    httpsAgent: enclaveHttpsAgent,
13  }
14);

Parameters

enclaveAttestationDataObject
A mapping of Enclave names to their PCRs or Callbacks which resolve to PCRs. This is optional. When included, the connection will only be attested when the PCRs match exactly. The provided data can be either a single Object, or an Array of Objects to allow roll-over between different sets of PCRs. If not provided, the attestation doc and its signature will be validated but the PCRs will be ignored.
evervaultAttestationBindings
The Evervault Attestation Bindings distributed as @evervault/attestation-bindings on npm. For testing, you can provide a mock object with a single async attestEnclave function.

Using static PCRs

The most simple way to set up your Evervault client to attest Enclaves is to provide hardcoded PCRs. This approach is not recommended for production deployments, as your clients will fall out of sync from the Enclave during deployments.

1const AttestationBindings = require("@evervault/attetation-bindings");
2const enclaveHttpsAgent = await evervault.createEnclaveHttpsAgent({
3  "my-enclave": {
4    pcr0: "...",
5    pcr1: "...",
6    pcr2: "...",
7    pcr8: "...",
8  },
9  AttestationBindings,
10});

Using the Evervault API as a PCR Provider

The Evervault API exposes an endpoint to retrieve the PCRs for all active deployments of an Enclave. This can be used to keep your Client in sync with your Enclave across deployments.

1const AttestationBindings = require("@evervault/attestation-bindings");
2const axios = require("axios");
3
4async function resolveEnclavePCRsFromEvervaultAPI() {
5  const { data: responseBody } = await axios.get(
6    "https://api.evervault.com/enclaves/my-enclave/attestation",
7    {
8      headers: {
9        "x-evervault-app-id": "app_1234", // replace with your app uuid
10      },
11    }
12  );
13  /**
14   * The API Responds with the enclave attestation under the top level data key:
15   * { "data": [{ "pcr0": "...",  ... }] }
16   */
17  return responseBody.data;
18}
19
20const enclaveHttpsAgent = await evervault.createEnclaveHttpsAgent(
21  {
22    "my-enclave": resolveEnclavePCRsFromEvervaultAPI,
23  },
24  AttestationBindings
25);

Node.js

Parameters

Parameters

Parameters

PCI Compliance

Parameters

Parameters

Parameters

Parameters

Parameters

On this page