- How Relay Works
- Outbound Interception
- Consistent Encryption
- Response Encryption
- Relay with Local Servers
- Relay FAQ
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.
- Include Evervault SDK: Include and initialize our server-side SDK in your application.
- Set Relay domain: Point your app to Relay and set its target using either an auto-generated Evervault domain or your own custom domain.
- Add fields to encrypt: Select global or route-specific fields for Relay to automatically encrypt and decrypt.
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.
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.
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.
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 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.
Outbound Relay supports two authentication mechanisms:
- Include a
Proxy-Authorizationheader 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.
- 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_PROXYenvironment variable which can be set as follows:
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.
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.
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 can be configured in two modes: Request Encryption & Response Encryption.
Relay encrypts fields when a request is sent through it. Relay forwards the payload with encrypted data to the destination you set, e.g. your API. The response from this destination may contain encrypted data. Relay will decrypt this data automatically so that authorized clients can render the plaintext to your users in your UI.
Some data, like cardholder data and application secrets, should never be rendered in plaintext. Relay can be configured to encrypt fields contained in a response from a destination (whether it is your API or a 3rd Party API), so that the data is masked and never shown in plaintext to your users.
Updating your Relay configuration
To enable Response Encryption, navigate to your Relay Configuration page and enable the Only Encrypt Response toggle.
Relay with Local Servers
If you have a server running locally, it's possible to use Relay in development mode to test Relay functionality.
- Install the CLI. To use Relay in development mode, you will need to have the Evervault CLI installed.
- Start the Relay. To start the Relay in development mode, use
ev relay run.
- Choose the Relay. Select the Relay that you would like to use with your local server.
- 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.
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:
By default, all Relay URLs are a subdomain of
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.