InCountry Java SDK

Installation

InCountry Storage SDK requires Java Developer Kit 1.8 or higher, recommended language level 8.

If you use Maven, please add this section to your dependencies list:

<dependency>
  <groupId>com.incountry</groupId>
  <artifactId>incountry-java-client</artifactId>
  <version>3.1.0</version>
</dependency>

If you use Gradle, please add this line to your dependencies list:

compile "com.incountry:incountry-java-client:3.0.0"

Countries List

To get a full list of supported countries and their codes, please follow this link.

Quick Start Guide

To access your data in InCountry Platform by using Java SDK, you need to create an instance of the Storage class using the getInstance method and pass the StorageConfig object to it. You can retrieve the CLIENT_ID, CLIENT_SECRET and ENV_ID variables on the Environments page of InCountry Portal.

SecretsData secretsData = SecretsDataGenerator.fromPassword("<encryption_secret>");
StorageConfig config = new StorageConfig()
        .setEnvId("<environment_id>")
        .setClientId("client_id")
        .setClientSecret("<client_secret>")
        .setSecretKeyAccessor(() -> secretsData);
Storage storage = StorageImpl.getInstance(config);

Storage Configuration

Below you can find a full list of possible configuration options for creating a Storage instance.

public class StorageImpl implements Storage {
  /**
   * creating Storage instance
   *
   * @param config A container with configuration for Storage initialization
   * @return instance of Storage
   * @throws StorageClientException if configuration validation finished with errors
   */
  public static Storage getInstance(StorageConfig config)
                                    throws StorageClientException, StorageServerException  {...}
//...
}

The StorageConfig class provides the following parameters:

/**
 * container with Storage configuration, using pattern 'builder'
 */
public class StorageConfig {
   //...
   /** Required to be passed in, or as environment variable INC_API_KEY */
   private String envId;
   /** Required when using oAuth authorization, can be also set via INC_CLIENT_ID */
   private String clientId;
   /** Required when using oAuth authorization, can be also set via INC_CLIENT_SECRET */
   private String clientSecret;
   /** Required when using API key authorization, or as environment variable */
   private String apiKey;
   /** Optional. Defines custom API URL, can also be set via INC_ENDPOINT */
   private String endPoint;
   /** Instance of SecretKeyAccessor class. Used to fetch encryption secret */
   private SecretKeyAccessor secretKeyAccessor;
   /** Optional. List of custom encryption configurations */
   private List<Crypto> customEncryptionConfigsList;
   /** Optional. If true - all keys will be stored as lower cased. default is false */
   private boolean normalizeKeys;
   /** Optional. Parameter endpointMask is used for switching from `default` InCountry host
    *  family (-mt-01.api.incountry.io) to a different one.  */
   private String endpointMask;
   /** Optional. Set custom endpoint for loading countries list */
   private String countriesEndpoint;
   /** Optional. Set HTTP requests timeout. Parameter is optional. Should be greater than 0.
    * Default value is 30 seconds. */
   private Integer httpTimeout;
   /** Set custom endpoints regional map to use for fetching oAuth tokens
    * Can be used only with {@link #defaultAuthEndpoint}
    * Format: key = region, value = authorization server URL for region */
   private Map<String, String> authEndpoints;
   /** Set custom oAuth authorization server URL, will be used as default one.
    * Can't be null when {@link #authEndpoints} is used */
   private String defaultAuthEndpoint;
   /** Optional. Set HTTP connections pool size. Expected value - null or positive integer.
    * Defaults to 20. */
   private Integer maxHttpPoolSize;
   /** Optional. Set maximum count of HTTP connections per route.
    * Expected value - null or positive integer.
    * Default value == {@link #maxHttpPoolSize}. */
   private Integer maxHttpConnectionsPerRoute;
   /** Optional. If false - key1-key10 will be not hashed. Default is true */
   private boolean hashSearchKeys = true;
   //...

Below you can find API Key authorization usage example:

SecretsData secretsData = SecretsDataGenerator.fromPassword("<password>");
StorageConfig config = new StorageConfig()
    .setEnvId("<env_id>")
    .setApiKey("<api_key>")
    .setSecretKeyAccessor(() -> secretsData);
Storage storage=StorageImpl.getInstance(config);

oAuth options configuration

The SDK allows to precisely configure oAuth authorization endpoints (if needed). Use this option only if your plan configuration requires so.

Below you can find an example of how to create a storage instance with custom oAuth endpoints:

Map<String, String> authEndpointsMap = new HashMap<>();
authEndpointsMap.put("emea", "https://auth-server-emea.com");
authEndpointsMap.put("apac", "https://auth-server-apac.com");
authEndpointsMap.put("amer", "https://auth-server-amer.com");

StorageConfig config = new StorageConfig()
   .setClientId(CLIENT_ID)
   .setClientSecret(SECRET)
   .setAuthEndpoints(authEndpointsMap)
   .setDefaultAuthEndpoint("https://auth-server-default.com")
   .setEndpointMask(ENDPOINT_MASK)
   .setEnvId(ENV_ID)
Storage storage = StorageImpl.getInstance(config);

StorageConfig config = new StorageConfig()
   .setCountriesEndpoint(countriesEndpoint)
   //...
Storage storage = StorageImpl.getInstance(config);

Encryption key/secret

The SDK provides the SecretKeyAccessor interface which allows you to pass your own secrets/keys to the SDK.

/**
 * Secrets accessor. Method {@link SecretKeyAccessor#getSecretsData()} is invoked
 * on each encryption/decryption.
 */
public interface SecretKeyAccessor {

