Package com.ironcorelabs.tenantsecurity.kms.v1

Class DeterministicTenantSecurityClient

java.lang.Object
com.ironcorelabs.tenantsecurity.kms.v1.DeterministicTenantSecurityClient
All Implemented Interfaces:
Closeable, AutoCloseable
public final class DeterministicTenantSecurityClient extends Object implements Closeable
DeterministicTenantSecurityClient class that can be used to deterministically encrypt and decrypt fields.
Author:
IronCore Labs

  • Field Details

    • DEFAULT_REQUEST_THREADPOOL_SIZE

      public static int DEFAULT_REQUEST_THREADPOOL_SIZE
      Default size of web request thread pool. Defaults to 25.

    • DEFAULT_AES_THREADPOOL_SIZE

      public static int DEFAULT_AES_THREADPOOL_SIZE
      Default size of the threadpool used for AES encryptions/decryptions. Defaults to the number of cores on the machine being run on.

    • DEFAULT_TIMEOUT_MS

      public static int DEFAULT_TIMEOUT_MS
      Default timeout in ms for the connection to the TSP.

  • Constructor Details

    • DeterministicTenantSecurityClient

      public DeterministicTenantSecurityClient(String tspDomain, String apiKey) throws Exception
      Constructor for DeterministicTenantSecurityClient class with default values.
      Parameters:
      tspDomain - Domain where the Tenant Security Proxy is running.
      apiKey - Key to use for requests to the Tenant Security Proxy.
      Throws:
      Exception - If the provided domain is invalid.

    • DeterministicTenantSecurityClient

      public DeterministicTenantSecurityClient(String tspDomain, String apiKey, int requestThreadSize, int aesThreadSize) throws Exception
      Constructor for DeterministicTenantSecurityClient class that allows for modifying the random number generator used for encryption. Sets a default connect and read timeout of 20s.
      Parameters:
      tspDomain - Domain where the Tenant Security Proxy is running.
      apiKey - Key to use for requests to the Tenant Security Proxy.
      requestThreadSize - Number of threads to use for fixed-size web request thread pool
      aesThreadSize - Number of threads to use for fixed-size AES operations threadpool
      Throws:
      Exception - If the provided domain is invalid.

    • DeterministicTenantSecurityClient

      public DeterministicTenantSecurityClient(String tspDomain, String apiKey, int requestThreadSize, int aesThreadSize, int timeout) throws Exception
      Constructor for DeterministicTenantSecurityClient class that allows for modifying the random number generator used for encryption.
      Parameters:
      tspDomain - Domain where the Tenant Security Proxy is running.
      apiKey - Key to use for requests to the Tenant Security Proxy.
      requestThreadSize - Number of threads to use for fixed-size web request thread pool
      aesThreadSize - Number of threads to use for fixed-size AES operations threadpool
      timeout - Request to TSP read and connect timeout in ms.
      Throws:
      Exception - If the provided domain is invalid.

  • Method Details

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • create

      public static CompletableFuture<DeterministicTenantSecurityClient> create(String tspDomain, String apiKey)
      Utility method to create a new client instance which returns a CompletableFuture to help handle error situations which can occur on class construction.
      Parameters:
      tspDomain - Domain where the Tenant Security Proxy is running.
      apiKey - Key to use for requests to the Tenant Security Proxy.
      Returns:
      CompletableFuture that resolves in a instance of the DeterministicTenantSecurityClient class.

    • encryptField

      public CompletableFuture<DeterministicEncryptedField> encryptField(DeterministicPlaintextField field, FieldMetadata metadata)
      Deterministically encrypt the provided field using the tenant's current secret.
      Parameters:
      field - Field to deterministically encrypt.
      metadata - Metadata about the field being encrypted.
      Returns:
      DeterministicEncryptedField which contains the field's paths and encrypted data.

    • encryptFieldBatch

      public CompletableFuture<BatchResult<DeterministicEncryptedField>> encryptFieldBatch(Map<String,DeterministicPlaintextField> fields, FieldMetadata metadata)
      Deterministically encrypt a batch of new fields using the tenant's primary KMS. Supports partial failure and returns a list of fields that were successfully encrypted as well as a list of errors for fields that failed to be encrypted.
      Parameters:
      fields - Map of field ID to plaintext field to be deterministically encrypted.
      metadata - Metadata about the fields being encrypted.
      Returns:
      Collection of successes and failures that occurred during operation. The keys of each map returned will be the same keys provided in the original fields map.

    • decryptField

      public CompletableFuture<DeterministicPlaintextField> decryptField(DeterministicEncryptedField field, FieldMetadata metadata)
      Decrypt the provided deterministically encrypted field.
      Parameters:
      field - Deterministically encrypted data to decrypt.
      metadata - Metadata about the field being decrypted.
      Returns:
      DeterministicPlaintextField which contains the field's paths and decrypted data.

    • decryptFieldBatch

      public CompletableFuture<BatchResult<DeterministicPlaintextField>> decryptFieldBatch(Map<String,DeterministicEncryptedField> fields, FieldMetadata metadata)
      Deterministically decrypt a batch of fields using the tenant's KMS that was used for encryption. Supports partial failure and will return both successfully decrypted fields as well as fields that failed to be decrypted.
      Parameters:
      fields - Map of field ID to deterministically encrypted field to be decrypted.
      metadata - Metadata about the fields being decrypted.
      Returns:
      Collection of successes and failures that occurred during operation. The keys of each map returned will be the same keys provided in the original fields map.

    • rotateField

      public CompletableFuture<DeterministicEncryptedField> rotateField(DeterministicEncryptedField field, FieldMetadata metadata)
      Decrypt the provided deterministically encrypted field and re-encrypt it with the current tenant secret. This should be called when rotating from one tenant secret to another.
      Parameters:
      field - Deterministically encrypted data to rotate to the current tenant secret.
      metadata - Metadata about the field being rotated.
      Returns:
      DeterministicEncryptedField encrypted using the tenant's current secret.

    • rotateFieldBatch

      public CompletableFuture<BatchResult<DeterministicEncryptedField>> rotateFieldBatch(Map<String,DeterministicEncryptedField> fields, FieldMetadata metadata)
      Determinally decrypt a batch of fields using the tenant's KMS that was used for encryption, then re-encrypt them with the current tenant secret. Supports partial failure and will return both successfully re-encrypted fields as well as fields that failed to be re-encrypted.
      Parameters:
      fields - Map of field ID to deterministically encrypted field to be rotated.
      metadata - Metadata about the fields being rotates.
      Returns:
      Collection of successes and failures that occurred during operation. The keys of each map returned will be the same keys provided in the original fields map.

    • generateSearchTerms

      public CompletableFuture<DeterministicEncryptedField[]> generateSearchTerms(DeterministicPlaintextField field, FieldMetadata metadata)
      Deterministically encrypt the provided field with all current and in-rotation secrets for the tenant. All of the resulting search terms should be used in combination when searching for the field.
      Parameters:
      field - Field to generate search terms for.
      metadata - Metadata about the field to generate search terms for.
      Returns:
      An array of deterministically encrypted fields to use when searching.

    • generateSearchTermsBatch

      public CompletableFuture<BatchResult<DeterministicEncryptedField[]>> generateSearchTermsBatch(Map<String,DeterministicPlaintextField> fields, FieldMetadata metadata)
      Deterministically encrypt a batch of fields with all current and in-rotation secrets for the tenant. Supports partial failure and will return both successfully encrypted fields as well as fields that failed to be encrypted.
      Parameters:
      fields - Map of field ID to plaintext field to generate search terms for.
      metadata - Metadata about the fields to generate search terms for.
      Returns:
      Collection of successes and failures that occurred during operation. The keys of each map returned will be the same keys provided in the original fields map.