Package com.ironcorelabs.tenantsecurity.kms.v1

Class TenantSecurityClient

java.lang.Object
com.ironcorelabs.tenantsecurity.kms.v1.TenantSecurityClient
All Implemented Interfaces:
Closeable, AutoCloseable
public final class TenantSecurityClient extends Object implements Closeable
TenantSecurityClient class that can be used to encrypt and decrypt documents.
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

    • TenantSecurityClient

      public TenantSecurityClient(String tspDomain, String apiKey) throws Exception
      Constructor for TenantSecurityClient class that uses the SecureRandom NativePRNGNonBlocking instance for random number generation.
      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.

    • TenantSecurityClient

      public TenantSecurityClient(String tspDomain, String apiKey, int requestThreadSize, int aesThreadSize) throws Exception
      Constructor for TenantSecurityClient class that allows call to provide web request and AES operation thread pool sizes. Uses the SecureRandom NativePRNGNonBlocking instance for random number generation.
      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.

    • TenantSecurityClient

      public TenantSecurityClient(String tspDomain, String apiKey, int requestThreadSize, int aesThreadSize, int timeout) throws Exception
      Constructor for TenantSecurityClient class that allows call to provide web request and AES operation thread pool sizes. Uses the SecureRandom NativePRNGNonBlocking instance for random number generation.
      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.

    • TenantSecurityClient

      public TenantSecurityClient(String tspDomain, String apiKey, int requestThreadSize, int aesThreadSize, SecureRandom randomGen) throws Exception
      Constructor for TenantSecurityClient 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
      randomGen - Instance of SecureRandom to use for PRNG when performing encryption operations.
      Throws:
      Exception - If the provided domain is invalid or the provided SecureRandom instance is not set.

    • TenantSecurityClient

      public TenantSecurityClient(String tspDomain, String apiKey, int requestThreadSize, int aesThreadSize, SecureRandom randomGen, int timeout) throws Exception
      Constructor for TenantSecurityClient 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
      randomGen - Instance of SecureRandom to use for PRNG when performing encryption operations.
      timeout - Request to TSP read and connect timeout in ms.
      Throws:
      Exception - If the provided domain is invalid or the provided SecureRandom instance is not set.

  • Method Details

    • close

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

    • getDeterministicClient

      public DeterministicTenantSecurityClient getDeterministicClient()
      Get a DeterministicTenantSecurityClient to deterministically encrypt and decrypt fields. The deterministic client inherits the configuration of this client, using the same thread pools for requests and AES operations as this client. To use a different configuration or pools, you can construct a DeterministicTenantSecurityClient directly.

    • create

      public static CompletableFuture<TenantSecurityClient> 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 TenantSecurityClient class.

    • addTspFailuresToBatchResult

      protected <T> BatchResult<T> addTspFailuresToBatchResult(BatchResult<T> batchResult, Map<String,ErrorResponse> tspFailures)
      Add a map of TSP failures to the provided BatchResult. The batch successes will be unchanged.
      Type Parameters:
      T - Success type for BatchResult. Should be EncryptedDocument or PlaintextDocument
      Parameters:
      batchResult - Result from batch operation like `encryptBatchOfDocuments`
      tspFailures - Failures provided by the TSP when calling a batch endpoint
      Returns:
      A new BatchResult where the failures are a combination of the original failures and the TSP-provided failures.

    • encryptStream

      public CompletableFuture<StreamingResponse> encryptStream(InputStream input, OutputStream output, DocumentMetadata metadata)
      Encrypt the bytes in input and write it to output. A new key will be wrapped using the TSP. The returned value contains the edek needed to decrypt the resulting stream.
      Parameters:
      input - The input stream of bytes to encrypt.
      output - The output stream to write encrypted bytes to.
      metadata - Metadata about the document being encrypted.
      Returns:
      The edek which can be used to decrypt the resulting stream

    • decryptStream

      public CompletableFuture<Void> decryptStream(String edek, InputStream input, OutputStream output, DocumentMetadata metadata)
      Decrypt the bytes that are represented by input using the key contained inside the edek. No bytes will be written to the output stream until the entire document has been decrypted. This means that even though the data is streamed in the decrypted data will be cached in memory until the tag has been verified. Once the GCM tag has been reached and verified, this function will return. If there is a problem with the document represented by input or a problem unwrapping the edek the returned CompletableFuture will return an exception instead.
      Parameters:
      edek - The encrypted dek which should be unwrapped by the TSP.
      input - A stream representing the encrypted document.
      output - An output stream to write the decrypted document to. Note that this output should not be used until after the future exits successfully because the GCM tag is not fully verified until that time.
      metadata - Metadata about the document being encrypted.
      Returns:
      Future which will complete when input has been decrypted.

    • encrypt

      public CompletableFuture<EncryptedDocument> encrypt(Map<String,byte[]> document, DocumentMetadata metadata)
      Encrypt the provided document. Documents are provided as a map of fields from the document id/name (String) to bytes (byte[]). Uses the Tenant Security Proxy to generate a new document encryption key (DEK), encrypt that key (EDEK) and then uses the DEK to encrypt all of the provided document fields. Returns an EncryptedDocument which contains a Map from each fields id/name to encrypted bytes as well as the EDEK and discards the DEK.
      Parameters:
      document - Document to encrypt. Each field in the provided document will be encrypted with the same key.
      metadata - Metadata about the document being encrypted.
      Returns:
      Encrypted document and base64 encrypted document key (EDEK) wrapped in a EncryptedResult class.

    • encrypt

      public CompletableFuture<EncryptedDocument> encrypt(PlaintextDocument document, DocumentMetadata metadata)
      Encrypt the provided document reusing an existing encrypted document encryption key (EDEK). Makes a call out to the Tenant Security Proxy to decrypt the EDEK and then uses the resulting key (DEK) to encrypt the document. This allows callers to update/re-encrypt data that has already been encrypted with an existing key. For example, if multiple columns in a DB row are all encrypted to the same key and one of those columns needs to be updated, this method allows the caller to update a single column without having to re-encrypt every field in the row with a new key.
      Parameters:
      document - PlaintextDocument which contains the encrypted document key (EDEK) as well as the Map of bytes to encrypt.
      metadata - Metadata about the document being encrypted.
      Returns:
      EncryptedDocument which contains a map of encrypted bytes and base64 encrypted document key (EDEK).

    • encryptBatch

      public CompletableFuture<BatchResult<EncryptedDocument>> encryptBatch(Map<String,Map<String,byte[]>> plaintextDocuments, DocumentMetadata metadata)
      Encrypt a map of documents from the ID of the document to the list of fields to encrypt. Makes a call out to the Tenant Security Proxy to generate a collection of new DEK/EDEK pairs for each document ID provided. This function supports partial failure so it returns two Maps, one of document ID to successfully encrypted document and one of document ID to a TenantSecurityException.
      Parameters:
      plaintextDocuments - Map of document ID to map of fields to encrypt.
      metadata - Metadata about all of the documents 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 plaintextDocuments map.

    • encryptExistingBatch

      public CompletableFuture<BatchResult<EncryptedDocument>> encryptExistingBatch(Map<String,PlaintextDocument> plaintextDocuments, DocumentMetadata metadata)
      Re-encrypt a existing map of documents from the ID of the document to the previously encrypted document. Makes a call out to the Tenant Security Proxy to decrypt the EDEKs present in each provided document. This function supports partial failure so it returns two Maps, one of document ID to successfully re-encrypted document and one of document ID to a TenantSecurityException.
      Parameters:
      plaintextDocuments - Map of previously encrypted document from ID to document.
      metadata - Metadata about all of the documents 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 plaintextDocuments map.

    • decrypt

      public CompletableFuture<PlaintextDocument> decrypt(EncryptedDocument encryptedDocument, DocumentMetadata metadata)
      Decrypt the provided EncryptedDocument. Decrypts the documents encrypted document key (EDEK) using the Tenant Security Proxy and uses it to decrypt and return the document bytes. The DEK is then discarded.
      Parameters:
      encryptedDocument - Document to decrypt which includes encrypted bytes as well as EDEK.
      metadata - Metadata about the document being decrypted.
      Returns:
      PlaintextDocument which contains each documents decrypted field bytes.

    • rekeyEdek

      public CompletableFuture<String> rekeyEdek(String edek, DocumentMetadata metadata, String newTenantId)
      Re-key a document's encrypted document key (EDEK) using a new KMS config. Decrypts the EDEK then re-encrypts it using the specified tenant's current primary KMS config. The DEK is then discarded.
      Parameters:
      edek - Encrypted document key to re-key.
      metadata - Metadata about the EDEK being re-keyed.
      newTenantId - Tenant ID the EDEK should be re-keyed to.
      Returns:
      Newly re-keyed EDEK.

    • decryptBatch

      public CompletableFuture<BatchResult<PlaintextDocument>> decryptBatch(Map<String,EncryptedDocument> encryptedDocuments, DocumentMetadata metadata)
      Decrypt a map of documents from the ID of the document to its encrypted content. Makes a call out to the Tenant Security Proxy to decrypt all of the EDEKs in each document. This function supports partial failure so it returns two Maps, one of document ID to successfully decrypted document and one of document ID to a TenantSecurityException.
      Parameters:
      encryptedDocuments - Map of documents to decrypt from ID of the document to the EncryptedDocument
      metadata - Metadata to use for each decrypt operation.
      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 encryptedDocuments map.

    • logSecurityEvent

      public CompletableFuture<Void> logSecurityEvent(SecurityEvent event, EventMetadata metadata)
      Send the provided security event to the TSP to be logged and analyzed. Returns Void if the security event was successfully received. Note that logging a security event is an asynchronous operation at the TSP, so successful receipt of a security event does not mean that the event is deliverable or has been delivered to the tenant's logging system. It simply means that the event has been received and will be processed.
      Parameters:
      event - Security event that represents the action that took place.
      metadata - Metadata that provides additional context about the event.
      Returns:
      Void on successful receipt by TSP