You can use our Java SDK to:

Encrypt data server-side
Decrypt data server-side
Invoke Functions
Proxy requests through Outbound Relay

Encrypting/Decrypting data with our backend SDKs instead of Inbound Relay may expose you to greater compliance burden because because your server handles plaintext data.

Instead you can:

Use an Inbound Relay to encrypt data before it reaches your server.
Use an Outbound Relay to decrypt data before it reaches a third-party service.
Use our client-side SDKs to encrypt data before sending it to your server.

Quickstart

Install SDK

First, let's install the Evervault SDK using either gradle or maven.

1
implementation 'com.evervault:lib:4.0.0'

Initialize SDK

Now, let's initialize the SDK using our App's ID and API key. If you don't have one yet, you can get one by creating an App in the Evervault Dashboard.

1
import com.evervault.Evervault;
2
3
var evervault = new Evervault("<APP_ID>", "<API_KEY>");

Encrypt a string

Now that the SDK is initialized, we can encrypt a string.

1
var encrypted = evervault.encrypt("Hello, world!");

Decrypt data

decrypt() will decrypt data previously encrypted with the encrypt() function or through Relay. It will also deserialise the data into an object of a specified type.

The decrypt function requires the type of data is of Map<String, Object>.

1
private static class Bar {
2
    public String name;
3
}
4
5
void encryptAndDecrypt() throws EvervaultException {
6
    var evervault = new Evervault("<APP_ID>", "<API_KEY>");
7
8
    // Encrypt some data
9
    var encryptedName = (String) evervault.encrypt("foo");
10
11
    // Decrypt the previously encrypted data
12
    var dataToDecrypt = new HashMap<String, String>();
13
    dataToDecrypt.put("name", encryptedName);
14
15
    // Decrypts and deserialises the encrypted data into a `Bar` instance
16
    Bar decryptedData = evervault.decrypt(dataToDecrypt, Bar.class);
17
18
    System.out.println(decryptedData.name); // Prints `foo`
19
}

Creating Client Side Decrypt Tokens

Client Side Decrypt Tokens are versatile and short-lived tokens that frontend applications can utilise to decrypt data previously encrypted through Evervault. Client Side Decrypt Tokens are restricted to specific payloads.

By default, a Client Side Decrypt Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future.

1
var encryptedData = evervault.encrypt("foo");
2
Instant timeInFiveMinutes = Instant.now().plus(minutes, ChronoUnit.MINUTES);
3
4
var token = evervault.createClientSideDecryptToken(encryptedData, timeInFiveMinutes);

Full example

Pulling all of this together leaves us with the following working example. You can copy and paste the code below (using a sandbox API key and App ID), run it in your own environment and run the encryption and decryption for yourself.

1
import com.evervault.Evervault;
2
3
var evervault = new Evervault("<APP_ID>", "<API_KEY>");
4
5
var encrypted = evervault.encrypt("Hello, world!");
6
7
System.out.println(encrypted);

Reference

Evervault()

The SDK constructor accepts the following parameters:

Your App's ID
Your App's API key
Optional configuration parameters
- Domain names to route through Outbound Relay
- Whether to enable Outbound Relay and fetch domain configuration from the Evervault API.

Example

1
import com.evervault.Evervault;
2
3
var evervault = new Evervault("<APP_ID>", "<API_KEY>", "prime256v1", ["api.example.com"], true);

Parameters

appIdRequiredString

Your Evervault App's ID.

apiKeyRequiredString

An API key for your Evervault App.

curveString

The elliptic curve used for cryptographic operations.

enableOutboundRelayBoolean, Default: false

Whether to enable Outbound Relay, and automatically intercept requests to Outbound Relay destinations.

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(data)

Encrypts data using Evervault Encryption. Evervault Strings can be used across all of our products.

To encrypt data using the Java SDK, simply pass a string or a map into the evervault.encrypt() function. 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 a 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 a Vector with encrypted strings.

The encrypted data can be stored in your database as normal and can be used with any of Evervault’s other services.

1
import com.evervault.Evervault;
2
3
var evervault = new Evervault("<APP_ID>", "<API_KEY>");
4
5
var result = evervault.encrypt("Hello, world!");

Parameters

The data to encrypt.

evervault.decrypt(data)

