toc

Relay

Collect and share sensitive data.

Automatically encrypt sensitive data at the field-level before it enters your app, and decrypt it as it leaves. Integrate in 5 minutes by including our SDK and changing a DNS record.

Using Relay means you can collect sensitive data (like credit card numbers, SSNs, credentials and health data) from your users and share it with third-parties without ever handling it in plaintext.

How Relay Works

Start encrypting sensitive data in minutes.

  1. Include Evervault SDK: Include and initialize our server-side SDK in your application.
  2. Set Relay domain: Point your app to Relay and set its target using either an auto-generated Evervault domain or your own custom domain.
  3. Add fields to encrypt: Select global or route-specific fields for Relay to automatically encrypt and decrypt.
Evervault Dashboard → Create Relay

Relay can be configured to intercept and encrypt inbound data to your API. By providing us with the URL or DNS targets for your API, we will generate a new Relay URL on the .relay.evervault.com subdomain. All requests to this Relay subdomain will be terminated by Evervault. Relay isolates the fields to be encrypted and passes them to E3 for encryption. Relay then reconstructs the original request and passes it on to your API transparently.

If you'd prefer to use your own domain name, you can simply specify a custom domain when you create your Relay. The dashboard will guide you through the steps necessary to create a CNAME record and point your domain name to Relay.

All responses that your API returns will be passed back to the client transparently through Relay. Any fields returned containing encrypted data will also be decrypted before being returned to the client. This means your infrastructure never handles anything other than ciphertext, but your users can still see requests and responses in plaintext.

During development, you can specify a local server as your Relay's target to test Relay functionality.

Relay supports WebSockets. Simply use your Relay hostname as the WebSocket target and we will transparently encrypt/decrypt all client-server and server-client messages containing JSON.

You can specify fields to encrypt by name or by using JSONPath selectors in the Evervault Dashboard.

Relay supports field encryption up to a payload size of 10MB.

You don’t need to change your database configuration, although Evervault-encrypted strings are marginally longer than the original value. This may require you to increase length limits on fields, as well as convert certain datatypes from numeric values to strings. You can store Evervault-encrypted data in your database as you would the plaintext version.


Outbound Interception

By including our Node.js SDK or Python SDK, we will automatically route all requests from your backend to third-party APIs through the Evervault edge network and decrypt any fields that we detect are encrypted. This means that fields can be encrypted before they reach your backend, stored in your database and sent to third-party APIs without writing any logic for decryption, or worrying about storing the data in a secure way.

How does Outbound Interception work?

Relay can be used to pass data to third-party services and APIs using the Relay HTTP CONNECT Proxy on relay.evervault.com:443.

Relay intercepts outbound requests by signing a new certificate for the target (e.g. api.twilio.com) using the Relay Root CA. In order to establish a TLS connection with the target, your system needs to trust the Root CA certificate. Relay transparently terminates TLS-encrypted requests and decrypts all Evervault-encrypted data within the payload before establishing a new TLS connection with the destination and sending the request.

We currently only support CONNECT-over-TLS in order to avoid transmitting credentials in plaintext.

Outbound Relay supports two authentication mechanisms:

  1. Include a Proxy-Authorization header in the destination request. This ensures that your API credentials are TLS-encrypted at all times. Relay will remove this header before being passed to the destination.
  2. Use spec-compliant HTTP Basic Auth with your team ID as the username and your API key as the password. Many languages support the HTTPS_PROXY environment variable which can be set as follows: https://teamID:apiKey@relay.evervault.com:443.

Our Node.js SDK and our Python SDK allow you to automatically forward all requests to Relay with the Proxy-Authorization header included and the Relay Root CA trusted. No additional configuration is required.


Consistent Encryption

Relay allows you to enable Consistent Encryption for fields where you need to avoid data duplication.

For example, if you were encrypting phone numbers and you needed to ensure that the same phone number doesn't already exist in the database, Consistent Encryption would allow you to compare the encrypted phone numbers and check if they are equal.

warningWe do not recommend using Consistent Encryption for fields that do not have many possible values.

Under the hood, consistent encryption uses the original plaintext data as well as a secret that only Relay has access to in order to derive a key that is unique to that particular piece of data. This means that given the same input, consistent encryption will always produce the same encrypted string without using cryptography that is any weaker.

Consistent Encryption should only be used on fields where there are sufficiently many possible values. It is difficult to be specific about what is or isn't safe, but encrypting things like booleans, enums, or short strings would not be a good idea as a potential attacker could easily guess the original value based on how frequently certain ciphertexts appear.

Consistent Encryption can be enabled for specific fields by checking the Add consistent fields checkbox in the "fields to encrypt" configuration for your Relay.

Consistent Encryption takes precedence over standard encryption. That is, if an entry in your payload matches both a consistent field and a standard field, it will be encrypted consistently.


Relay with Local Servers

If you have a server running locally, it's possible to use Relay in development mode to test Relay functionality.

  1. Install the CLI. To use Relay in development mode, you will need to have the Evervault CLI installed.
  2. Start the Relay. To start the Relay in development mode, use ev relay run.
  3. Choose the Relay. Select the Relay that you would like to use with your local server.
  4. Enter your Target. Input the URL (such as http://localhost:3000) that you would Relay to forward requests to.

You will then get a new Relay URL on a .relay.evervault.dev subdomain. All requests to this Relay subdomain will be forwarded to your local server, without having to deploy anything publicly.


Relay FAQ

Below you'll find questions related to sharing encrypted data.

Can I use a custom domain name with Relay?

Yes, you can choose to use your own domain name with Relay. The only change necessary on your end is the creation of a CNAME DNS record to point your custom domain to Relay:

TypeNameValue
CNAMErelay.subdomain.acme.comcustom.relay.evervault.com

By default, all Relay URLs are a subdomain of .relay.evervault.com.

Does Relay encrypt all my data?

Relay only encrypts fields that you specify in the Dashboard. Currently, Relay will only encrypt fields in JSON or form data payloads.

Does Relay decrypt all my data before passing it to third-parties?

Yes. By including our SDKs, Evervault will intercept outbound requests and will automatically decrypt any fields containing Evervault-encrypted data before passing it on to third-parties.

How does Relay intercept requests if they are TLS-encrypted?

Evervault has a Root CA which terminates TLS and opens a new TLS connection to the request's destination. Relay will automatically generate a new certificate for each server you send a request to. The Evervault Relay Root CA must be trusted by your application in order to modify the payload, but our SDKs will automatically trust this certificate for you.

Does Relay support WebSockets?

Yes, Relay supports encryption of JSON fields on WebSocket connections.