    /**
     * get your container with secrets
     *
     * @return SecretsData
     * @throws StorageClientException when something goes wrong during getting secrets
     */
    SecretsData getSecretsData() throws StorageClientException;
}


public class SecretsData {
    /**
     * creates a container with secrets
     *
     * @param secrets non-empty list of secrets. One of the secrets must have
     *        same version as currentVersion in SecretsData
     * @param currentVersion Should be a non-negative integer
     * @throws StorageClientException when parameter validation fails
     */
     public SecretsData(List<SecretKey> secrets, int currentVersion)
                throws StorageClientException {...}
    //...
}


public class SecretKey {
    /**
    * Creates a secret key
    *
    * @param secret  secret/key as byte array
    * @param version secret version, should be a non-negative integer
    * @param isKey   should be True only for user-defined encryption keys
    * @throws StorageClientException when parameter validation fails
    */
    public SecretKey(byte[] secret, int version, boolean isKey)
              throws StorageClientException {...}
    //...
}

You can implement the SecretKeyAccessor interface and pass secrets/keys in multiple ways:

1. As a constant SecretsData object:

   SecretsData secretsData = new SecretsData(secretsList, currentVersion);
   SecretKeyAccessor accessor = () -> secretsData;
   

2. As a function that dynamically fetches secrets:

   SecretKeyAccessor accessor = () -> loadSecretsData();
   
   private SecretsData loadSecretsData()  {
      String url = "<your_secret_url>";
      String responseJson = loadFromUrl(url).asJson();
      return SecretsDataGenerator.fromJson(responseJson);
   }
   

You can also use the SecretsDataGenerator class to create SecretsData instances:

1. from a String password:

   SecretsData secretsData = SecretsDataGenerator.fromPassword("<password>");
   

2. from a JSON string representing the SecretsData object:

   SecretsData secretsData = SecretsDataGenerator.fromJson(jsonString);
   

{
    "secrets": [
        {
            "secret": "secret0",
            "version": 0,
            "isKey": false
        },
        {
            "secret": "secret1",
            "version": 1,
            "isKey": false
        }
    ],
    "currentVersion": 1
}

The SecretsData object allows you to specify multiple keys/secrets which SDK will use for decryption based on the version of the key or secret used for encryption.

Meanwhile the SDK will encrypt data only by using a key (or secret) that matches the currentVersion parameter provided in SecretsData object. This enables the flexibility required to support Key Rotation policies when secrets/keys must be changed over time.

The SDK will encrypt data by using the current secret/key while maintaining the ability to decrypt records encrypted with older keys/secrets. The SDK also provides a method for data migration which allows you to re-encrypt data with the newest key/secret. For details, please see the migrate method.

The SDK allows you to use custom encryption keys, instead of secrets.

Usage

Here you can find all the methods available within InCountry Java SDK.

Writing data to Storage

You can use the write method to create or replace a record.

public interface Storage {
    /**
     * Write data to remote storage
     *
     * @param country country identifier
     * @param record  object which encapsulate data which must be written in storage
     * @return recorded record
     * @throws StorageClientException if validation finished with errors
     * @throws StorageServerException if server connection failed or server response error
     * @throws StorageCryptoException if encryption failed
     */
    Record write(String country, Record record)
          throws StorageClientException, StorageServerException, StorageCryptoException;
    //...
}

Below you can find an example of how to initialize a record object:

public class Record {
   /**
    * Minimalistic constructor
    *
    * @param recordKey record key
    */
    public Record(String recordKey) {...};

