Primitives

Outbound Relay

Outbound Relay Diagram

Outbound Relay is an invisible decryption proxy that lets you share encrypted data with third-party APIs, without the third-party having to decrypt any fields themselves.

Outbound Relay is available in all our server-side SDKs or you can manually specify it as a proxy in your request.

Under the hood, Outbound Relay is an HTTP CONNECT proxy that intercepts requests from your API to specific third-party hostnames, terminates TLS and swaps encrypted data with the original plaintext.

By the time the request reaches the third-party API, all fields are decrypted, and the request will appear as a valid API request for the third-party.


Getting started

Get Started

Encrypt a string in less than 5 minutes with Evervault CEO Shane Curran.

Step 1: Configure the proxy

There are two ways to configure your requests to go through Outbound Relay. The first and most straightforward of these is to include one of our server-side SDKs in your API. Alternatively, if your language of choice is not supported yet, you can still use Outbound Relay by specifying the proxy in your request as shown below using curl.

In this example, we will use RequestBin to generate an testing API that will log all requests, including their payloads. We can create a RequestBin by navigating to requestbin.com/r, where we will be given a temporary URL which we can send requests to.

Using an Evervault SDK

To use Outbound Relay, simply include and initialize the Evervault SDK in your application and enable outbound relay. Outbound Relay can be used in any of our server-side SDKs.

Then, using HTTPS libraries in the language of your choice, we can send a request to the RequestBin, and the Evervault SDK will automatically intercept requests and route them through Outbound Relay.

Note: For this demo we are using the .encrypt method to create some encrypted data. In production, you should avoid ever having plain text reach your server.

Using curl

If your language of choice is not supported yet, you can still use Outbound Relay by specifying the proxy in your request to be https://relay.evervault.com and including your Evervault API key in the Proxy-Authorization header. To configure this in an HTTP client within your code you'll need to set up an HTTP CONNECT proxy over TLS, and trust our CA cert.


You should now see the request appear in the RequestBin logs with the data still encrypted. We can now configure Outbound Relay to decrypt all sensitive data being sent to the RequestBin.

Step 2: Configure endpoints to decrypt

Once you have included the Evervault SDK in your application, Outbound Relay can be enabled for specific domains within the Evervault Dashboard.

Within the Outbound Relay tab in your App, you can specify the hostnames of the APIs you want to send encrypted data to. In this case, we’ll add our RequestBin as an Outbound Relay Destination.

Screenshot of adding an outbound destination

If we run our application and send the request again, we’ll be able to see another request in our RequestBin. This time, the encrypted ssn that we sent from our application was automatically decrypted by Outbound Relay before being passed to the RequestBin.

This flow means you can still interact with any third-party API that requires sensitive data in plaintext, while keeping it encrypted at all times within your application.

What’s next?

Congratulations! You have successfully configured Outbound Relay to share encrypted data with a third-party API without handling it in plaintext.

If you need to process encrypted data using your own code, check out Functions.

Response Encryption

If you would like to encrypt responses from the third-party API before they reach your server (for example, encrypting bank details returned from a payments API), you can specify fields or files to encrypt in the Settings of your Outbound Relay Destination.

File Decryption

Outbound Relay supports decrypting files and text fields in multipart/form-data uploads.

For Response Encryption, Outbound Relay supports encrypting files and text-fields in multipart/form-data uploads. Simply add the names of the relevant fields in your form to your fields to encrypt.

There is currently a per-request limit of 25 MB for encryption/decryption.