Java

Getting started

The SDK has two ways to load your App's encryption key. Choose one before you start, since encryption works the same way after the SDK is initialized.

• API key (recommended): the SDK fetches the encryption key from the Evervault API at runtime, so there's no key material to manage. This is the default, and the steps below use it.
• Offline JSON Web Key Set (JWK Set): for isolated networks with no route to the Evervault API, initialize the SDK with a key you supply instead. See Encrypt without network access.

Install the SDK

First, let's install the Evervault SDK using either Gradle or Maven.

1implementation 'com.evervault:lib:4.3.1'

Initialize the 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.

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

The SDK fetches your App's encryption key from the Evervault API when it initializes. To initialize it without network access instead, see Encrypt without network access.

Encrypt a string

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

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

Encrypt without network access

Initializing the SDK with an API key is the recommended approach for every environment that can reach the Evervault API. The exception is an isolated network with no route to the public internet, such as a cardholder data environment. In those scenarios, the SDK can't fetch your App's encryption key when it starts, so you need to supply it with a key instead. To do this, download your App's public keys as a JWK Set from https://keys.evervault.com/<TEAM_UUID>/apps/<APP_ID>?format=jwks. Ship that document alongside your application and build the client from it.

1import com.evervault.Evervault;
2import com.evervault.models.EvervaultKey;
3
4EvervaultKey key = EvervaultKey.fromJwks(jwks, "<KID>");
5
6Evervault evervault = Evervault.withKey("<APP_ID>", key);

Building a client this way encrypts without making any network calls, and comes with some trade-offs:

• You're responsible for storing the JWK Set and keeping it in sync with your App.
• Encryption is the only operation that works without network access. Decrypting, running Functions, and using Outbound Relay still call the Evervault API and need an API key.

See Evervault.withKey() and EvervaultKey.fromJwks() for the full set of overloads.

Reference

Evervault()

The SDK constructor takes two parameters; your App's ID and API key.

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

Evervault.withKey()

Builds a client that encrypts with a key you supply, rather than one fetched from the Evervault API. Read the key out of your App's JWK Set with EvervaultKey.fromJwks().

1import com.evervault.Evervault;
2import com.evervault.models.EvervaultKey;
3
4EvervaultKey key = EvervaultKey.fromJwks(jwks, "<KID>");
5
6Evervault evervault = Evervault.withKey("<APP_ID>", key);

The client encrypts on the curve of the key it was given, so the kid you pick also decides the curve. Supplying an API key lets the same client decrypt and run Functions. Adding a Team UUID sets up Outbound Relay credentials without calling the Evervault API.

1Evervault evervault = Evervault.withKey("<APP_ID>", "<API_KEY>", key, "<TEAM_UUID>");

EvervaultKey.fromJwks()

Reads a public key out of a JWK Set so that Evervault.withKey() can encrypt with it. Pass the kid of the key you want, since a set can hold a key for each curve the SDK supports.

1EvervaultKey key = EvervaultKey.fromJwks(jwks, "<KID>");

Call it without a kid when the set holds exactly one key. That overload is also the only way to read a key that carries no kid of its own.

1EvervaultKey key = EvervaultKey.fromJwks(jwks);

Either form throws an EvervaultException if the JWK Set is malformed, or if no key matches the kid. It also throws an exception if the key describes a point that isn't on its stated curve. The message lists the key IDs in the set.

encrypt()

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 value 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.

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

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

decrypt()

Decrypts the data previously encrypted with the encrypt() function or through Relay. An API key with the decrypt permission must be used to perform this operation.

1private static class Bar {
2    public String name;
3}
4
5void encryptAndDecrypt() throws EvervaultException {
6    Evervault evervault = new Evervault("<APP_ID>", "<API_KEY>");
7
8    // Encrypt some data
9    String encryptedName = (String) evervault.encrypt("foo");
10
11    // Decrypt the previously encrypted data
12    Map<String, String> 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}

createClientSideDecryptToken()

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.

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

run()

Lets you invoke an Evervault Function with a given payload. The function result will be deserialized into an instance of responseType and will be returned.

1void runFunction() throws EvervaultException {
2    Evervault evervault = new Evervault("<APP_ID>", "<API_KEY>");
3
4    // Encrypt some data
5    String encryptedSsn = (String) evervault.encrypt("478-32-9183");
6
7    // Create the function payload
8    Map<String, String> functionPayload = new HashMap<String, String>();
9    functionPayload.put("ssn", encryptedSsn);
10
11    // Deserializes the function response into a `Result` instance
12    Result result = evervault.run("ssn-validation-function", functionPayload, Result.class);
13    System.out.println("Validation result": + result.isValid);
14}
15
16public class Result {
17    public boolean isValid;
18}

createRunToken()

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.

1import com.evervault.Evervault;
2
3Evervault evervault = new Evervault("<APP_ID>", "<API_KEY>");
4
5Map<String, String> payload = new HashMap<String, String>();
6payload.put("ssn", "ev:encrypted_string")
7
8RunToken runToken = evervault.createRunToken(
9    "hello-function",
10    payload
11);

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

1fetch("https://api.evervault.com/functions/[function-name]/runs", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: `RunToken [run-token]`,
6  },
7  body: JSON.stringify({
8    payload: {
9      ssn: "encrypted_string",
10    },
11  }),
12});