toc

Java SDK

A full reference of our Java SDK.

You can use our Java SDK to:

  1. Encrypt data at your server
  2. Run your Cages
  3. Encrypt/decrypt data with Relay

You can use our Java SDK to encrypt data — rather than with Relay — and still send it to a third-party via Outbound Interception. Encrypting with our backend SDKs is best for developers who want to avoid the network latency of Relay and/or want to avoid sending plaintext data to Relay to be encrypted.

Encrypting data with our backend SDKs instead of Relay may expose you to greater compliance burden because plaintext data touches your server before it is encrypted.

You don’t need to change your database configuration. You can store Evervault-encrypted data in your database as you would the plaintext version.

Installation

Our Java SDK is distributed via maven and can be installed using your preferred build tool.

Gradle

implementation 'com.evervault:lib:3.1.0'

Maven

xml
<dependency>
<groupId>com.evervault</groupId>
<artifactId>lib</artifactId>
<version>3.1.0</version>
</dependency>

Initialization

java
// Import Evervault
import com.evervault.Evervault;
// Initialize the client with your team’s API key
var evervault = new Evervault("<YOUR_API_KEY>");
// Encrypt your data
var encrypted = evervault.encrypt("Claude");
// Process the encrypted data in a Cage
var result = evervault.run("hello-cage", encrypted, false, null);

Relay Interception

The Evervault Java SDK can be used to intercept outbound HTTPS requests for decryption. This can be done by setting up a proxy to Evervault on your HTTP client, and defining the hostnames that you would like to be intercepted using the decryptionDomains parameter when you initialise the SDK.

Only domains present in the decryptionDomains initialisation option are proxied through Relay. Wildcard domains can be specified.

Evervault CA

To allow outbound interception with Relay the Evervault Root Ca certificate must be added to the JVM keystore.

sh
curl https://ca.evervault.com --output evervault-ca.cert
sudo keytool -import -alias evervault-ca -file evervault-ca.cert -keystore <path/to/jdk/cacerts>
Setting up HTTP Client With Proxy

The Apache Closeable HTTP Client requires the proxy and credentials to be explicitly set. When initialising your http client, you will need to get the CredentialsProvider and HttpRoutePlanner from the Evervault SDK, and the host from the Evervault ProxySystemSettings class.

java
// Import ProxySettings for setting proxy host
import com.evervault.utils.ProxySystemSettings;
// Initialise Evervault SDK
var evervault = new Evervault(apiKey, new String[]{'acme.com'})
// Build httpClient with proxy
CloseableHttpClient httpClient = HttpClientBuilder
.create()
.setProxy(ProxySystemSettings.PROXY_HOST)
.setDefaultCredentialsProvider(evervault.getEvervaultProxyCredentials())
.setRoutePlanner(evervault.getEvervaultHttpRoutePlanner())
.build();
We currently only support CONNECT-over-TLS in order to avoid transmitting credentials in plaintext. The Apache Http Client does support this. The core Java Http Clients do NOT currently support this.

Manual Proxy

If you use a different http client to the Apache HTTPClient above and it supports CONNECT-over-TLS, you can setup outbound interception by setting the http client to proxy requests through it with these details:

SettingValue
hoststrict.relay.evervault.com
port443
userYour Evervault Team's UUID (Can be found in the Evervault Dashboard)
passwordYour Evervault Team's API_KEY (Can be found in the Evervault Dashboard)

All traffic that passes through this proxy will be decrypted.

Reference

The Evervault Java SDK exposes a constructor and two functions:

  • evervault.encrypt()
  • evervault.run()

Evervault Constructor

Evervault constructor expects your api key which you can retrieve from evervault website. There are also optional parameters.

java
var evervault = new Evervault(API_KEY);
ParameterTypeDescription
apiKeyStringThe API key of your Evervault Team
curveEvervault.EcdhCurveThe elliptic curve used for cryptographic operations. See Elliptic Curve Support to learn more.
decryptionDomainsString[]Requests sent to any of the domains listed will be proxied through outbound interception. Wildcard domains may be included in this list. See Outbound Interception to learn more.

evervault.encrypt()

encrypt will encrypt your data and return an object which is a String in case you passed a literal type like bool, string, int, float, char, byte.

In case you pass a map<literal, literal> then the key will be preserved and the value will be an encrypted string. If value is another map for example, it will follow the sample principle recursively.

In case you pass a vector with literals the return will be vector with encrypted strings.

java
var name = (String) evervault.encrypt(plaintext_name);
ParameterTypeDescription
dataObjectData to be encrypted.

evervault.run()

evervault.run() lets you invoke a Cage with a given payload.

java
var cageResult = evervault.run(cageName, encryptedData, false, null);
ParameterTypeDescription
cageNameStringName of the Cage to be run.
dataObjectPayload for the Cage.
asyncStringRun your Cage in async mode. Async Cage runs will be queued for processing.
versionObjectSpecify the version of your Cage to run. By default, the latest version will be run.

Was this page useful?