toc

Tutorial

Get started in 3 simple steps.

This Tutorial is the best way to get started with Evervault. You'll follow 3 easy steps:

  1. Encrypt sensitive data →
  2. Store encrypted data →
  3. Process encrypted data →

Before you begin, create an account and a team in the Evervault Dashboard.

Step 1: Encrypt sensitive data

You can encrypt sensitive data as it enters your app — either client-side or server-side — with one simple function: evervault.encrypt(). There's no need to manage encryption keys, and Evervault cannot decrypt the data.

Install Evervault SDKs

To encrypt on the client, install one of the Evervault client-side SDKs: React or Javascript. To encrypt on the server, install one of our server-side SDKs: Node.js, Python, Ruby or PHP.

  • React.js
  • JavaScript
  • Node.js
  • Python
  • Ruby
  • PHP
bash
# Run this in the root of your project directory
npm install @evervault/react
Client-side SDK in React Native, and server-side SDK in Go coming soon.

Initialize Evervault SDK

Once installed, initialize your chosen SDK with your team's unique ID found in the Settings.

  • React.js
  • JavaScript
  • Node.js
  • Python
  • Ruby
  • PHP
jsx
// To make Evervault available for use in your app,
// use an EvervaultProvider component for your app.
// Make sure to pass in your team's unique ID.
import { EvervaultProvider } from '@evervault/react';
export const App = () => (
<EvervaultProvider teamId={'<YOUR_TEAM_ID>'}>
<ChildComponent />
</EvervaultProvider>
);

Encrypt your data

To encrypt data where it enters your app, simply pass an object or string into the evervault.encrypt() function.

  • React.js
  • JavaScript
  • Node.js
  • Python
  • Ruby
  • PHP
jsx
// Any time you want to encrypt data simply import useEvervault()
import React from 'react';
import { useEvervault } from '@evervault/react';
export const MyComponent = ({ someState }) => {
const evervault = useEvervault();
const [plaintextState, setPlaintextState] = React.useState({
accountNumber: 'ABC-12389US',
});
const [encryptedState, setEncryptedState] = React.useState(undefined);
const encryptState = React.useCallback(
async () => setEncryptedState(await evervault.encrypt(plaintextState)),
[setEncryptedState, evervault]
);
React.useEffect(() => encryptState(), [encryptState]);
if (encryptedState) {
return <p>{encryptedState}</p>;
}
};

Learn more about the Evervault Encryption Scheme (EES) →

Step 2: Store encrypted data

Store the encrypted data in your database. You don't need to change:

  1. How you pass data to your database, or
  2. Your existing data structure.
javascript
// Encrypt your plaintext data
const encryptedData = await evervault.encrypt({
name: 'Elon Musk',
email: 'elon@boringcompany.com',
dateOfBirth: '1/1/0001',
});
// encryptedData will be an object with the
// same structure, but with encrypted values
const encryptedData = {
name: 'eyJpc3MiOiJldmVydmF1bHQiLCJ2ZXJzaW9uIjoxLCJkY0ifQ==.3f07bd95c99e',
email: 'eyJpc3MiOiJldmVydmF1bHQiLCJ2ZXJzaW9uIjoxLCJkYXRn0=.3e61b9ba147d',
dateOfBirth: 'eyJpc3MiOiJldmVydmF1bHQiLCJ2ZXJzHlwZSI6InN0=.4fb74bd58d36',
};
Storage by Evervault coming soon.

Learn more about the format of Evervault-encrypted data →

Step 3: Process encrypted data

The only way to process your encrypted data is to deploy and run an Evervault Cage.

Evervault Cages

Cages are serverless functions for processing encrypted data. Cages are isolated from your stack, and hosted on Evervault.

You can write and deploy any serverless function to a Cage. At present, Cages can only be written in Node.js. You can call and run a Cage with any language that can send HTTPS requests.

Deploy Docker Containers as Cages for machine learning, resource-intensive apps or services, and worker processes — coming soon.

Deploy your Cage

You can deploy a Cage in 3 ways: by connecting to a GitHub repository (see below), using the Evervault CLI or using Cagify for inline deployments in Node.js.

Create Cage with GitHubEvervault Dashboard

In the Evervault Dashboard:

  1. Click New Cage
  2. Select Choose Template
  3. Authenticate with GitHub if you haven’t already
  4. Install the Evervault app on GitHub
  5. Select a template Cage
  6. Create your Cage

Run your Cage

Automatically run your Cage code by passing the Cage name and the payload into the evervault.run() function. Or, send an HTTPS POST request with a JSON payload and API-KEY header to https://cage.run/cage-name.

Cages can currently only be called server-side because they require your team's API key for authentication.

  • React.js
  • JavaScript
  • Node.js
  • Python
  • Ruby
  • PHP
Coming soon: run Cages client-side. For now, please refer to the Node.js guide.

Run your application to see the result. Return the result to the client via your server, or forward it to a third party API via an HTTP request. All outbound HTTP requests are logged, and are shown in your team's Dashboard.

The Node.js SDK is pre-initialized in all Cages as the globally-scoped evervault object. This allows you to encrypt the result, and store it in your database.

Update your Cage

If you do a push to your GitHub repo, Evervault will automatically update your Cage code. If you choose to deploy with the Evervault CLI, use the cage:deploy command to update your Cage code.

Recap

You're now:

  1. Encrypting data as it enters your app by passing a payload into the evervault.encrypt() function;
  2. Storing the encrypted data in your database without having changed your data structure; and
  3. Processing the encrypted data by running a Cage using the evervault.run() function.

You can encrypt any data, and configure Cages to run any function.

Simply repeat the encrypt-store-process cycle each time you want to encrypt new data, and run new functions on it.