Application Protector Java

• 1: Understanding the Architecture
• 2: System Requirements
• 3: Preparing the Environment
• 4: Installing the AP Java Protector
• 5: Configuring the Protector
• 6: Application Protector Java APIs
• 6.1: Using the AP Java APIs
• 7: Additional Topics
• 7.1: Uninstalling the Application Protector
• 7.2: Memory Usage of the AP Java
• 7.3: DevOps Approach for Application Protector Java
• 7.4: Application Protector API Return Codes
• 7.5: Config.ini file for Application Protector
• 7.6: Multi-node Application Protector Architecture

1 - Understanding the Architecture

This page describes the architecture, the individual components, and the workflow of the Protegrity Application Protector (AP) solution.

Architecture and Workflow

The following figure illustrates the deployment architecture of the Application Protector (AP).

The following table describes the components of the AP deployment architecture.

The following steps describe the workflow of a sample AP deployment in the production environment.

1. The customer application initializes the SDK.
2. The configurations that are required configuration parameters are passed to the protector using the config.ini file.

   Note: The configurations can be set through environment variables. ENV overrides values in the config.ini file, except for cadence and session timeout which must be set in the config file.
   For more information about environment variables configuration, refer to Configuration Parameters for Protector.

3. The RP Agent regularly syncs with the RP Proxy or ESA to check for policy updates. If a change is detected, the updated policy package is securely downloaded over a TLS channel and stored in shared memory.
4. The protector synchronizes with shared memory based on the cadence value defined in config.ini file. If a new package is available, it is fetched into process memory. This updated package is then used to perform data protection operations such as, such as, protect, unprotect, and reprotect.
5. The audit logs generated during protection operations are forwarded to the Audit Store:
   • Logs from the application are sent through the Log Forwarder
   • Logs from the RP Agent are also forwarded using the Log Forwarder

Components of the Application Protector

The Protegrity Application Protector (AP) solution comprises several key components that work together to enforce data protection policies and ensure secure operations.

Application Protector

The core engine that integrates with customer applications to perform data protection operations:

• Protect
• Unprotect
• Reprotect

AP is available in multiple language-specific variants:

• AP Java: For applications developed in Java
• AP Python: For applications developed in Python

Resilient Package (RP) Agent

A standalone process responsible for policy synchronization:

• To sync with the RP Proxy or ESA at regular intervals of 60 seconds
• To detect policy changes and download updated packages over a secure TLS channel
• To store the packages in shared memory for use by the protector

Log Forwarder

A log processing tool that handles audit and protection logs:

• Collects logs generated by AP and RP Agent
• Forwards logs to the Audit Store within ESA

Ports used to transport the protection and audit logs to the ESA:

• 15780: Configurable
• 15781: Non-configurable

Package Deployment

The different approaches for package deployment during the initialization process of the Application Protector are described in this section.

Dynamic Package Deployment

Use this approach when the protector needs to continuously check for policy updates after initialization.

• Set the cadence parameter to a non-zero value in the config.ini file.
• This value defines the interval in seconds at which the protector synchronizes with the RP Agent.
• If a policy change is detected, the protector automatically fetches the updated package and applies it during protection operations.

  Note: This method ensures that the protector always operates with the latest policy.

Immutable Package Deployment

Use this approach when the protector does not need to check for policy changes after initialization.

• Add the [devops] parameter in the config.ini file before initializing the protector.
• A REST API call is used to download an envelope-encrypted package from the ESA.
• The protector uses this static package for all operations without further synchronization.
  For more information about the DevOps approach, refer to DevOps Approach for Application Protector.

2 - System Requirements

The following table lists the minimum hardware configurations.

3 - Preparing the Environment

Preparing the Environment for AP Java Installation on Linux

Before installing Protegrity Application Protector (AP) Java on a Linux platform, ensure the following prerequisites are met:

Prerequisites

• The Enterprise Security Administrator (ESA) is installed, configured, and running.
• The IP address or host name of the Load Balancer, Proxy, or ESA is noted.
• The Policy Management (PIM) is initialized on the ESA. It creates cryptographic keys and the policy repository for data protection.
  For more information about initializing the PIM, refer to Initializing the Policy Management.

4 - Installing the AP Java Protector

Extracting the Setup Scripts and Package

To extract the setup scripts and package:

1. Download the ApplicationProtector_Linux-ALL-64_x86-64_JRE-1.8-64_<version>.tgz file to any location on the machine where you want to install the protector.
2. Extract the AP Java installation package using the following command.
   

   tar –xvf ApplicationProtector_Linux-ALL-64_x86-64_JRE-1.8-64_<version>.tgz
   

   The following setup files are extracted:
   • ApplicationProtector_Linux-ALL-64_x86-64_JRE-1.8-64_<version>.tgz
   • signatures/ApplicationProtector_Linux-ALL-64_x86-64_JRE-1.8-64_<version>.sig
3. Verify the digital signature of the signed AP Java build.
   For more information about verifying the signed AP Java build, refer to Verification of Signed Protector Build.
4. Extract the AP Java installation package again using the following command.
   

   tar –xvf ApplicationProtector_Linux-ALL-64_x86-64_JRE-1.8-64_<version>.tgz
   

   The following setup files are extracted:
   • LogforwarderSetup_Linux_x64_<version>.sh
   • RPAgentSetup_Linux_x64_<version>.sh
   • APJavaSetup_Linux_x64_<version>.sh

Installing Log Forwarder on Linux

The steps to install the Log Forwarder on a Linux platform using the Interactive mode or through the Silent mode are described in this section.

Note: To preserve all the configurations while upgrading the Log Forwarder, ensure that you backup all the files present under the /opt/protegrity/logforwarder/data/config.d directory.

Using Interactive Mode

To install the Log Forwarder on a Linux platform using the Interactive mode:

1. Run the Log Forwarder installer using the following command.

   ./LogforwarderSetup_Linux_x64_<version>.sh
   

   The prompt to enter the Audit Store endpoint appears.

   Enter the audit store endpoint (host),
   alternative (host:port) to use another port than the default port 9200 :
   

2. Enter the Audit Store endpoint that is the Audit Store IP address and the Audit Store port number where the Log Forwarder sends the logs.

   Note: The default port number is 9200. If you are using the default port, then do not specify the port number.

3. Press ENTER.

   The added Audit Store endpoint appears on the screen.

   The prompt to enter an additional Audit Store appears.

   Do you want to add another audit store endpoint? [y/n]:
   

4. If you want to add more than one Audit Store endpoint, then type y otherwise type n.
   If you need to add additional Audit Store endpoints, then repeat both Step 2 and Step 3 for each additional endpoint to add.

5. Type the y key to install into the destination directory.

   The Log Forwarder is installed in the /opt/protegrity/logforwarder/ directory.

6. Start the Protegrity Log Forwarder service by using the following command.

   /opt/protegrity/logforwarder/bin/logforwarderctrl start
   

   The Log Forwarder is successfully installed.

Using Silent Mode

You can also execute the Log Forwarder installer without any manual intervention, which is also known as the Silent mode of installation. The following parameters must be provided to execute the installer in the Silent mode.

At the command prompt, type the following command from the installer directory.

./LogforwarderSetup_Linux_x64_<version>.sh -e <ip address:port number> [-e <ip address:port number>]

To install the Log Forwarder in a custom directory, add the -d or --dir argument to the command to specify the Log Forwarder installation directory.

The following snippet displays a sample command.

./LogforwarderSetup_Linux_x64_<version>.sh -e <ip address:port number> [-e <ip address:port number>] -d <Log Forwarder installation directory> 

Installing RP Agent on Linux

The steps to install the RP Agent on a Linux platform using the Interactive mode or through the Silent mode of installation are described in this section.

Using Interactive Mode

To install the RP Agent on a Linux platform using the Interactive mode:

1. Run the RP Agent installer using the following command.

   ./RPAgentSetup_Linux_x64_<version>.sh
   

   The prompt to enter the upstream hostname or IP address appears.

   Please enter upstream host name or IP address
   []:
   

2. Enter the ESA Host Name or IP Address.

3. Press ENTER.

   The prompt to enter the username for downloading certificates appears.

   Please enter the user name for downloading certificates
   []:
   

4. Enter the username for downloading the certificates.

5. Press ENTER.

   The prompt to enter the password for downloading the certificates appears.

   Please enter the password for downloading certificates
   []:
   

6. Enter ESA password.

7. Press ENTER to install into the destination directory.

   Directories are created under /opt/protegrity/rpagent by default, and the required installation files are installed in these directories.

   Ensure that the ESA is up and running with the HubController service in running status to enable automatic downloading of certificates.