   /**
    * Overloaded constructor
    *
    * @param recordKey record key
    * @param body      data to be stored and encrypted
    */
    public Record(String recordKey, String body) {...}
    //...
}

Below you can find an example of how to write a record:

Record record = new Record("some_key")
    .setBody("some PII data")
    .setProfileKey("customer")
    .setKey1("hatchback")
    .setKey2("english")
    .setKey3("insurance")
    .setRangeKey1(10_000L)
storage.write("us", record);

List of available record fields

Release of Java SDK 3.X has introduced a series of new fields available for data storage. Below you can find a full list of all the supported data fields in InCountry Platform along with their types and storage methods. Each field is either encrypted, hashed or stored, as follows:

public class Record {
    //String fields, hashed
    private String recordKey;
    private String key1;
    private String key2;
    private String key3;
    private String key4;
    private String key5;
    private String key6;
    private String key7;
    private String key8;
    private String key9;
    private String key10;
    private String profileKey;
    private String serviceKey1;
    private String serviceKey2;
    //String fields, encrypted
    private String body;
    private String precommitBody;
    //Long fields, plain
    private Long rangeKey1;
    private Long rangeKey2;
    private Long rangeKey3;
    private Long rangeKey4;
    private Long rangeKey5;
    private Long rangeKey6;
    private Long rangeKey7;
    private Long rangeKey8;
    private Long rangeKey9;
    private Long rangeKey10;
    //Readonly service fields, date in ISO format
    protected Date createdAt;
    protected Date updatedAt;

You can access all the properties by using the appropriate getters and setters, for example:

String key2 = record.getKey2();
String body = record.getBody();

record.setProfileKey("customer")
    .setRangeKey1(1_000L)
    .setKey3("grey");

Date fields

You can use the createdAt and updatedAt fields to access the date-related information about records. ThecreatedAt field stores date when the record was initially created in the target country. The updatedAt fields stores the date of the latest write operation for the given recordKey.

Writing multiple records

You can use the batchWrite method to create or replace multiple records at once.

public interface Storage {
     /**
      * Write multiple records at once in remote storage
      *
      * @param country country identifier
      * @param records record list
      * @return BatchRecord object which contains list of recorded records
      * @throws StorageClientException if validation finished with errors
      * @throws StorageServerException if server connection failed or server response error
      * @throws StorageCryptoException if record encryption failed
      */
     BatchRecord batchWrite(String country, List<Record> records)
          throws StorageClientException, StorageServerException, StorageCryptoException;
     //...
}

Below you can find an example of how to write multiple records:

List<Record> list = new ArrayList<>();
list.add(new Record("some_record_key","some PII data"));
list.add(new Record("another_record_key","another PII data"));
storage.batchWrite("us", list);

Reading stored data

You can read the stored data records by their recordKey with the readmethod.

public interface Storage {
   /**
    * Read data from remote storage
    *
    * @param country   country identifier
    * @param recordKey record unique identifier
    * @return Record object which contains required data
    * @throws StorageClientException if validation finished with errors
    * @throws StorageServerException if server connection failed or server response error
    * @throws StorageCryptoException if decryption failed
    */
    Record read(String country, String recordKey)
        throws StorageClientException, StorageServerException, StorageCryptoException;
    //...
}

Below you can find an example of how to read a record:

String recordKey = "user_1";
Record record = storage.read("us", recordKey);
String decryptedBody = record.getBody();

Searching for records

You can look up for data records by random keys with the find method.

public interface Storage {
   /**
    * Find records in remote storage according to filters
    *
    * @param country country identifier
    * @param builder object representing find filters and search options
    * @return BatchRecord object which contains required records
    * @throws StorageClientException if validation finished with errors
    * @throws StorageServerException if server connection failed or server response error
    * @throws StorageCryptoException if decryption failed
    */
    BatchRecord find(String country, FindFilterBuilder builder)
         throws StorageClientException, StorageServerException, StorageCryptoException;
    //...
}

Use FindFilterBuilder class to configure your find request.

Below you can find an example of how to use find method along with FindFilterBuilder:

FindFilterBuilder builder = FindFilterBuilder.create()
                  .keyEq(StringField.KEY2, "someKey")
                  .keyEq(StringField.KEY3, "firstValue", "secondValue")
                  .keyEq(NumberField.RANGE_KEY1, 123L, 456L);

BatchRecord findResult = storage.find("us", builder);
if (findResult.getCount() > 0) {
    Record record = findResult.getRecords().get(0);
    //...
}

This request will return records filtered according to the following pseudo-SQL pattern:

key2 = 'someKey' AND key3 in ('firstValue' , 'secondValue') AND (123 < = `rangeKey1` < = 456)

All the conditions added with FindFilterBuilder are joined by using a logical AND operator. If you add multiple conditions for the same key, only the last condition will be used and all the prior conditions will be ignored.

You can use the limit and offset options to iterate through the list of records.

FindFilterBuilder builder = FindFilterBuilder.create()
                  //...
                  .limitAndOffset(20, 80);
BatchRecord records = storage.find("us", builder);

The following predicate types are available for each string key field of the Record class through individual methods of FindFilterBuilder:

EQUALS         (FindFilterBuilder::keyEq)
NOT_EQUALS     (FindFilterBuilder::keyNotEq)

You can use the following methods of the builder for filtering records by numerical fields:

EQUALS              (FindFilterBuilder::keyEq)
IN                  (FindFilterBuilder::keyIn)
GREATER             (FindFilterBuilder::keyGT)
GREATER OR EQUALS   (FindFilterBuilder::keyGTE)
LESS                (FindFilterBuilder::keyLT)
LESS OR EQUALS      (FindFilterBuilder::keyLTE)
BETWEEN             (FindFilterBuilder::keyBetween)

The find method returns the BatchRecord object which contains a list of Record and some metadata:

class BatchRecord {
    private int count;
    private int limit;
    private int offset;
    private int total;
    private List<Record> records;
    //...
}

You can access these fields by using getters, for example:

int limit = records.getTotal();

The BatchRecord.getErrors() function allows you to get a List of RecordException objects which contains detailed information about records were not processed correctly during execution of the find request.

Searching for one record matching a filter

You can use the findOne method when you need to find only the first record matching a specific filter from a set of records.

public interface Storage {
   /**
    * Find only one first record in remote storage according to filters
    *
    * @param country country identifier
    * @param builder object representing find filters
    * @return founded record or null
    * @throws StorageClientException if validation finished with errors
    * @throws StorageServerException if server connection failed or server response error
    * @throws StorageCryptoException if decryption failed
    */
    Record findOne(String country, FindFilterBuilder builder)
           throws StorageClientException, StorageServerException, StorageCryptoException;
    //...
}

It works the same way as the find method but returns the first record or null if no records are found.

Below you can find an example of how to search for one specific record:

FindFilterBuilder builder = FindFilterBuilder.create()
                  .keyEq(StringField.KEY2, "someKey")
                  .keyEq(StringField.KEY3, "firstValue", "secondValue")
                  .keyEq(NumberField.RANGE_KEY1, 123L, 456L);

Record record = storage.findOne("us", builder);
//...

Deleting records

You can use the delete method to delete a record by its key field from InCountry Platform.

public interface Storage {
    /**
    * Delete record from remote storage
    *
    * @param country   country code of the record
    * @param recordKey the record's key
    * @return true when record was deleted
    * @throws StorageClientException if validation finished with errors
    * @throws StorageServerException if server connection failed
    */
    boolean delete(String country, String recordKey)
            throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to delete a record:

String recordKey = "user_1";
storage.delete("us", recordKey);

Attaching files to a record

InCountry Storage allows you to attach files to the previously created records. Attachments' meta information is available through the attachments field of the Record object.

public class Record {
    /** ... other fields ...  */
    private List<AttachmentMeta> attachments;
}

public class AttachmentMeta {
    private Date createdAt;
    private Date updatedAt;
    private String downloadLink;
    private String fileId;
    private String filename;
    private String hash;
    private String mimeType;
    private int size;
    //...
}

Adding attachments

You can use the addAttachment method of the Storage instance to add or replace attachments. File data can be provided as InputStream.

public interface Storage {
    /**
     * Add attached file to existing record
     *
     * @param country         country identifier
     * @param recordKey       the record's recordKey
     * @param fileInputStream input data stream
     * @param fileName        file name
     * @param upsert          if true will overwrite existing file with the same name.
     *                        Otherwise will throw exception
     * @param mimeType        mime type for attached file
     * @return AttachmentMeta attachment meta information: fileId, mimeType, size, etc.
     * @throws StorageClientException if validation finished with errors
     * @throws StorageServerException if server connection failed or server response error
     */
    AttachmentMeta addAttachment(String country, String recordKey, InputStream fileInputStream,
                                 String fileName, boolean upsert, String mimeType)
             throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to upload a file:

File initialFile = new File("example.txt");
InputStream stream = new FileInputStream(initialFile);
storage.addAttachment(COUNTRY, RECORD_KEY, stream, "example.txt", false, MIME_TYPE);

Deleting attachments

The deleteAttachment method of Storage instance allows you to delete attachment using its fileId.

public interface Storage {
    /**
     * Delete attached file of existing record
     *
     * @param country   country identifier
     * @param recordKey the record's recordKey
     * @param fileId    file identifier
     * @return true when file was deleted
     * @throws StorageClientException if validation finished with errors
     * @throws StorageServerException if server connection failed or server response error
     */
    boolean deleteAttachment(String country, String recordKey, String fileId)
            throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to delete an attachment:

storage.deleteAttachment(COUNTRY, RECORD_KEY, fileId);

Downloading attachments

You can use the getAttachmentFile method of the Storage instance to download the attachment content. It returns the AttachedFile class instance with a readable stream and a file name.

public interface Storage {
    /**
     * Get attached file of existing record
     *
     * @param country   country identifier
     * @param recordKey the record's recordKey
     * @param fileId    file identifier
     * @return AttachedFile object which contains required file
     * @throws StorageClientException if validation finished with errors
     * @throws StorageServerException if server connection failed or server response error
     */
    AttachedFile getAttachmentFile(String country, String recordKey, String fileId)
            throws StorageClientException, StorageServerException;
    //...
}

public class AttachedFile {
   private final InputStream fileContent;
   private final String fileName;
   //...
}

Below you can find an example of how to download an attachment:

AttachedFile attachement = storageForAttachment.getAttachmentFile(COUNTRY, RECORD_KEY, fileId);
File file = new File(attachement.getFileName());
FileUtils.copyInputStreamToFile(attachement.getFileContent(), file);

Working with attachment metadata

Here you can see the available methods to manage attachment metadata.

Getting attachment metadata

You can use the getAttachmentMeta method of the Storage instance to retrieve attachment's metadata by its fileId.

public interface Storage {
    /**
     * Get attached file meta information
     *
     * @param country   country identifier
     * @param recordKey the record's recordKey
     * @param fileId    file identifier
     * @return AttachmentMeta object which contains required meta information fileId,
     * mimeType, size, filename, downloadLink, updatedAt and createdAt
     * @throws StorageClientException if validation finished with errors
     * @throws StorageServerException if server connection failed or server response error
     */
    AttachmentMeta getAttachmentMeta(String country, String recordKey, String fileId)
            throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to fetch the attachment metadata:

AttachmentMeta meta = storageForAttachment.getAttachmentMeta(COUNTRY, RECORD_KEY, fileId);

Updating attachment metadata

You can use the updateAttachmentMeta method of the Storage instance to update attachment's metadata (MIME type and file name).

public interface Storage {
    /**
     * Update attached file meta information
     *
     * @param country   country identifier
     * @param recordKey the record's recordKey
     * @param fileId    file identifier
     * @param fileName  file name (optional if mimeType provided)
     * @param mimeType  file MIME type (optional if fileName provided)
     * @return AttachmentMeta object which contains updated fields
     * @throws StorageClientException if validation finished with errors
     * @throws StorageServerException if server connection failed or server response error
     */
    AttachmentMeta updateAttachmentMeta(String country, String recordKey, String fileId,
                                        String fileName, String mimeType)
            throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to update the attachment metadata:

AttachmentMeta meta = storage
        .updateAttachmentMeta(COUNTRY, RECORD_KEY, fileId, NEW_FILE_NAME, NEW_MIME_TYPE);

Data Migration and Key Rotation support

The using of the SecretKeyAccessor class provides the SecretsData object which enables key rotation and data migration support.

You can use the migrate method to re-encrypt data encrypted with older versions of the secret.

public interface Storage {
   /**
    * Make batched key-rotation-migration of records
    *
    * @param country country identifier
    * @param limit   batch-limit parameter
    * @return MigrateResult object which contain total records
    *         left to migrate and total amount of migrated records
    * @throws StorageClientException if validation finished with errors
    * @throws StorageServerException if server connection failed or server response error
    * @throws StorageCryptoException if decryption failed
    */
    MigrateResult migrate(String country, int limit)
           throws StorageClientException, StorageServerException, StorageCryptoException;
    //...
}

You should specify the country parameter which defines the country you want to perform migration in and the limit parameter which defines an exact number of records to migrate. The migrate method returns the MigrateResult object which contains some information about the migration, as follows:

1. number of migrated records (migrated) .

2. number of records left to migrate (totalLeft). Basically, this means the number of records with versions different from currentVersion provided by the SecretKeyAccessor class instance.

public class MigrateResult {
    private int migrated;
    private int totalLeft;
    //...
}

For detailed example of a migration usage please follow this link.

Error Handling

InCountry Java SDK may throw the following exceptions:

• StorageClientException is used for various input validation errors.

• StorageServerException is thrown when SDK fails to communicate with InCountry servers or if a server response validation fails.

• StorageCryptoException is thrown during encryption/decryption procedures (both default and custom). This may be an inidication of malformed/corrupted data or a wrong encryption key provided to the SDK.

• StorageException is a general exception. Inherited by all other exceptions

We strongly recommend you to gracefully handle all the possible exceptions, as follows:

public void test() {
    try {
        // use InCountry Storage instance here
    } catch (StorageClientException e) {
        // some input validation error
    } catch (StorageServerException e) {
        // some server error
    } catch (StorageCryptoException e) {
        // some encryption error
    } catch (StorageException e) {
        // general error
    } catch (Exception e) {
        // something else happened not related to InCountry SDK
    }
}

Custom Encryption Support

Java SDK supports the usage of custom encryption/decryption methods if you decide to use your own algorithm instead of the default one.

You can use the setCustomEncryptionConfigsList method of the StorageConfig class for passing a list of custom encryption implementations, as follows:

public class StorageConfig {
  //...
  /**
   * for custom encryption
   *
   * @param customEncryptionConfigsList List with custom encryption functions
   * @return StorageConfig
   */
  public StorageConfig setCustomEncryptionConfigsList(List<Crypto> customEncryptionConfigsList) {
      this.customEncryptionConfigsList = customEncryptionConfigsList;
      return this;
  }
  //...
}

To use a custom encryption, you need to implement the following interface:

public interface Crypto {
    /**
     * encrypts data with secret
     *
     * @param text      data for encryption
     * @param secretKey secret
     * @return encrypted data as String
     * @throws StorageClientException when parameters validation fails
     * @throws StorageCryptoException when decryption fails
     */
    String encrypt(String text, SecretKey secretKey)
            throws StorageClientException, StorageCryptoException;