Decrypts data previously encrypted using the encrypt() function or through Relay (Evervault's encryption proxy).

An API key with the decrypt permission must be used to perform this operation.

1
private static class Bar {
2
    public String name;
3
}
4
5
void encryptAndDecrypt() throws EvervaultException {
6
    var evervault = new Evervault("<APP_ID>", "<API_KEY>");
7
8
    // Encrypt some data
9
    var encryptedName = (String) evervault.encrypt("foo");
10
11
    // Decrypt the previously encrypted data
12
    var dataToDecrypt = new HashMap<String, String>();
13
    dataToDecrypt.put("name", encryptedName);
14
15
    // Decrypts and deserialises the encrypted data into a `Bar` instance
16
    Bar decryptedData = evervault.decrypt(dataToDecrypt, Bar.class);
17
18
    System.out.println(decryptedData.name); // Prints `foo`
19
}

Parameters

dataRequiredObject

The data to decrypt.

valueTypeRequiredClass<T>

The value type of the data to deserialize into.

Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases

Instead you can:

Use Outbound Relay to decrypt data before it reaches third-party services.
Use Functions or Cages to process encrypted data.

evervault.createClientSideDecryptToken(payload, expiry)

By default, a Client Side Decrypt Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future.

1
var encryptedData = evervault.encrypt("foo");
2
Instant timeInFiveMinutes = Instant.now().plus(minutes, ChronoUnit.MINUTES);
3
4
var token = evervault.createClientSideDecryptToken(encryptedData, timeInFiveMinutes);

Parameters

payloadRequiredObject

The payload containing encrypted data that the token will be used to decrypt.

expiryjava.time.Instant

The time the token will expire. Defaults to 5 minutes in the future.

evervault.run(functionName, data, options)

Lets you invoke an Evervault Function with a given payload.

1
import com.evervault.Evervault;
2
3
var evervault = new Evervault("<APP_ID>", "<API_KEY>");
4
5
var result = evervault.run(
6
    "hello-function",
7
    {
8
        "name": "Claude Shannon",
9
        "ssn": "ev:encrypted_string"
10
    }
11
);

Parameters

functionNameRequiredString

Name of the function the run token is for.

dataRequiredObject

Payload for the function.

optionsObject

Additional options for running the function.

Response

Function runs will return a POJO containing a Function Run ID (public String runId) and the result from your Function (public Object result).

evervault.createRunToken(functionName, data)

Creates a single use, time bound token (5 minutes) for invoking an Evervault Function with a given payload.

Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.

1
import com.evervault.Evervault;
2
3
var evervault = new Evervault("<APP_ID>", "<API_KEY>");
4
5
var runToken = evervault.createRunToken(
6
    "hello-function",
7
    {
8
        "name": "Claude Shannon",
9
        "ssn": "ev:encrypted_string"
10
    }
11
);

Parameters

functionNameRequiredString

Name of the function the run token is for.

payloadObject

Payload that the token can be used with. If not provided, a run token will be created, and the payload will not be validated when the function is executed.

Response

When you create a Run Token, a POJO containing 1 attribute is returned.

1
{
2
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsInZlciI6IjAuMCJ9.eyJhcHBVdWlkIjoiYXBwX2RmZGE3MmUwMTZiMCIsImZ1bmN0aW9uTmFtZSI6ImhlbGxvLWNhZ2UtdGFsbC13YWxscy10cmF2ZWwiLCJydW5JZCI6IjRiMjhmMzNlLWU3NjYtNDI2OC1iNmY2LTUyYzZkM2VmMGQzYyIsImV4cCI6MTY2Nzg3Njc2Nn0.gCiFw7UJ8gjZfeXNEaqX4H1Y9HBX9avjioZ4yDU8PTtmGT4QTzVOhnDV46v_yyXLxpO1BgzoBRpYbLciiW1_QXSLmx6cCuJy4vHUZwssHT13vB7AXIl_88Ab5R7w9vpOQIDoCjhPVWJsolwUiiGh_5yE4wGv6WPTIfSv249_hpJLMz3AAffXUckiLPxFporY73KXtTANQH_zniivB91KdBnyGhle7gTs1EXWLqpdMIrqOz9cmoXU31DGd-AgeMzM082s_XtdCFq7FNLLtg6Nx8Mx8Bjl0cKV41R-jbTpHSXxutLX-PSDmWn5wSqDhlQoEWdTLsoS6xp7qhZ2urYyYg"
3
}

Run Tokens can then be used to authenticate Function runs from the client-side.

bernstein:~$

curl -X POST https://run.evervault.com/hello-function \
		 -H 'Authorization: Bearer eyJ..Tg' \
		 -H 'Content-Type: application/json' \
		 --data '{"name": "Claude Shannon", "ssn": "ev:encrypted_string"}'