8. If you have installed the RP Agent using the --nocert parameter, then the ESA certificates are not downloaded during the installation. To manually install the certificates to the /opt/protegrity/rpagent/data directory of the RP Agent, perform the following steps.

   i. Navigate to the /opt/protegrity/rpagent/bin directory and run the following command.

   ./GetCertificates -u <ESA User with the Export Certificates role and can create JWT token> [-h <ESA host name or IP address>] [--port <port no.>] [-d directory]
   

   This initiates a secure communication between the RP Agent and the ESA.

   ii. Enter the password for the ESA user.

   iii. Verify that the following files have been copied to the /opt/protegrity/rpagent/data directory:

   • CA.pem
   • cert.key
   • cert.pem
   • rpagent.cfg
   • secret.txt

9. Start the RP Agent by using the following command.

   /opt/protegrity/rpagent/bin/rpagentctrl start
   

   The RP Agent is successfully installed.

Using Silent Mode

You can also execute the RP Agent installer without any manual intervention, which is also known as the Silent mode of installation. The following parameters must be provided to execute the installer in the Silent mode.

At the command prompt, type the following command from the installer directory.

./RPAgentSetup_Linux_x64_<version>.sh (-u <user> -p <password>) [-h <host>] [--port <port>] 

If you want to install the RP Agent in a custom directory, then you can add the -d parameter to the command to specify the directory.

The following command displays a sample snippet.

./RPAgentSetup_Linux_x64_<version>.sh (-u <user> -p <password>) [-h <host>] [--port <port>] [-d <dir>]

Installing Application Protector Java on Linux

The steps to install the AP Java on a Linux platform using the Linux installer or through the Silent mode of installation, are described in this section.

Using Linux Installer

To install the AP Java on the Linux platform using the Linux installer:

1. Run the AP Java installer using the following command.

   ./APJavaSetup_Linux_x64_<version>.sh
   

   The prompt to continue the installation appears.

   *****************************************************
   Welcome to the AP Java SDK Setup Wizard
   *****************************************************
   
   This will install AP Java SDK on your computer.
   
   Do you want to continue? [yes or no]
   

2. If you want to continue with the installation of the AP Java SDK, then type yes else type no.

   If you type yes, then the prompt to enter the installation directory appears.

   Please enter installation directory
   [/opt/protegrity]:
   

   If you type no, then the installation of the AP Java aborts.

The AP Java is installed successfully.

The default installation directory for the AP Java on a Linux platform is /opt/protegrity/sdk/java.

Ensure that the following folder structure is maintained:

• /lib and /data directories are located at the same directory level
  
• ApplicationProtectorJava.jar and jcorelite.plm are located inside the /lib directory
  
• config.ini file is located in the /data directory
  

Using Silent Mode

You can also execute the AP Java installer without any manual intervention, which is also known as the Silent mode of installation. The following parameter must be provided to execute the installer in the Silent mode.

./APJavaSetup_Linux_x64_<version>.sh [-dir <directory>]

5 - Configuring the Protector

Configuring AP Java on Linux

To configure the AP Java on the Linux platform:

1. Setup the Java classpath.

   Operating System	Classpath
   Linux	/opt/protegrity/sdk/java/lib

2. Before the trusted application can successfully load the ApplicationProtectorJava.jar file, ensure that -

   • The Java classpath is set accurately.
   • The path to jcorelite.plm is configured properly.

3. Deploy a policy to test the application.

   For more information about deploying a policy, refer to Deploying Policies.

For more information about configuring the various parameters for the AP Java using the config.ini file, refer to Config.ini file for Application Protector.

Verifying Installation of AP Java

The steps to verify the successful installation of the AP Java are described in this section.

1. Configure the application as a trusted application in the ESA.
   For more information about trusted applications, refer to Working With Trusted Applications.

2. Initialize AP Java.
   For more information about the AP Java initialization API, refer to getProtector.

3. Run the GetVersion method using the following command to check the version of the installed AP Java.

   public java.lang.String getVersion()
   

   The following is a sample code to check the version number of the installed AP Java.

   /* Illustrates how to call getVersion() api to know the version of Application Protector
   * Executing this for the first time creates a forensic entry that should be added to the authorized app
   *
   * Compiled as : javac -cp ApplicationProtectorJava.jar AP_Java_getVersion
   * Run as : java -cp ApplicationProtectorJava.jar AP_Java_getVersion
   */
    import com.protegrity.ap.java.*;
    public class GetVersion {
        public static void main(String[] args) throws ProtectorException {
   
        Protector protector=null;
        try {
        protector=Protector.getProtector();
        System.out.println("Product version : "+protector.getVersion());
        } catch (ProtectorException e) {
        e.printStackTrace();
        throw e;
            }
        }
    }
   

6 - Application Protector Java APIs

A session must be created to run the Application Protector (AP) Java. The session enables AP Java to access information about the Trusted Application from the policy stored in memory. If the application is trusted, then the protect, unprotect, or reprotect method is called, one or many times, depending on the data.

The AP Java can be initialized by an OS User who is registered and deployed as the Trusted Application User in the ESA. The OS User can also be a Policy User.

The following diagram represents the basic flow of a session.

Note: The AP Java only supports bytes converted from the string data type.
If any other data type is directly converted to bytes and passed as an input to the API that supports byte as an input and provides byte as an output, then data corruption might occur.

Supported data types for the AP Java

The AP Java supports the following data types:

• Bytes
• Double
• Float
• Integer
• java.util.Date
• Long
• Short
• String

The following are the various APIs provided by the AP Java.

getProtector

The getProtector method returns the Protector object associated with the AP Java APIs. After initialization, this object is used to create a session. The session is then passed as a parameter to protect, unprotect, or reprotect methods.

static Protector getProtector() 

Parameters
None

Returns
Protector Object: An object associated with the Protegrity Application Protector API.

Exception
ProtectorException: If the configurations are invalid, then an exception is thrown indicating a failed initialization.

getVersion

The getVersion method returns the product version of the AP Java in use.

public java.lang.String getVersion()

Parameters
None

Returns
String: Product version

getVersionEx

The getVersionEx method returns the extended version of the AP Java in use. The extended version consists of the Product version number and the CORE version number.

Note: The Core version is a sub-module used for troubleshooting protector issues.

public java.lang.String getVersionEx()

Parameters
None

Returns
String: Product version and CORE version

getLastError

The getLastError method returns the last error and a description of why this error was returned. When the methods used for protecting, unprotecting, or reprotecting data return an exception or a Boolean false, the getLastError method is called that describes why the method failed.

public java.lang.String getLastError(SessionObject session)

Parameters
Session: Session ID that is obtained by calling the createSession method.

Returns
String: Error message

Exception
ProtectorException: If the SessionObject is null, then an exception is thrown
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown

For more information about the return codes, refer to Application Protector API Return Codes.

createSession

The createSession method creates a new session. The sessions that have not been utilized for a while, are automatically removed according to the sessiontimeout parameter defined in the [protector] section of the config.ini file.

The methods in the Protector API that take the SessionObject as a parameter, might throw an exception SessionTimeoutException if the session is invalid or has timed out. The application developers can handle the SessionTimeoutException and create a new session with a new SessionObject.

public SessionObject createSession(java.lang.String policyUser)

Parameters
policyUser: User name defined in the policy, as a string value.

Returns
SessionObject: Object of the SessionObject class.

Exception
ProtectionException: If input is null or empty, then an exception is thrown.

protect - Short array data

It It protects the data provided as a short array that uses the preservation data type or No Encryption data element. It supports bulk protection. There is no maximum data limit. For more information about the data limit, refer to AES Encryption.

