DocsSDKsAPI
Dashboard

SDKs

Node.js SDK

You can use our Node.js SDK to:

  • Encrypt data server-side
  • Decrypt data server-side
  • Invoke Functions
  • Proxy requests through Relay

Encrypting/Decrypting data with our backend SDKs instead of Relay may expose you to greater compliance burden because your server handles plaintext data.

Instead you can:

  • Use a Relay to encrypt data before it reaches your server.
  • Use our client-side SDKs to encrypt data before sending it to your server.

Quickstart

Install SDK

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

Initialize 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.

Encrypt a string

Now that the SDK is initialized, we can encrypt a string.

Full example

Pulling all of this together leaves us with the following working example. You can copy and paste the code below (using a sandbox API key and App ID), run it in your own environment and run the encryption for yourself.

Working with Third Party SDKs

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.

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.

Reference

new Evervault(appId, apiKey)

The SDK constructor accepts three parameters:

  1. Your App's ID
  2. Your App's API key
  3. Optional configuration parameters
Parameters
appIdRequiredString

Your Evervault App's ID.

apiKeyRequiredString

Your Evervault App's API Key.

evervault.encrypt(data)

evervault.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.

Parameters
dataRequiredString | Object | Buffer

The data you want to encrypt.

evervault.decrypt(data)

evervault.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.

Parameters
encryptedRequiredString | Object | Buffer

The data you want to decrypt.

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.

evervault.createClientSideDecryptToken(payload, expiry)

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.

Parameters
payloadRequiredString | Object | Buffer

The payload containing encrypted data that the token will be used to decrypt.

expiryDate

The time the token will expire. Defaults to 5 minutes in the future.

evervault.run(functionName, data)

evervault.run() lets you invoke an Evervault Function with a given payload

Parameters
functionNameRequiredString

The name of the function your want to run.

dataRequiredObject

The data you want to send to the function.

Response

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

evervault.createRunToken(data, options)

evervault.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.

Parameters
functionNameRequiredString

The name of the function your want to run.

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.

Response

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

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

evervault.enableOutboundRelay(options)

If the SDK you are using does not support a proxy agent you can use this function. Its is recommended to use createRelayHttpsAgent() for all other use cases.

Configures your application to proxy HTTP requests using Relay based on the configuration created in the Evervault dashboard. See Relay to learn more.

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.

evervault.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.

using HTTPSProxyAgent with Axios

Axios is configured in the following example to send a request through Relay.

evervault.createEnclaveHttpsAgent(enclaveAttestationData, evervaultAttestationBindings)

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.

Parameters
enclaveAttestationData

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. See our example of using the Evervault API as a provider for a more robust approach.

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.