Products
Inbound Relay
Inbound Relay is an encryption proxy that intercepts and encrypts, or redacts, selected fields and files in an HTTPS request before forwarding the request to its original destination.
Since fields are secured before reaching your server, you can collect sensitive data (like credit card numbers, SSNs, credentials or health data) from your users without ever handling it in plaintext.
Inbound Relay can be placed in front of any HTTPS API and configured within the Evervault Dashboard to encrypt or redact any fields within a JSON, XML or multipart/form-data
payload.
Getting Started
Get Started
Encrypt a string in less than 5 minutes with Evervault CEO Shane Curran.
Get up and running with Evervault Encryption in less than 5 minutes.
In this example, you will use Inbound Relay to encrypt and redact sensitive data. Before starting this tutorial, you'll need to sign up for an Evervault account and create an App.
Create an endpoint
To get started with Inbound Relay, you will need an API endpoint that is accessible publicly over the internet. In this example, we will use RequestBin — a free service for generating temporary API endpoints which allows you to log and inspect request and response payloads.
You can create a RequestBin by navigating to requestbin.com/r. After doing so, you will be presented with an API endpoint URL which you can send requests to.
You can send an HTTPS POST
request to your RequestBin using the following cURL script:
If you navigate back to the RequestBin Dashboard, you should be able to see the payload by clicking the request in the log panel on the left.
Create an Inbound Relay
Now that you have a publicly accessible API endpoint, you can create an Inbound Relay. An Inbound Relay is an encryption proxy that sits between the client and server.
To create an Inbound Relay, go to the “Inbound Relay” section within your App in the Evervault Dashboard. Click the “Create an Inbound Relay” button and paste in your RequestBin endpoint URL as the target.
You’ll then be given a new API endpoint which you can send requests to. Any requests that are sent to this API endpoint will be intercepted by Evervault before being proxied to the original destination API endpoint. In the next section, you’ll configure the proxy to encrypt certain fields in the request.
If we run the previous cURL command with our new Evervault API endpoint, the request will be proxied to RequestBin without any fields having been encrypted.
Protect Your Sensitive Data
Now that you're proxying traffic through Inbound Relay, you can configure it to start securing sensitive fields.
Inbound Relay currently provides two ways to protect your data: Encryption and Redaction.
Encryption and Redaction are useful for two distinct use cases.
Encryption
Encrypted data can be decrypted at a later stage (using Functions, Cages, or Outbound Relay). This is particularly useful when receiving sensitive data that you primarily send to third-party APIs, or that you want to process using your own code.
Redaction
Relay can redact PII from specific JSON fields and replace the PII with synthetic data. Using Inbound Relay for Redaction can be particularly useful when sharing sensitive data with third-party LLMs, like OpenAI.
Inbound Relay can also unredact the data after the response is received from an LLM or other third parties. You can configure unredaction by going to Inbound Relay
-> Secured Fields
-> Response Body
-> Unredacted Fields
and entering the JSON path on the response body where Relay should find and replace the redacted data with the original values. When unredaction is configured, a map of the PII and the redacted values will be returned in a X-Evervault-Redacted
header.
Relay Redaction is currently in public beta.
Encryption and Redaction Example
In the code snippet above, you are sending a name and a Social Security Number. We will configure our Inbound Relay to encrypt the Social Security Number, and redact the name.
To begin, navigate to the Secured Fields section within your Inbound Relay's page in the Evervault Dashboard. If you click on the Add Fields button in the top right of the page, a modal will appear where you can specify both the fields to encrypt, and the fields to redact.
To encrypt the ssn
field, we will simply type ssn
into the Encrypted Fields input. Then to redact the name
, we will type name
into the Redacted Fields section.
Once you have configured both fields, click the Save button at the bottom of the modal.
You can also specify fields to encrypt/redact manually using JSONPath Selectors. This is useful for more advanced query patterns.
When you run the same cURL command as above, you will see that the request logged in the RequestBin will contain a different name
in plaintext and the ssn
field will be an Evervault-encrypted string. Rerunning this cURL command will produce a different name each time.
You have successfully used Inbound Relay to secure your data!
What’s next?
Any strings you encrypt using Inbound Relay can now be used across the rest of the Evervault Platform. To share it with a third-party API, you can use Outbound Relay. To process it using your own code, you can use either Evervault Functions or Evervault Cages.
Response Decryption
By default, Inbound Relay will automatically scan any responses from your endpoint and decrypt any fields containing Evervault-encrypted data. This means that any clients of your Inbound Relay will never interact with encrypted data, but your endpoint will only ever see encrypted data.
Custom Domains
Inbound Relay lets you specify custom domain names if you would prefer not to include an evervault.com
hostname in your Inbound Relay’s URL. During Relay creation, simply specify your own hostname of choice. The Dashboard will then guide you through adding a custom CNAME
record to point traffic to your Inbound Relay. The CNAME required will point to custom.relay.evervault.com
.
If you require client IPs in your target server, you can change the CNAME to point to direct.custom.relay.evervault.com
. This will append the client IP to the X-Forwarded-For
header of the request.
mTLS
Inbound Relay lets you upload a client certificate to authenticate with the target server over mTLS. You can upload a client cert on the configuration page of your Inbound Relay. When mTLS is enabled, requests through that Relay will require an Evervault API Key. This can be added as an HTTP header (api-key: API-KEY...
). If the mTLS cert has a password attached, it is encrypted with your team's encryption keys before being sent to Evervault's backend.
Fields to Encrypt
Inbound Relay supports several different content types. Currently, we support JSON, XML, Form URL Encoded and Multipart Form Data. When it comes to configuring your fields to encrypt, it can vary depending on what Content-Type you're targeting. JSON and XML both support JSONPath selectors for more advanced field selection deep into the objects themselves, while Form URL Encoded and Multipart Form Data only take the names of the fields to be encrypted since they are both flat structures. When you add a field to encrypt, you will be asked whether you're adding a JSON field or a Form field. JSON fields will only attempt to match on JSON and XML requests, while form fields will only be applied to Form URL encoded and Multipart Form data requests.
WebSockets
Inbound Relay supports WebSockets. Simply use your Relay hostname as the WebSocket target, and we will transparently encrypt and decrypt all client-server and server-client messages containing JSON or XML.
File Encryption
Inbound Relay supports encrypting files and text-fields in multipart/form-data
uploads. Simply configure the relevant form fields in your Relay's Fields To Encrypt. Encrypted files will arrive at your server with an unchanged filename, but the bytes in the file will be fully encrypted.
All Evervault encrypted files begin with the unicode bytes %EVENC
. You can use this to validate that files are arriving encrypted.
For Response Decryption, Relay will scan and decrypt both multipart/form-data
responses or raw file responses, e.g. image/png
.
There is currently a per-request limit of 25 MB for encryption/decryption.
To help you get started, check out our Guide to File Encryption!
Alerts
Alerts allow you to see errors in Slack, Discord or sent to any webhook url of your choice. You can create an alert for your Relay inside of the Evervault Dashboard by navigating to Relay -> Alerts -> Add Alert
Webhooks
When you configure a custom webhook to receive alerts, the following fields will be in the response.
The relay error code
Error Codes
If you received a failed response from Relay that included an X-Evervault-Error-Code
header or if you received a JSON response with an evervault-error-code
field in the case of programmatic access, you can use this Relay error code reference to help resolve the issue.
This error indicates you are sending a request to a Relay (e.g my-api-com.relay.evervault.com) which doesn't exist. Ensure you have entered the Relay subdomain correctly. Also, ensure you have configured your Relay correctly by following our Relay documentation.
If you are still having issues, please contact support.
The target took too long to respond. The error can have many causes ranging from network issues to malformed client requests. Ensure the target domain URL is correct, wait a few moments and try again. If the error persists, reach out to the owner of the target domain through any support channels they have in place.
There was an issue with Relay itself. Try again in a few moments. If the issue persists, reach out to support.
There was an issue finding a Relay for the provided domain. Make sure you are using the correct domain. If your domain is correct but you are still seeing this issue, ensure you have Relay configured correctly by following our Relay documentation.
This error occurs when Relay is configured to perform response encryption and receives an unsupported content type as a response from the endpoint. Currently, Relay only can only encrypt JSON, XML and multipart/form-data
structured data.
If your endpoint does not support these formats, one way to get around this limitation is to move your request logic into a Function in which you parse the plaintext into a suitable form, encrypt it and return it to the client.
There was an issue authenticating with the provided API key. Ensure that you are using the correct API key.
There was encrypted data where it wasn't expected. This can mean a number of things:
- An inbound request header value contained Evervault encrypted data.
- An inbound request payload had Evervault encrypted data as the value of one of the fields, which was not going to be encrypted.
- The target URI for the inbound request had Evervault encrypted data as part of the path.
The server is unable (or refuses) to process the request sent by the client, due to an issue that is perceived by the server to be a client problem.
Your App has made an outbound request to a destination that isn't trusted by Relay.