If the data type preservation methods are used for data protection, then the protected data can be stored in the same data type as used for the input data.

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, short[] input, short[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with short format data.
output: Resultant output array with short format data.
externalIv: Buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Short array data for encryption

It protects the data provided as a short array that uses an encryption data element. It supports bulk protection. There is no maximum data limit.
For more information about the data limit, refer to AES Encryption.

When the encryption method is used to protect data, the output of data protection (protected data) should be stored in byte[].

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, short[] input, byte[][] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with short format data.
output: Resultant output array with byte format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Note: Encryption data elements do not support external IV.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Int array data

It It protects the data provided as an int array that uses the preservation data type or No Encryption data element. It supports bulk protection. However, you are recommended to pass not more than 1 MB of input data for each protection call.

If the data type preservation methods are used for data protection, then the protected data can be stored in the same data type as used for the input data.

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, int[] input, int[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with int data.
output: Resultant output array with int data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Int array data for encryption

It protects the data provided as an int array that uses an encryption data element. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

Data protected by using encryption data elements with input as integers, long or short data types, and output as bytes, cannot move between platforms with different endianness.
For example, you cannot move the protected data from the AIX platform to Linux or Windows platform and vice versa while using encryption data elements in the following scenarios:

• Input as integers and output as bytes
• Input as short integers and output as bytes
• Input as long integers and output as bytes

When the encryption method is used to protect data, the output of data protection (protected data) should be stored in byte[].

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, int[] input, byte[][] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with int data.
output: Resultant output array with byte data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Note: Encryption data elements do not support external IV.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Long array data

It protects the data provided as a long array that uses the preservation data type or No Encryption data element. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

If the data type preservation methods are used for data protection, then the protected data can be stored in the same data type as used for the input data.

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, long[] input, long[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with long format data.
output: Resultant output array with long format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Long array data for encryption

It protects the data provided as a long array that uses an encryption data element. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

When the encryption method is used to protect data, the output of data protection (protected data) should be stored in byte[].

protect(SessionObject sessionObj, java.lang.String dataElementName, long[] input, byte[][] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with long format data.
output: Resultant output array with byte format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Note: Encryption data elements do not support external IV.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Float array data

It protects the data provided as a float array that uses the No Encryption data element. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

If the data type preservation methods are used for data protection, then the protected data can be stored in the same data type as used for the input data.

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, float[] input, float[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with float format data.
output: Resultant output array with float format data.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Float array data for encryption

It protects the data provided as a float array that uses an encryption data element. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

When the encryption method is used to protect data, the output of data protection (protected data) should be stored in byte[].

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, float[] input, byte[][] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with float format data.
output: Resultant output array with byte format data.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Double array data

It protects the data provided as a double array that uses the No Encryption data element. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

When the data type preservation methods are used to protect data, the output of data protection can be stored in the same data type that was used for the input data.

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, double[] input, double[] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with double format data.
output: Resultant output array with double format data.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Double array data for encryption

It protects the data provided as a double array that uses an encryption data element. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

When the encryption method is used to protect data, the output of data protection (protected data) should be stored in byte[].

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, double[] input, byte[][] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with double format data.
output: Resultant output array with byte format data.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Date array data

It protects the data provided as a java.util.Data array that uses a preservation data type. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

If the data type preservation methods are used for data protection, then the protected data can be stored in the same data type as used for the input data.

If the protect and unprotect operations are performed in different time zones using the java.util.Date API, then the unprotected data does not match with the input data.
For example, if you perform the protect operation in EDT time zone using the java.util.Date API, then you must perform the unprotect operation only in EDT time zone. This ensures that the unprotect operation returns back the original data.

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, java.util.Date[] input, java.util.Date[] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with date format data.
output: Resultant output array with date format data.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - String array data

It protects the data provided as a string array that uses a preservation data type or the No Encryption data element. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

For String and Byte data types, the maximum length for tokenization is 4096 bytes, while for encryption there is no maximum length defined.

If the data type preservation methods are used for data protection, then the protected data can be stored in the same data type as used for the input data.

For Date and Datetime type of data elements, an invalid input data error is returned by the protect API if the input value falls between the non-existent date range. It ranges from 05-OCT-1582 to 14-OCT-1582 of the Gregorian Calendar.

For more information about the tokenization and de-tokenization of the cutover dates of the Proleptic Gregorian Calendar, refer to section Datetime Tokenization for Cutover Dates of the Proleptic Gregorian Calendar.

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, java.lang.String[] input, java.lang.String[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with string format data.
output: Resultant output array with string format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - String array data for encryption

It protects the data provided as s string array that uses an encryption data element. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

For String and Byte data types, the maximum length for tokenization is 4096 bytes, while for encryption there is no maximum length defined.

The output of data protection is stored in byte[] when:

• Encryption method is used to protect data
• Format Preserving Encryption (FPE) method is used for Char and String APIs

The string as an input and byte as an output API is unsupported by Unicode Gen2 and FPE data elements for the AP Java.

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, java.lang.String[] input, byte[][] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with string format data.
output: Resultant output array with byte format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Note: Encryption data elements do not support external IV.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Char array data

It protects the data provided as a char array that uses a preservation data type or the No Encryption data element. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

If the data type preservation methods are used for data protection, then the protected data can be stored in the same data type as used for the input data.

For Date and Datetime type of data elements, an invalid input data error is returned by the protect API if the input value falls between the non-existent date range. It ranges from 05-OCT-1582 to 14-OCT-1582 of the Gregorian Calendar.

For more information about the tokenization and de-tokenization of the cutover dates of the Proleptic Gregorian Calendar, refer to section Datetime Tokenization for Cutover Dates of the Proleptic Gregorian Calendar.

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, char[][] input, char[][] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with char format data.
output: Resultant output array with char format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Char array data for encryption

It protects the data provided as a char array that uses an encryption data element. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

The output of data protection is stored in byte[] when:

• Encryption method is used to protect data
• Format Preserving Encryption (FPE) method is used for Char and String APIs

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, char[][] input, byte[][] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with char format data.
output: Resultant output array with byte format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Note: Encryption data elements do not support external IV.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - Byte array data

It protects the data provided as a byte array that uses the encryption data element, No Encryption data element, and preservation data type. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

For String and Byte data types, the maximum length for tokenization is 4096 bytes, while for encryption there is no maximum length defined.

The Protegrity AP Java protector only supports bytes converted from the string data type.
If any data type is converted to bytes and passed as input to the API supporting byte as input and providing byte as output, then data corruption might occur.

If the data type preservation methods are used for data protection, then the protected data can be stored in the same data type as used for the input data.

For Date and Datetime type of data elements, an invalid input data error is returned by the protect API if the input value falls between the non-existent date range. It ranges from 05-OCT-1582 to 14-OCT-1582 of the Gregorian Calendar.

For more information about the tokenization and de-tokenization of the cutover dates of the Proleptic Gregorian Calendar, refer to section Datetime Tokenization for Cutover Dates of the Proleptic Gregorian Calendar.

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, byte[][] input, byte[][] output, PTYCharset ...ptyCharsets)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with byte format data.
output: Resultant output array with byte format data.
ptyCharsets: Encoding associated with the bytes of the input data.

PTYCharset ptyCharsets = PTYCharset.<encoding>;

The ptyCharsets parameter supports the following encodings:

• UTF-8
• UTF-16LE
• UTF-16BE

The ptyCharsets parameter is mandatory for the data elements created with Unicode Gen2 tokenization method and the FPE encryption method for byte APIs. The encoding set for the ptyCharsets parameter must match the encoding of the input data passed.

The default value for the ptyCharsets parameter is UTF-8.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

protect - String array data with External Tweak

It protects the data provided as a string array using the FPE (FF1) that uses a preservation data type with FPE data elements. It supports bulk protection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each protection call.

When FPE method is used with FPE data elements for data protection, the protected data can be stored in the same data type that was used for input data.

public boolean protect(SessionObject sessionObj, java.lang.String dataElementName, java.lang.String[] input, java.lang.String[] output, byte[] externalIv, byte[] externalTweak)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with string format data.
output: Resultant output array with string format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.
externalTweak: Optional parameter, which is a buffer containing data that will be used as Tweak, when externalTweak = null, the value is ignored.

Result
True: The data is successfully protected.
False: The parameters passed are accurate, but the method failed when:

• The protection methods failed to perform the required action
  
• The data element is null or empty

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Short array data

It unprotects the data provided as a short array that uses the preservation data type or the No Encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, short[] input, short[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with short format data.
output: Resultant output array with short format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Short array data for encryption

It unprotects the data provided as a short array that uses an encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, byte[][] input, short[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with byte format data.
output: Resultant output array with short format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Note: Encryption data elements do not support external IV.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Int array data

It unprotects the data provided as an int array that uses a preservation data type or a No Encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, int[] input, int[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with int format data.
output: Resultant output array with int format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Int array data for encryption

It unprotects the data provided as an int array that uses an encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, byte[][] input, int[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with byte format data.
output: Resultant output array with int format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Note: Encryption data elements do not support external IV.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Long array data

It unprotects the data provided as a long array that uses the preservation data type or the No Encryption data element. It supports the bulk unprotection. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, long[] input, long[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with long format data.
output: Resultant output array with long format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Long array data for encryption

It unprotects the data provided as a long array that uses an encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, byte[][] input, long[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with byte format data.
output: Resultant output array with long format data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Note: Encryption data elements do not support external IV.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Float array data

It unprotects the data provided as a float array that uses a No Encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, float[] input, float[] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with float format data.
output: Resultant output array with float format data.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Float array data for encryption

It unprotects the data provided as a float array that uses an encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, byte[][] input, float[] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with byte format data.
output: Resultant output array with float format data.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Double array data

It unprotects the data provided as a double array that uses the No Encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, double[] input, double[] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with double format data.
output: Resultant output array with double format data.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Double array data for encryption

It unprotects the data provided as a double array that uses an encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, byte[][] input, double[] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with byte format data.
output: Resultant output array with double format data.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Date array data

It unprotects the data provided as a java.util.Date array using the preservation data type. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

If the protect and unprotect operations are performed in different time zones using the java.util.Date API, then the unprotected data does not match with the input data.
For example, if you perform the protect operation in EDT time zone using the java.util.Date API, then you must perform the unprotect operation only in EDT time zone. This ensures that the unprotect operation returns back the original data.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, java.util.Date[] input, java.util.Date[] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with date format data.
output: Resultant output array with date format data.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - String array data

It unprotects the data provided as a string array that uses a preservation data type or a No Encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, String[] input, String[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with string format data.
output: Resultant output array with string format data.
externalIv: This is optional. Buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - String array data for encryption

It unprotects the data provided as a string array that uses an encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, byte[][] input, String[] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with byte format data.
output: Resultant output array with string format data.
externalIv: This is optional. Buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Note: Encryption data elements do not support external IV.

Result
True: The data is successfully unprotected
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Char array data

It unprotects the data provided as a char array that uses a preservation data type or a No Encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, char[][] input, char[][] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with char format data.
output: Resultant output array with char data.
externalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Char array data for encryption

It unprotects the data provided as a char array that uses an encryption data element. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, byte[][] input, char[][] output, byte[] externalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with byte format data.
output: Resultant output array with char format data.
externalIv: This is optional. Buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - Byte array data

It unprotects the data provided as a byte array that uses an encryption data element or a No Encryption data element, or a preservation data type. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

The Protegrity AP Java protector only supports bytes converted from the string data type.
If any data type is converted to bytes and passed as input to the API supporting byte as input and providing byte as output, then data corruption might occur.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, byte[][] input, byte[][] output, byte[] externalIv, PTYCharset ...ptyCharsets)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with byte format data.
output: Resultant output array with byte format data.
externalIv: This is optional. Buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.
ptyCharsets: Encoding associated with the bytes of the input data.

PTYCharset ptyCharsets = PTYCharset.<encoding>;

The ptyCharsets parameter supports the following encodings:

• UTF-8
• UTF-16LE
• UTF-16BE

The ptyCharsets parameter is mandatory for the data elements created with Unicode Gen2 tokenization method and the FPE encryption method for byte APIs. The encoding set for the ptyCharsets parameter must match the encoding of the input data passed.

The default value for the ptyCharsets parameter is UTF-8.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

unprotect - String array data with External Tweak

It unprotects the data provided as a string array using the FPE (FF1) that uses a preservation data type with FPE data elements. It supports the bulk unprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each unprotection call.

public boolean unprotect(SessionObject sessionObj, java.lang.String dataElementName, String[] input, String[] output, byte[] externalIv, byte[] externalTweak)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
dataElementName: String containing the data element name defined in policy.
input: Input array with byte format data.
output: Resultant output array with byte format data.
externalIv: This is optional. Buffer containing data that will be used as external IV, when externalIv = null, the value is ignored.

Result
True: The data is successfully unprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

reprotect - String array data

It reprotects the data provided as a string array that uses a preservation data type or a No Encryption data element. The protected data is first unprotected and then protected again with a new data element. It supports the bulk reprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each reprotection call.

For String and Byte data types, the maximum length for tokenization is 4096 bytes.

If you are using the reprotect API, then the old data element and the new data element must have the same data type. For example, if you have used Alpha-Numeric data element to protect the data, then you must use only Alpha-Numeric data element to reprotect the data.

public boolean reprotect(SessionObject sessionObj, String newDataElementName, String oldDataElementName, java.lang.String[] input, java.lang.String[] output, byte[] newExternalIv, byte[] oldExternalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
newdataElementName: String containing the data element name defined in policy to create the output data.
olddataElementName: String containing the data element name defined in policy for the input data.
input: Input array with string format data.
output: Resultant output array with string format data.
newexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when newExternalIv = null, the value is ignored.
oldexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when oldExternalIv = null, the value is ignored.

Result
True: The data is successfully reprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as a text explanation and reason for the failure, call getLastError(session).

Exception
ProtectorException: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

reprotect - Short array data

It reprotects the data provided as a short array that uses a preservation data type or a No Encryption data element. The protected data is first unprotected and then protected again with a new data element. It supports the bulk reprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each reprotection call.

If you are using the reprotect API, then the old data element and the new data element must have the same data type.
For example, if you have used Alpha-Numeric data element to protect the data, then you must use only Alpha-Numeric data element to reprotect the data.

public boolean reprotect(SessionObject sessionObj, String newDataElementName, String oldDataElementName, short[] input, short[] output, byte[] newExternalIv, byte[] oldExternalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
newdataElementName: String containing the data element name defined in policy to create the output data.
olddataElementName: String containing the data element name defined in policy for the input data.
input: Input array with short format data.
output: Resultant output array with short format data.
newexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when newExternalIv = null, the value is ignored.
oldexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when oldExternalIv = null, the value is ignored.

Result
True: The data is successfully reprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

reprotect - Int array data

It reprotects the data provided as an int array that uses a preservation data type or a No Encryption data element. The protected data is first unprotected and then protected again with a new data element. It supports the bulk reprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each reprotection call.

If you are using the reprotect API, then the old data element and the new data element must have the same data type.
For example, if you have used Alpha-Numeric data element to protect the data, then you must use only Alpha-Numeric data element to reprotect the data.

public boolean reprotect(SessionObject sessionObj, String newDataElementName, String oldDataElementName, int[] input, int[] output, byte[] newExternalIv, byte[] oldExternalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
newdataElementName: String containing the data element name defined in policy to create the output data.
olddataElementName: String containing the data element name defined in policy for the input data.
input: Input array with int format data.
output: Resultant output array with int format data.
newexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when newExternalIv = null, the value is ignored.
oldexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when oldExternalIv = null, the value is ignored.

Result
True: The data is successfully reprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

reprotect - Long array data

It reprotects the data provided as a long array that uses a preservation data type or a No Encryption data element. The protected data is first unprotected and then protected again with a new data element. It supports the bulk reprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each reprotection call.

If you are using the reprotect API, then the old data element and the new data element must have the same data type.
For example, if you have used Alpha-Numeric data element to protect the data, then you must use only Alpha-Numeric data element to reprotect the data.

public boolean reprotect(SessionObject sessionObj, String newDataElementName, String oldDataElementName, long[] input, long[] output, byte[] newExternalIv, byte[] oldExternalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
newdataElementName: String containing the data element name defined in policy to create the output data.
olddataElementName: String containing the data element name defined in policy for the input data.
input: Input array with long format data.
output: Resultant output array with long format data.
newexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when newExternalIv = null, the value is ignored.
oldexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when oldExternalIv = null, the value is ignored.

Result
True: The data is successfully reprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

reprotect - Float array data

It reprotects the data provided as a float array that uses a No Encryption data element. The protected data is first unprotected and then protected again with a new data element. It supports the bulk reprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each reprotection call.

If you are using the reprotect API, then the old data element and the new data element must have the same data type.
For example, if you have used Alpha-Numeric data element to protect the data, then you must use only Alpha-Numeric data element to reprotect the data.

public boolean reprotect(SessionObject sessionObj, String newDataElementName, String oldDataElementName, float[] input, float[] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
newdataElementName: String containing the data element name defined in policy to create the output data.
olddataElementName: String containing the data element name defined in policy for the input data.
input: Input array with float format data.
output: Resultant output array with float format data.
newexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when newExternalIv = null, the value is ignored.
oldexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when oldExternalIv = null, the value is ignored.

Result
True: The data is successfully reprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

reprotect - Double array data

It reprotects the data provided as a double array that uses a No Encryption data element. The protected data is first unprotected and then protected again with a new data element. It supports the bulk reprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each reprotection call.

If you are using the reprotect API, then the old data element and the new data element must have the same data type.
For example, if you have used Alpha-Numeric data element to protect the data, then you must use only Alpha-Numeric data element to reprotect the data.

public boolean reprotect(SessionObject sessionObj, String newDataElementName, String oldDataElementName, double[] input, double[] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
newdataElementName: String containing the data element name defined in policy to create the output data
olddataElementName: String containing the data element name defined in policy for the input data.
input: Input array with double format data.
output: Resultant output array with double format data.

Result
True: The data is successfully reprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

reprotect - Date array data

It reprotects the data provided as a date array that uses a preservation data type. The protected data is first unprotected and then protected again with a new data element. It supports the bulk reprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each reprotection call.

If you are using the reprotect API, then the old data element and the new data element must have the same data type.
For example, if you have used Alpha-Numeric data element to protect the data, then you must use only Alpha-Numeric data element to reprotect the data.

If the protect and unprotect operations are performed in different time zones using the java.util.Date API, then the unprotected data does not match with the input data.
For example, if you perform the protect operation in EDT time zone using the java.util.Date API, then you must perform the unprotect operation only in EDT time zone. This ensures that the unprotect operation returns back the original data.

public boolean reprotect(SessionObject sessionObj, String newDataElementName, String oldDataElementName, java.util.Date[] input, java.util.Date[] output)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
newdataElementName: String containing the data element name defined in policy to create the output data.
olddataElementName: String containing the data element name defined in policy for the input data.
input: Input array with date format data.
output: Resultant output array with date format data.

Result
True: The data is successfully reprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

reprotect - Byte array data

It reprotects the data provided as a byte array that uses an encryption data element or a No Encryption data element, or a preservation data type. The protected data is first unprotected and then protected again with a new data element. However, you are recommended to pass not more than 1 MB of input data for each reprotection call.

When the data type preservation methods, such as, Tokenization and No Encryption are used to reprotect data, the output of data protection (protected data) can be stored in the same data type that was used for input data.

The Protegrity AP Java protector only supports bytes converted from the string data type.
If any data type is converted to bytes and passed as input to the API supporting byte as input and providing byte as output, then data corruption might occur.

If you are using the reprotect API, then the old data element and the new data element must have the same data type.
For example, if you have used Alpha-Numeric data element to protect the data, then you must use only Alpha-Numeric data element to reprotect the data.

public boolean reprotect(SessionObject sessionObj, String newDataElementName, String oldDataElementName, byte[][] input, byte[][] output, byte[] newExternalIv, byte[] oldExternalIv, PTYCharset ...ptyCharsets)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
newdataElementName: String containing the data element name defined in policy to create the output data.
olddataElementName: String containing the data element name defined in policy for the input data.
input: Input array with byte format data.
output: Resultant output array with byte format data.
newexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when newExternalIv = null, the value is ignored.
oldexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when oldExternalIv = null, the value is ignored.
ptyCharsets: Encoding associated with the bytes of the input data.

PTYCharset ptyCharsets = PTYCharset.<encoding>;

The ptyCharsets parameter supports the following encodings:

• UTF-8
• UTF-16LE
• UTF-16BE

The ptyCharsets parameter is mandatory for the data elements created with Unicode Gen2 tokenization method and the FPE encryption method for byte APIs. The encoding set for the ptyCharsets parameter must match the encoding of the input data passed.

The default value for the ptyCharsets parameter is UTF-8.

Result
True: The data is successfully reprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

reprotect - String array data with External Tweak

It reprotects the data provided as a string array using the FPE (FF1) that uses a preservation data type with FPE data elements. The protected data is first unprotected and then protected again with a new FPE data element. It supports the bulk reprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each reprotection call.

If you are using the reprotect API, then the old data element and the new data element must have the same data type.
For example, if you have used Alpha-Numeric data element to protect the data, then you must use only Alpha-Numeric data element to reprotect the data.

public boolean reprotect(SessionObject sessionObj, String newDataElementName, String oldDataElementName, String[] input, String[] output, byte[] newExternalIv, byte[] oldExternalIv, byte[] newExternalTweak, byte[] oldExternalTweak)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
newdataElementName: String containing the data element name defined in policy to create the output data.
olddataElementName: String containing the data element name defined in policy for the input data.
input: Input array with String format data.
output: Resultant output array with String format data.
newexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when newExternalIv = null, the value is ignored.
oldexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when oldExternalIv = null, the value is ignored.
newExternalTweak: Optional parameter, which is a buffer containing data that will be used as Tweak, when newExternalTweak = null, the value is ignored.
oldExternalTweak: Optional parameter, which is a buffer containing data that will be used as Tweak, when oldExternalTweak = null, the value is ignored.

Result
True: The data is successfully reprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as, a text explanation and reason for the failure, call getLastError(session).

Exception
Protector Exception: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

reprotect - Char array data

It reprotects the data provided as a char array that uses a preservation data type or a No Encryption data element. The protected data is first unprotected and then protected again with a new data element. It supports the bulk reprotection. There is no maximum data limit. However, you are recommended to pass not more than 1 MB of input data for each reprotection call.

If you are using the reprotect API, then the old data element and the new data element must have the same data type. For example, if you have used Alpha-Numeric data element to protect the data, then you must use only Alpha-Numeric data element to reprotect the data.

public boolean reprotect(SessionObject sessionObj, String newDataElementName, String oldDataElementName, char[][] input, char[][] output, byte[] newExternalIv, byte[] oldExternalIv)

Parameters
sessionObj: SessionObject that is obtained by calling the createSession method.
newdataElementName: String containing the data element name defined in policy to create the output data.
olddataElementName: String containing the data element name defined in policy for the input data.
input:Input array with char format data.
output: Resultant output array with char format data.
newexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when newExternalIv = null, the value is ignored.
oldexternalIv: Optional parameter, which is a buffer containing data that will be used as external IV, when oldExternalIv = null, the value is ignored.

Result
True: The data is successfully reprotected.
False: The parameters passed are accurate, but the method failed to perform the required action.

For more information, such as a text explanation and reason for the failure, call getLastError(session).

Exception
ProtectorException: If the SessionObject is null or if policy is configured to throw an exception, then an exception is thrown.
SessionTimeoutException: If the session is invalid or has timed out, then an exception is thrown.

6.1 - Using the AP Java APIs

The process to use the AP Java protect, unprotect, and reprotect methods are described on this page.

It is assumed that the ESA is already available.

The tasks can be divided in the following order.

1. Create the data elements and data store in the Policy Management on the ESA Web UI.
2. Create the member sources and roles.
3. Configure the policy.
4. Configure the trusted application.
5. Add a trusted application to the data store.
6. Install the AP Java.
7. Run the sample application.

Creating a data element and data store

Determine how the data needs to be protected either by using encryption or tokenization before running the application. Protection and unprotection methods are available for both.

Create a data element and data store in the ESA by performing the following.

1. To create a data element, from the ESA Web UI, navigate to Policy Management → Data Elements & Masks → Data Elements.
   For more information about creating data elements, refer to Working With Data Elements.
2. To create a data store, navigate to Policy Management → Data Stores.
   For more information about creating data stores, refer to Creating a Data Store.

Creating a member source and role

Create a member source and role in the ESA by performing the following.

1. To create a member source, from the ESA Web UI, navigate to Policy Management → Roles & Member Sources → Member Sources.
   For more information about creating a member source, refer to Working With Member Sources.
2. To create a role, from the ESA Web UI, navigate to Policy Management → Roles & Member Sources → Roles.
   For more information about creating a role, refer to Working with Roles.

Configuring a policy

Configure a policy in the ESA by performing the following.

1. From the ESA Web UI, navigate to Policy Management → Policies & Trusted Applications → Policies.
2. Click Add New Policy.
   The New Policy screen appears.
3. After the policy is configured for the application user, add the permissions, data elements, roles, and data stores to the policy and then save it.
4. Deploy the policy using the Policy Management Web UI.

For more information about creating a data security policy, refer to Creating Policies.

Configuring a trusted application

Only the applications and users configured as trusted applications under the ESA security policy can access the AP APIs.
If a policy is deployed but the application or the user is not trusted, then the AP aborts with the following message while performing the protect or unprotect operations.
API consumer is not part of the trusted applications, please contact the Security Officer

Configure a trusted application in the ESA by performing the following.

1. From the ESA Web UI, navigate to Policy Management → Policies & Trusted Applications → Trusted Application.
2. Create a trusted application.
3. Deploy the trusted application using the Policy Management Web UI.

For more information about trusted applications, refer to Working With Trusted Applications.

Adding a trusted application to data store

Add a trusted application to data store by performing the following.

1. From the ESA Web UI, navigate to Policy Management → Data Stores.
   The list of all the data stores appear.
2. Select the required data store.
   The screen to edit the data store appears.
3. Under the Trusted Applications tab, click Add.
   The screen to add the trusted application appears.
4. Select the required trusted application and click Add.
5. Select the required policy and deploy it using the Policy Management Web UI.

For more information about adding a trusted application to data store, refer to Linking Data Store to a Trusted Application.

Installing the AP Java

Install the AP Java by performing the following.

1. To install the AP Java, refer to Application Protector Java Installation.

2. Verify if the AP Java is successfully installed by performing the following.
   a. Configure the application as a trusted application in the ESA.
   For more information about trusted applications, refer to Working With Trusted Applications.
   b. Initialize the AP Java.
   For more information about the AP Java initialization API, refer to getProtector.
   c. Run the GetVersion method using the following command to check the version of the installed AP Java.

   public java.lang.String getVersion()
   

   For more information about sample code to check the version number of the installed AP Java, refer to sample AP Java application for performing the protect, unprotect, and reprotect operations.

Running the AP Java APIs

After setting up the policy and trusted application, you can begin testing the AP Java APIs for protection, unprotection, and reprotection.

For more information about the AP Java APIs, refer to Application Protector Java APIs.

For more information about the AP Java return codes, refer to Application Protector API Return Codes.

To run this sample application, ensure that the Application Name in the Trusted Application is set as HelloWorld.

The following represents a sample AP Java application for performing the protect, unprotect, and reprotect operations.

/* Save the file as: HelloWorld.java
*
* This is sample program demonstrating the usage of Java SDK API
*
* Configure Trusted Application policy in ESA with
* - Application name: HelloWorld
* - Application user: <SYSTEM USER>
*
* Compiled as : javac -cp .:<PATH_TO_INSTALL_DIR>/sdk/java/lib/ApplicationProtectorJava.jar HelloWorld.java
* Run as :
* java -cp .:<PATH_TO_INSTALL_DIR>/sdk/java/lib/ApplicationProtectorJava.jar HelloWorld policyUser dataElement inputData
* 
* Example: java -cp .:/opt/protegrity/sdk/java/lib/ApplicationProtectorJava.jar HelloWorld user1 TE_AN_SLT13_L0R0_N "This is data"
*
* Use either Token Elements or NoEncryption as dataElement while running this code.
*/

import com.protegrity.ap.java.Protector;
import com.protegrity.ap.java.ProtectorException;
import com.protegrity.ap.java.SessionObject;

public class HelloWorld {

  public static void performProtectionOperation(
      String policyUser, String dataElement, String inputData) throws ProtectorException {

    String[] input = {inputData};
    String[] protectedOutput = new String[input.length];
    String[] unprotectedOutput = new String[input.length];

    // Initialize Java SDK Protector
    Protector protector = Protector.getProtector();

    // Create a new protection operation session for policyUser
    SessionObject session = protector.createSession(policyUser);

    // Get Java SDK and Core Version
    System.out.println(protector.getVersionEx());

    // Perform Protect Operation
    boolean res = protector.protect(session, dataElement, input, protectedOutput);
    if (!res) {
      System.out.println(protector.getLastError(session));
    } else {
      System.out.println("Protected Data:");
      for (String out : protectedOutput) {
        System.out.print(out + " ");
      }
      System.out.println();
    }

    // Perform Unprotect Operation
    res = protector.unprotect(session, dataElement, protectedOutput, unprotectedOutput);
    if (!res) {
      System.out.println(protector.getLastError(session));
    } else {
      System.out.println("Unprotected Data:");
      for (String out : unprotectedOutput) {
        System.out.print(out + " ");
      }
      System.out.println();
    }
  }

  public static void main(String[] args) throws ProtectorException {

    if (args.length == 3) {
      System.out.println(
          "Testing input data "
              + args[2]
              + " "
              + "with dataElement "
              + args[1]
              + " "
              + "and policyUser "
              + args[0]);

      performProtectionOperation(args[0], args[1], args[2]);

    } else {
      System.out.println(
          " Usage : java -cp .:<PATH_TO_INSTALL_DIR>/sdk/java/lib/ApplicationProtectorJava.jar HelloWorld PolicyUser DataElement Data");
      System.out.println(
          " Example : java -cp .:<PATH_TO_INSTALL_DIR>/sdk/java/lib/ApplicationProtectorJava.jar HelloWorld user1 TE_AN_SLT13_L0R0_N Protegrity");
      System.exit(0);
    }
  }
}

7 - Additional Topics

This section expands the core Application Protector (AP) Java documentation.

• Uninstalling AP Java on Linux involves removing binaries, configuration files, and dependencies.
• Understanding AP Java’s memory footprint is critical for performance tuning and resource allocation.

7.1 - Uninstalling the Application Protector

Uninstalling Application Protector (AP) Java from Linux

This section outlines the steps to uninstall the various components of AP Java from a Linux platform.

Uninstalling the Log Forwarder from Linux

Note: To preserve all the configurations while upgrading the Log Forwarder, ensure all the files present under the /opt/protegrity/logforwarder/data/config.d directory are backed up.

To uninstall the Log Forwarder from a Linux platform:

1. Navigate to the /opt/protegrity/logforwarder/bin directory.

2. Stop the Log Forwarder using the following command.

   ./logforwarderctrl stop
   

3. Delete the /opt/protegrity/logforwarder directory.

   The Log Forwarder is uninstalled.

Uninstalling the RP Agent from Linux

Note: Before uninstalling the RP Agent, ensure that all the files present under the /opt/protegrity/rpagent/data directory are backed up.

To uninstall the RP Agent from a Linux platform:

1. Navigate to the /opt/protegrity/rpagent/bin directory.

2. Stop the RP Agent using the following command.

   ./rpagentctrl stop
   

3. Delete the /opt/protegrity/rpagent directory.

   The RP Agent is uninstalled.

Uninstalling the AP Java from Linux

To uninstall the AP Java from a Linux platform:

1. Navigate to the /opt/protegrity/sdk directory.

2. Delete the /java directory.

   The AP Java is uninstalled.

7.2 - Memory Usage of the AP Java

The memory used for the different policy sizes using a sample HelloWorld java application is described in this section. This is a sample memory usage. You can use this as a reference for memory usage in the AP Java for different policy sizes.

Sample application

The following is a sample HelloWorld.java application.

/* HelloWorld.java
*
* This is sample program demonstrating the usage of Java SDK API
*
* Configure Trusted Application policy in ESA with
* - Application name: lib.HelloWorld
* - Application user: <SYSTEM USER>
*
* Compiled as : javac -cp .:<PATH_TO_INSTALL_DIR>/sdk/java/lib/ApplicationProtectorJava.jar HelloWorld.java
* Run as :
* java -cp .:<PATH_TO_INSTALL_DIR>/sdk/java/lib/ApplicationProtectorJava.jar HelloWorld policyUser dataElement inputData
*
* Use either Token Elements or NoEncryption as dataElement while running this code.
*/

package lib;

import com.protegrity.ap.java.Protector;
import com.protegrity.ap.java.ProtectorException;
import com.protegrity.ap.java.SessionObject;

public class HelloWorld {

  public static void performProtectionOperation(
      String policyUser, String dataElement, String inputData) throws ProtectorException {

    String[] input = {inputData};
    String[] protectedOutput = new String[input.length];
    String[] unprotectedOutput = new String[input.length];

    // Initialize Java SDK Protector
    Protector protector = Protector.getProtector();

    // Create a new protection operation session for policyUser
    SessionObject session = protector.createSession(policyUser);
    // Get Java SDK Version
    System.out.println("Java SDK Version:" + protector.getVersion());

    // Perform Protect Operation
    boolean res = protector.protect(session, dataElement, input, protectedOutput);
    if (!res) {
      System.out.println(protector.getLastError(session));
    } else {
      System.out.println("Protected Data:");
      for (String out : protectedOutput) {
        System.out.print(out + " ");
      }
      System.out.println();
    }

    // Perform Unprotect Operation
    res = protector.unprotect(session, dataElement, protectedOutput, unprotectedOutput);
    if (!res) {
      System.out.println(protector.getLastError(session));
    } else {
      System.out.println("Unprotected Data:");
      for (String out : unprotectedOutput) {
        System.out.print(out + " ");
      }
      System.out.println();
    }
  }

  public static void main(String[] args) throws ProtectorException {

    if (args.length == 3) {
      System.out.println(
          "Testing input data "
              + args[2]
              + " "
              + "with dataElement "
              + args[1]
              + " "
              + "and policyUser "
              + args[0]);

      performProtectionOperation(args[0], args[1], args[2]);

    } else {
      System.out.println(
          " Usage : java -cp .:<PATH_TO_INSTALL_DIR>/sdk/java/lib/ApplicationProtectorJava.jar HelloWorld PolicyUser DataElement Data");
      System.out.println(
          " Example : java -cp .:<PATH_TO_INSTALL_DIR>/sdk/java/lib/ApplicationProtectorJava.jarr HelloWorld user1 TE_AN_SLT13_L0R0_N"
              + " Protegrity");
      System.exit(0);
    }
  }
}

Expected memory usage

The process to find the policy size and expected memory usage for different policy sizes used by the java application is described in this section.

To find the policy size:

1. On Insights dashboard, under the Discover section, navigate to the troubleshooting index.
2. Search using the process.module.keyword: coreprovider filter.
3. Navigate to the logs with description as Policy successfully loaded. The additional_info.memoryUsed field depicts the policy size.

The following is the expected memory usage for different policy sizes used by the HelloWorld java application.

The process memory increases substantially for a few milliseconds when the application is running in the following cases:

• The policy is replaced with another policy
  
• Changes are made in the current policy

Conclusion

The results for memory required by various policy sizes using the sample HelloWorld.java application can be used to determine the memory requirements of the Java application.

7.3 - DevOps Approach for Application Protector Java

The DevOps approach enables immutable package deployment. It uses a REST API call to download packages from the ESA in an encrypted format.

Note: The RP Agent should not be installed for immutable package deployments using DevOps.

For more information about package deployment approaches, refer to Resilient Package Deployment.

A REST API call is used to download the package on your local machine. Configure the package path in the config.ini file within the DevOps section and the decryptor class.

If a downloaded path is overwritten, a new package will be reflected in the running application at the set time interval. This occurs when another package with the same name overwrites the existing one. This changes the protector’s behaviour. The protector no longer functions as an immutable protector.

1. A REST API call is used to download the policy from the ESA in an envelop encrypted format. A public key is created using a Key Management System (KMS) or Hardware Security Module (HSM). This public key must be passed to the REST API.
2. The ESA generates a JSON file for the package with policy.
3. The encrypted DEK needs to be decrypted to perform the security operations. A Decryptor class is implemented using the Decryptor interface, to decrypt the Data Encryption Key (DEK) using a private key.

Before you begin

Ensure the following prerequisites are met:

• The installation of the RP Agent is not required for immutable package deployment using the DevOps approach.
• The decryptor parameter must have a fully qualified name of the decryptor class.
  A Decryptor class needs to be implemented using the Decryptor interface, which decrypts the Data Encryption Key (DEK) using a private key. It returns the decrypted DEK in bytes.
  For more information on the decryptor interface of AP Java, refer to Configuring the Decryptor interface.
  For more information on the decryptor interface of AP Python, refer to Configuring the Decryptor interface.
  
• The data store is properly configured before exporting your Application Protector policy. Define allowed servers for seamless policy deployment and secure access control.
  For more information about configuring a data store, refer to -
  • Creating a Data Store
  • Adding Allowed Servers for the Data Store

AP Java

Using the DevOps approach

Perform the following steps to use the DevOps approach for immutable package deployment.

1. Add the [devops] parameter in the config.ini file.
   Ensure the decryptor class has a fully qualified domain name.

   [devops]
   package.path = /path/to/policyFile
   decryptor = packageName.DecryptorClassName
   

   The following is an example for adding the [devops] parameter in the config.ini file.

   [devops]
   package.path = /opt/policies/policy1.json
   decryptor = com.protegrity.apjava.test.RSADecryptor
   

Note: For ESA 10.2.0 and later, Application Protector DevOps must use the Encrypted Resilient Package REST APIs using GET method. The legacy Export API using POST method is deprecated and not supported for Teams (PPC). The deprecated API remains supported only for the Enterprise edition for backward compatibility.

For more information about exporting Resilient Package using POST method for 10.0.1 and 10.1.0 ESA, refer to Using the Resilient Package REST APIs.

For more information about exporting Resilient Package using GET method for 10.2 ESA, refer to Using the Resilient Package REST APIs.

For more information about exporting Resilient Package using GET method for PPC, refer to Using the Encrypted Resilient Package REST APIs.

Sample code for DevOps approach

The sample code for DevOps approach for various Application Protectors using different cloud platforms is provided in this section.

DevOps approach for AP Java

The sample code for DevOps approach for the AP Java using different cloud platforms is provided in this section.

Configuring the Decryptor interface

A Decryptor class must implement the DEKDecryptor interface to decrypt the DEK. This interface includes the decrypt method. The decrypt method provides keyLabel, algorithmId, and encDek parameters. The decrypted DEK must be returned in byte[] format.

The following is a sample code for implementing the DEKDecryptor interface.

package com.protegrity.jcorelite.decryptor;

import com.protegrity.jcorelite.constants.KEK_ALGO;
import com.protegrity.jcorelite.exceptions.PtyDecryptorException;

public interface DEKDecryptor {

    public byte[] decrypt(String keyLabel, KEK_ALGO algorithmId, byte[] encDek) throws PtyDecryptorException;
}

Using AWS

The following is a sample implementation using the private key from AWS KMS.

/* Sample Application for decrypting encrypted DEK using AWS KMS keys.
 *
 * [Protegrity Prerequisite]
 * Create an asymmetric KMS key in the AWS KMS.
 * Use the public key of the generated asymmetric key to download ESA policy using the curl request.
 *
 * [AWS Prerequisite]
 * Install AWS CLI.
 * Ensure that the AWS credentials and configurations are properly set before running the code that interacts with the AWS services.
 * There are multiple ways to configure the AWS credentials and configurations.
 * 1. AWS CLI configuration:
 *    Command: $aws configure
 *    A prompt appears to enter the following information:
 *     - AWS Access Key ID: The access key associated with the AWS account or IAM user.
 *     - AWS Secret Access Key: The secret key associated with the access key.
 *     - Default region name: The AWS region to use by default.
 *     - Default output format: The format for CLI command output.
 *    The AWS credentials and configuration settings are set up in the ~/.aws/credentials and ~/.aws/config files.
 *  
 * 2. Environment variables:
 *    The AWS credentials using environment variables can be set using the following commands.
 *       export AWS_ACCESS_KEY_ID = "your_access_key_id"
 *       export AWS_SECRET_ACCESS_KEY = "your_secret_access_key"
 *       export AWS_REGION= "your_aws_default_region"
 *
 * [Java Prerequisite]
 * Add AWS KMS Java SDK as part of your dependency:
 *      implementation 'com.amazonaws:aws-java-sdk-kms:1.12.423'
 */
 
import com.amazonaws.services.kms.AWSKMS;
import com.amazonaws.services.kms.AWSKMSClientBuilder;
import com.amazonaws.services.kms.model.DecryptRequest;
import com.amazonaws.services.kms.model.DecryptResult;
import com.protegrity.jcorelite.constants.KEK_ALGO;
import com.protegrity.jcorelite.decryptor.DEKDecryptor;
import com.protegrity.jcorelite.exceptions.PtyDecryptorException;
import java.nio.ByteBuffer;
import java.util.Base64;
 
public class AWSKMSDecryptor implements DEKDecryptor {
    private static final String KEY_ID  = "3068b3ef-4924-4be5-9e9a-440b418553b3";
    public byte[] decrypt(String keyLabel, KEK_ALGO algorithm, byte[] encDek) throws PtyDecryptorException {
        getEncoder().encodeToString(encDek));
        /* create an AWS KMS client */
        AWSKMS kmsClient = AWSKMSClientBuilder.standard().build();
        /* wrap byte array into buffer */
        ByteBuffer ciphertextBuffer = ByteBuffer.wrap(encDek);
        /* decrypt request */
        DecryptRequest decryptRequest =  new DecryptRequest().withCiphertextBlob(ciphertextBuffer).withEncryptionAlgorithm("RSAES_OAEP_SHA_256").withKeyId(KEY_ID);
        /* decrypt the ciphertext */
        DecryptResult decryptResult = kmsClient.decrypt(decryptRequest);
        /* get the decrypted data */
        ByteBuffer decryptedBuffer = decryptResult.getPlaintext();
        /* buffer to byte array */
        byte[] decryptedDek = decryptedBuffer.array();
       
        return decryptedDek;
       
    }    
}

Using Azure

The following is a sample implementation using the private key from Azure Key Vault.

/*
* Sample Application for decrypting encrypted DEK using Azure Key Vault
*
* [Azure Prerequisite]
* Install azure cli
* Login to azure :
  az login --use-device-code
*
* [Protegrity Prerequisite]
* For creating a key in Azure Key Vault using Azure CLI, refer :
  https://learn.microsoft.com/en-us/azure/key-vault/keys/quick-create-cli 
* Download the public key from the key vault : 
  az keyvault key download --vault-name test -n testkey -e PEM -f publickey.pem
* Replace all the new lines with \n in publickey.pem
* Public key is now ready to be used for downloading your ESA policy
* Azure supports RSA1_5, RSA_OAEP and RSA_OAEP_256 algorithms, 
  whose correspoding names in REST API call are RSA1_5, RSA-OAEP-SHA1 and RSA-OAEP-256 respectively
  Refer : https://learn.microsoft.com/en-us/java/api/com.azure.security.keyvault.keys.cryptography.models.encryptionalgorithm?view=azure-java-stable
* Make sure that decrypt permission is present for the key vault : 
  az keyvault set-policy -n "test" --key-permissions decrypt --object-id 7e821e4c-e0ad-4a6f-aa26-f445c7c7e3ea
* To get the private key URI from azure key vault, refer :
  https://learn.microsoft.com/en-us/azure/key-vault/keys/quick-create-cli
*
* [Java Prerequisite]
* Add Azure key vault and azure identity as part of your dependency
  artifactIds : azure-security-keyvault-keys, azure-identity
*
* The below code demonstrates decryption of encrypted DEK using private key URI received from Azure key vault
*/

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.keys.cryptography.CryptographyClient;
import com.azure.security.keyvault.keys.cryptography.CryptographyClientBuilder;
import com.azure.security.keyvault.keys.cryptography.models.EncryptionAlgorithm;
import com.azure.security.keyvault.keys.cryptography.models.EncryptResult;
import com.azure.security.keyvault.keys.cryptography.models.DecryptResult;

import com.protegrity.jcorelite.constants.KEK_ALGO;
import com.protegrity.jcorelite.decryptor.DEKDecryptor;
import com.protegrity.jcorelite.exceptions.PtyDecryptorException;

public class AzureDecryptor2 {
    private static final String KEY_ID  = "https://test.vault.azure.net/keys/testkey/aaf3861366a24b1bb4f6871eb11afafe";
    
    public byte[] decrypt(String keyLabel, KEK_ALGO algorithm, byte[] encDek) throws PtyDecryptorException {
        /*
         * Instantiate a CryptographyClient that will be used to call the service.
         * Notice that the client is using
         * default Azure credentials. For more information on this and other types of
         * credentials, see this document:
         * https://docs.microsoft.com/java/api/overview/azure/identity-readme?view=azure
         * -java-stable.
         * 
         * To get started, you'll need a key identifier for a key stored in a key vault.
         * See the README
         * (https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/keyvault/azure-
         * security-keyvault-keys/README.md)
         * for links and instructions.
         */
        CryptographyClient cryptoClient = new CryptographyClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .keyIdentifier(KEY_ID)
                .buildClient();
        
        DecryptResult decryptResult = cryptoClient.decrypt(EncryptionAlgorithm.RSA_OAEP, encDek);

        return decryptResult.getPlainText();
    }  
}

Using GCP

The following is a sample implementation using the private key from Google Cloud KMS.

/*
* Sample Application decrypting encrypted DEK using Google Cloud Key Management
*
* [Protegrity Prerequisite]
* Create an asymmetric key using Google Cloud Key Management with key purpose of ASYMMETRIC_DECRYPT.
* This example uses a key with algorithm 2048 bit RSA key OAEP Padding - SHA256 Digest
* Now use the public key of the generated asymmetric key to download your ESA policy
*
* Example curl command to download policy
* curl --location 'https://{ESA_IP}/pty/v1/rps/export?version=1&coreversion=1' \
       --header 'accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'Authorization: Basic' \
       --data '{
         "kek":{
         "publicKey":{
         "label": "LABEL_NAME",
         "algorithm": "ALGORITHM_NAME",
         "value": "-----BEGIN PUBLIC KEY-----
                   [asymmetric public key using Google Cloud Key Management]
                   -----END PUBLIC KEY-----"}
       }
       }'
*
* The below code demonstrates decrypting encrypted DEK using key generated using Google Cloud Key Management
*
* [Google Prerequisite]
* Google Cloud Account with Google Cloud Key Management enabled
* Install gcloud cli
  gcloud auth application-default command creates application_default_credentials.json
*
* [Java Prerequisite]
* Add Google Cloud KMS as part of your dependency
  implementation 'com.google.cloud:google-cloud-kms:<version_number>'
*
* Check Google Cloud API Documentation for more information
*/

package com.protegrity.test;

import com.google.cloud.kms.v1.AsymmetricDecryptResponse;
import com.google.cloud.kms.v1.CryptoKeyVersionName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.protobuf.ByteString;
import com.protegrity.jcorelite.constants.KEK_ALGO;
import com.protegrity.jcorelite.exceptions.PtyDecryptorException;
import java.io.IOException;

public class GCPKMSDecryptor {

  public byte[] decryptAsymmetricKey(byte[] encDek) throws IOException {
    // Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String keyId = "my-key";
    String keyVersionId = "123";
    return decryptAsymmetricKey(projectId, locationId, keyRingId, keyId, keyVersionId, encDek);
  }

  // Decrypt data that was encrypted using the public key component of the given
  // key version.
  public byte[] decryptAsymmetricKey(
      String projectId,
      String locationId,
      String keyRingId,
      String keyId,
      String keyVersionId,
      byte[] ciphertext)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the key version name from the project, location, key ring, key,
      // and key version.
      CryptoKeyVersionName keyVersionName =
          CryptoKeyVersionName.of(projectId, locationId, keyRingId, keyId, keyVersionId);
      // Decrypt the ciphertext.
      AsymmetricDecryptResponse response =
          client.asymmetricDecrypt(keyVersionName, ByteString.copyFrom(ciphertext));
      return response.getPlaintext().toByteArray();
    }
  }

  public byte[] decrypt(String keyLabel, KEK_ALGO algorithm, byte[] encDek)
      throws PtyDecryptorException, IOException {
    return decryptAsymmetricKey(encDek);
  }
}

7.4 - Application Protector API Return Codes

When an application is developed using the APIs of the Protegrity Application Protector Suite, you may encounter the Application Protector API Return Codes. For more information about log return codes, refer to Log return codes.

Sample Log for AP Return Codes

The following is a sample log generated in Discover on the Audit Store Dashboards in the ESA.

Protection audit logs are stored in the Audit Store. Select the pty_insight_*audit* index to view the protection logs.

For more information about viewing the logs, refer to Working with Discover.

7.5 - Config.ini file for Application Protector

The Application Protector can be configured using the config.ini file. By default, this file is located in the <installation directory>/sdk/<protector>/data/ directory.

The various configurations required for setting up the Application Protector are described in this section.

Sample config.ini file

The following represents a sample config.ini file.

# -----------------------------
# Protector configuration
# ----------------------------- 
[protector]

# Cadence determines how often the protector connects with shared memory to fetch the policy updates in background.
# Default is 60 seconds. So by default, every 60 seconds protector tries to fetch the policy updates.
#
# Default 60.
cadence = 60

# The time during which an session object is valid. Default = 15 minutes.
session.sessiontimeout = 15

###############################################################################
# Log Provider Config
###############################################################################
[log]

# In case that connection to fluent-bit is lost, set how audits/logs are handled
# 
# drop  : (default) Protector throws logs away if connection to the fluentbit is lost
# error : Protector returns error without protecting/unprotecting 
#         data if connection to the fluentbit is lost
mode = drop

# Host/IP to fluent-bit where audits/logs will be forwarded from the protector
#
# Default localhost
host = localhost

Different configurations for Application Protector

The following are the various configurations:

Protector configurations

• cadence: The interval at which the protector synchronizes with the shared memory for fetching the package with policy. The default value for cadence is 60 seconds. The maximum and minimum value that can be set for cadence are 86400 seconds (24 hours) and 1 respectively.
  For more information about the policy deployment with different cadence configurations, refer to Policy Deployment.
  For more information about the Resilient Package sync configuration parameters, refer to Resilient Package Sync Configuration Parameters.
  For more information about changing protector status interval, refer to Resilient Package Status Configuration Parameter.
• session.sessiontimeout: The time during which a session object is valid. The default value for session.sessiontimeout is 15 minutes.

  Note: The session.sessiontimeout parameter is a feature of AP Java and not valid for AP Python and AP .Net.

Log Provider configurations

• mode: This describes how the protector logs are handled if you lose connection to the Log Forwarder host, can be set to one of the following values:
  • drop: The logs are dropped when the connection to the Log Forwarder is lost. The default mode is drop.
  • error: The data security operations are stopped and an error is generated when the connection to the Log Forwarder is lost.
• host: The Log Forwarder hostname or IP address where the logs will be forwarded from the protector. The default host for Log Forwarder is localhost.

For more information about the configuration parameters for forwarding the audits and logs, refer to Configuration Parameters for Forwarding Audits and Logs.

7.6 - Multi-node Application Protector Architecture

The multi-node Application Protector (AP) architecture, its individual components, and how logs are collected using the Log Forwarder are described in this section.

The following figure describes the multi-node AP architecture.

For example, some AP nodes are connected to an ESA, which includes the Audit Store component. Each AP node contains a Log Forwarder, RP Agent, and AP instance for sending logs to the ESA.

Protector: The AP can be configured using the config.ini file.
For more information about the configurations, refer to Config.ini file for Application Protector.

RP Agent: The RP Agent downloads the package with policy from the ESA, which is used by the protector to perform the protect, unprotect, or reprotect operations. It checks for the updates in the policy at set intervals and downloads the latest policy package when an update is detected.

Log Forwarder: The Log Forwarder component collects the logs from the AP and forwards them to the Audit Store. The Log Forwarder uses the 15780 port which is configurable to transport protection and audit logs to the ESA. The ESA receives the logs and stores it in the Audit Store.