    /**
     * decrypts data with Secret
     *
     * @param cipherText encrypted data
     * @param secretKey  secret
     * @return decrypted data as String
     * @throws StorageClientException when parameters validation fails
     * @throws StorageCryptoException when decryption fails
     */
    String decrypt(String cipherText, SecretKey secretKey)
            throws StorageClientException, StorageCryptoException;

    /**
     * version of encryption algorithm as String
     *
     * @return version
     */
    String getVersion();

    /**
     * only one CustomCrypto can be current. This parameter
     * used only during {@link com.incountry.residence.sdk.Storage}
     * initialisation. Changing this parameter will be ignored after initialization
     *
     * @return is current or not
     */
    boolean isCurrent();
}

public class SecretKey {
    /**
     * @param secret secret/key as byte array
     * @param version secret version, should be a non-negative integer
     * @param isKey should be True only for user-defined encryption keys
     * @param isForCustomEncryption should be True for using this key in custom encryption
     *                              implementations. Either ({@link #isKey} or
     *                              {@link #isForCustomEncryption}) can be True at the same
     *                              moment, not both
     * @throws StorageClientException when parameter validation fails
     */
    public SecretKey(byte[] secret, int version, boolean isKey, boolean isForCustomEncryption)
              throws StorageClientException {...}
    //...
}

You can set the isForCustomEncryption attribute with the SecretsData object in JSON format, as follows:

secrets_data = {
  "secrets": [{
     "secret": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwQUI=", //base64-encoded key (32 byte key)
     "version": 1,
     "isForCustomEncryption": true,
    }
  }],
  "currentVersion": 1,
}

The version attribute is used to differentiate custom encryptions from each other and from the default encryption as well. This way SDK will be able to successfully decrypt any old data if encryption changes over time.

The isCurrent attribute allows you to specify one of the custom encryption implementations that will be used for encryption. Only one implementation can be set as isCurrent() == true.

If none of the configurations have the isCurrent() == true attribute then the SDK will use the default encryption configuration to encrypt stored data. At the same time it will preserve the ability to decrypt old data which was encrypted with custom encryption configurations (if any).

Below you can find an example of how you can set up the SDK to use custom encryption (using Fernet encryption from https://github.com/l0s/fernet-java8 ).

/**
 * Example of custom implementation of {@link Crypto} using Fernet algorithm
 */
public class FernetCrypto implements Crypto {
    private static final String VERSION = "fernet custom encryption";
    private boolean current;
    private Validator<String> validator;

    public FernetCrypto(boolean current) {
        this.current = current;
        this.validator = new StringValidator() {
        };
    }

    @Override
    public String encrypt(String text, SecretKey secretKey)
            throws StorageCryptoException {
        try {
            Key key = new Key(secretKey.getSecret());
            Token result = Token.generate(key, text);
            return result.serialise();
        } catch (IllegalStateException ex) {
            throw new StorageCryptoException("Encryption error", ex);
        }
    }

    @Override
    public String decrypt(String cipherText, SecretKey secretKey)
            throws StorageCryptoException {
        try {
            Key key = new Key(secretKey.getSecret());
            Token result = Token.fromString(cipherText);
            return result.validateAndDecrypt(key, validator);
        } catch (PayloadValidationException ex) {
            throw new StorageCryptoException("Decryption error", ex);
        }
    }

    @Override
    public String getVersion() {
        return VERSION;
    }

    @Override
    public boolean isCurrent() {
        return current;
    }
}

Project dependencies

Below you can find a list of dependencies for compiling and running this project.

GroupId	ArtifactId	Version	Type
javax.xml.bind	jaxb-api	2.3.1	jar
javax.activation	javax.activation-api	1.2.0	jar
commons-codec	commons-codec	1.15	jar
commons-logging	commons-logging	1.2	jar
commons-io	commons-io	2.8.0	jar
org.apache.logging.log4j	log4j-api	2.14.0	jar
org.apache.logging.log4j	log4j-core	2.14.0	jar
org.apache.logging.log4j	log4j-core-jcl	2.14.0	jar
org.apache.httpcomponents	httpclient	4.5.13	jar
org.apache.httpcomponents	httpcore	4.4.13	jar
com.google.code.gson	gson	2.8.6	jar

Dependency Tree

compileClasspath
+--- javax.xml.bind:jaxb-api:2.3.1
|    \--- javax.activation:javax.activation-api:1.2.0
+--- commons-codec:commons-codec:1.15
+--- com.google.code.gson:gson:2.8.6
+--- org.apache.logging.log4j:log4j-api:2.14.0
+--- org.apache.logging.log4j:log4j-core:2.14.0
|    \--- org.apache.logging.log4j:log4j-api:2.14.0
+--- org.apache.logging.log4j:log4j-jcl:2.14.0
|    +--- commons-logging:commons-logging:1.2
|    \--- org.apache.logging.log4j:log4j-api:2.14.0
+--- org.apache.httpcomponents:httpclient:4.5.13
|    +--- org.apache.httpcomponents:httpcore:4.4.13
|    +--- commons-logging:commons-logging:1.2
|    \--- commons-codec:commons-codec:1.11 -> 1.15
+--- commons-io:commons-io:2.8.0
\--- org.apache.httpcomponents:httpmime:4.5.13
     \--- org.apache.httpcomponents:httpclient:4.5.13 (*)

Minimal JVM memory options

-Xms8m
-Xmx16m
-XX:MaxMetaspaceSize=32m