Primitives
Relay
Relay is a network proxy that can be configured to encrypt or decrypt sensitive data as it passes between a client and a destination server. Relay can be used with your own API or with third-party APIs. It is designed to be easy to use and requires minimal changes to your existing code.
To process data encrypted by Relay with your own code, you can use either Evervault Functions or Evervault Enclaves.
Getting Started
Encrypt with Relay
Use Relay to encrypt data sent from a browser before it reaches your server.
Get StartedSending requests through Relay
Sending requests through Relay is as simple as changing the URL of your API endpoint to the Relay URL. Relay will intercept the request, encrypt or decrypt the data as configured, and forward it to the original destination.
Working with Third-Party SDKs
When working with a third-party SDK you wont be able to change the URL it makes requests to. In this case, you can use the enableOutboundRelay functionality from any of our Server-side SDKs to automatically intercept requests made by the SDK and send them through Relay instead. Learn more from our Working with Third-Party APIs guide.
Encrypting data with Relay
A common use case for Relay is to encrypt sensitive data before it reaches your own API. This can be done by configuring a request action to encrypt the fields you want to secure. Encrypted data can then be safely stored in your database or used with any Evervault Primitive. To process it using your own code, you can use either Evervault Functions or Evervault Enclaves.
Response decryption
When working with your own API, you may want to decrypt encrypted data that is returned from your API in order to show it to users. This can be done by configuring a response action to decrypt the data you want to display.
Decrypting data with Relay
Relay can also be used to share encrypted data with third-party APIs. This allows you to store the encrypted data while still using third party services as if it was plain text data. This can be done by creating a Relay pointed at the third party API and configuring a request action to decrypt the fields you want to share. Learn more from our Working with Third-Party APIs guide.
Response encryption
When working with third-party APIs, you may want to encrypt sensitive data that is returned in responses from their API. This can be done by configuring a response action to encrypt the fields you want to secure.
Configuring Relay
Relays can be configured to encrypt or decrypt data with route actions. Route actions are a set of rules that determine how a Relay should handle data on request and reponse for certain paths and content types. You can configure route actions inside the Evervault Dashboard.
Path Matching
Route actions will only be applied to requests that match the route path. Route paths can be configured to match a specific path or multiple paths with a wildcard.
| Example | Description |
|---|---|
| / | Matches requests to the root path. |
| /checkout | Matches requests to /checkout |
| /patients/*/report | Matches requests to /patients/1/report, /patients/2/report, etc. |
| /users/** | Matches requests prefixed with /users. e.g /users/1, /users/1/addresses, etc. |
| /** | Matches all requests. |
Selecting Fields
Route actions are only applied to data that matches the list of selected fields defined on an action. Fields can be selected in different ways depending on the type of the request.
JSON
For JSON payloads, you can select fields using JSONPath. JSONPath is a query language for JSON that allows you to select fields by their path in the JSON object.
| Example | Description |
|---|---|
| $.name | Selects the name field. |
| $.address.* | Selects all fields in the address object. |
| $.patients.*.name | Selects the name field in all patient objects. |
| $.patients[?(@.country == 'IE')] | Selects all patient objects where the country field equals IE. |
| $..* | Selects all fields in the JSON object. |
JSON Payloads are supported for requests where the content-type subtype is json. The subtype is the part of the content-type after the /. For example, a content-type of application/json+charset=utf8 has a subtype of json.
Forms
Form fields will be matched directly by name. Form data is only supported for requests with a content-type of application/x-www-form-urlencoded or multipart/form-data.
File Encryption is supported for multipart/form-data requests.
Headers
Headers can be selected by name.
API Key Authentication
API Key Authentication adds an additional layer of security to your Relay. When enabled, requests through Relay will require a valid Evervault API Key to be passed in a X-Evervault-Api-Key header and your App's ID to be passed in a X-Evervault-App-Id header..
You can create API Keys inside of the Evervault Dashboard by navigating to App Settings -> API Keys.
When to use API Key Authentication
We strongly recommend enabling API Key Authentication for any Relay that is configured to decrypt data. However, it may not be necessary when you are working with your own API which has it's own authentication logic. When working with Third-Party API's it is important to use API Key Authentication to ensure that only your application can access the decrypted data.
File Encryption
Relay supports encrypting and decrypting files in multipart/form-data requests. Encrypted files will be forwarded on with an unchanged filename, but the bytes in the file will be fully encrypted. There is currently a per-request limit of 25 MB for encryption/decryption.
Evervault encrypted files begin with the unicode bytes %EVENC. You can use this to validate that files are arriving encrypted.
Custom Domains
By default, Relays are assigned a relay.evervault.app domain. You can also configure additional custom domains for your Relay. You can add a custom domain to your Relay in the Evervault Dashboard by navigating to Relay -> Settings -> Domains.
To add a custom domain, you will need to add a CNAME record to your DNS provider that points to custom-dns.relay.evervault.app.
Additionally, you will provided with an ownership validation TXT record that you must put on the _ev-custom-domain subdomain of your custom domain.
mTLS
Relay lets you upload a client certificate to authenticate with the target server over mTLS. You can upload a client cert for your Relay in the Evervault Dashboard by navigating to Relay -> Authentication. 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.
Service Limits
These limits apply to all requests sent through Relay. Limits can be increased upon request.
| Description | Limit |
|---|---|
| Max Payload Size (JSON, XML) | 5mb |
| Max File Size | 25mb |
| Max Chunked Size (transfer-encoding: chunked) | 700kb |
| Connection Timeout | 120s |
Alerts
Alerts allow you to see errors in Slack or be 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. When you configure a custom webhook to receive alerts, the following fields will be in the response.
Fields
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.
Error Codes
This error indicates you are sending a request to a Relay (e.g my-api-com.relay.evervault.app) 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.