This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Application Protector Java APIs

The various APIs of the AP Java.

1: Using the AP 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.

AP Java APIs

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.

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)

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.

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

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

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.

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

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

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.

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

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)

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

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)

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

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)

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

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)

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

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)

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

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

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.

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

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.

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

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.

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

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.

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

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

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

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

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.

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

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

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.

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

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

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.

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

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)

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

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)

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

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)

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

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)

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

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.

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

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

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

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.

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

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

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

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

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

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)

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)

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

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)

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

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)

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

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)

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

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)

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

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.

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

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

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.

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

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

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.

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

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

1 - Using the AP Java APIs

Sample application for the AP Java.

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.

Create the data elements and data store in the Policy Management on the ESA Web UI.
Create the member sources and roles.
Configure the policy.
Configure the trusted application.
Add a trusted application to the data store.
Install the AP Java.
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.

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

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

From the ESA Web UI, navigate to Policy Management → Policies & Trusted Applications → Policies.
Click Add New Policy.
The New Policy screen appears.
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.
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.

From the ESA Web UI, navigate to Policy Management → Policies & Trusted Applications → Trusted Application.
Create a trusted application.
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.

From the ESA Web UI, navigate to Policy Management → Data Stores.
The list of all the data stores appear.
Select the required data store.
The screen to edit the data store appears.
Under the Trusted Applications tab, click Add.
The screen to add the trusted application appears.
Select the required trusted application and click Add.
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.

To install the AP Java, refer to Application Protector Java Installation.
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.

Before running the following program, update the HelloWorld.java file with the policy username and data element name.

Compile and Run the Sample Application

Compile the sample application using the following command.

cd /opt/protegrity/sdk/java/lib
javac -cp .:ApplicationProtectorJava.jar HelloWorld.java

Run the sample application using the following command.

java -cp .:ApplicationProtectorJava.jar HelloWorld

By default, the config.ini file is located in the SDK data directory /opt/protegrity/sdk/java/data and is picked up automatically at runtime.

If the config.ini file is moved to a different location, specify its path explicitly when running the application:

java -Dconfig.path=/opt/config.ini -cp .:ApplicationProtectorJava.jar HelloWorld

If config.ini is present in the same directory as ApplicationProtectorJava.jar and jcorelite.plm, the SDK loads it automatically and the -Dconfig.path option is not required.

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);
    }
  }
}