toc

Relay

Collect and share sensitive data.

Relay is a proxy for encrypting data before it touches your API, and for decrypting it as you send it to a third-party API or return it to your users. Relay does not encrypt or decrypt data. Relay intercepts the encrypted data and communicates with E3. E3 does all cryptographic operations.

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

Relay has two stages: inbound encryption and outbound decryption.

To configure Inbound Relay:

  1. Create a Relay in the dashboard and provide your API URL.
  2. Point your frontend to the new Relay URL.
  3. Specify fields to encrypt in the Dashboard.

To configure Outbound Relay:

  1. Initialize the Evervault server-side SDK
    1. For Node.js: set relay to true in the initialization settings.
    2. For Python: call the relay() function once. This currently supports requests made using the popular requests package.
    3. For other languages: use http://relay.evervault.com:80 or https://relay.evervault.com:443 as a HTTP CONNECT proxy for requests you wish to Relay. Authorization is performed using HTTP Basic Auth with your team ID as the username and API key as the password.
  2. Send requests to third-party services as normal. Our SDK will automatically route all outbound HTTPS requests through Relay. Encrypted data will be decrypted by Relay before being sent to its destination.

Use Cases

Encrypt sensitive data.

You can use Relay to encrypt sensitive customer and user data. For example:

  • Identity & contact data. Any data that relates to the identity of your users, including addresses, phone numbers, social security numbers, tax numbers, government issued IDs, and biometric information.
  • Financial & transaction data. Bank account information, cardholder data (card number, CVC code, and expiration date), and payments records.
  • Health & medical data. Medical history, biological & genetic data, and healthcare & insurance provider information.
  • Intellectual property (IP) & proprietary data. Sensitive documents, trade secrets, and ML models & datasets.

Interact with APIs.

Encrypt requests and responses when you communicate with third-party APIs. For example:

  • Encrypt & store biometric information and send it to an identity verification API, like Onfido.
  • Encrypt & store phone numbers and send them to a communications API, like Twilio.
  • Encrypt labelled ML training data returned from a data labelling API, like Scale.

Secure your secrets

Encrypt your users' credentials for third-party services using Relay, and authorize with those services by running a headless browser in, or calling an API from, a Cage.

Inbound Relay

Relay can be configured to intercept and encrypt inbound data to your API. By providing us with the URL 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.

All Relay URLs are on the .relay.evervault.com subdomain by default. Custom domains are available on request and can be configured through a simple DNS change.

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 without any visibility over the encrypted data itself.

Inbound 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. You can store Evervault-encrypted data in your database as you would the plaintext version.

Outbound Relay

Relay can be used to pass data to third-party services and APIs using the outbound 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.

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: http://teamID:apiKey@relay.evervault.com:80.

We encourage you to use our CONNECT-over-TLS Relay on supported platforms which is available on https://relay.evervault.com:443. This will ensure that your credentials are never sent over plaintext.

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.

Automatic Relay integration is coming soon to our Python and Ruby SDKs.

Local Relay

During development, you may want to experiment with Relay and send requests to a server running on localhost instead of the public internet. By installing the Evervault CLI and running ev relay local run, a Relay will be created on the .relay.evervault.dev subdomain and will tunnel requests from the internet to your local API.

You can configure which fields to encrypt in the Dashboard or by using the ev relay local set command. Once you are happy with your field configuration, you can deploy the Relay to production by running ev relay publish.