MapReduce APIs

This section describes the MapReduce APIs available for protection and unprotection in the Big Data Protector to build secure Big Data applications.

Warning: The Protegrity MapReduce protector only supports bytes converted from the string data type.

If any other data type is directly converted to bytes and passed as input to the API that supports byte as input and provides byte as output, then data corruption might occur.

Caution: If you are using the Protect, or Unprotect, or Reprotect API which accepts byte as input and provides byte as output, then ensure that you pass the charset argument in APIs with the charset used to encode the string input data type.
For example, if the input String was encoded using the UTF-16LE charset, then ensure to pass the “UTF-16LE” charset argument in the ByteIn or ByteOut APIs.

Note: If you perform a security operation on a single data item, then an exception appears in case of any error. Similarly, if you perform a security operation on bulk data, then an exception appears in case of any error except for the error codes 22, 23, and 44. Instead of an error message, the UDFs return an error list for the individual items in the bulk data. For more information about the API error return codes, refer Return Codes for the Big Data Protector.

If you are using the Bulk APIs for the MapReduce protector, then the following two modes for error handling and return codes are available:

• Default mode: Starting with the Big Data Protector, version 6.6.4, the Bulk APIs in the MapReduce protector will return the detailed error and return codes instead of 0 for failure and 1 for success. In addition, the MapReduce jobs involving Bulk APIs will provide error codes instead of throwing exceptions.
  For more information about the return codes for the Big Data Protector, refer .

• Backward compatibility mode: If you need to continue using the error handling capabilities provided with Big Data Protector, version 6.6.3 or lower, that is 0 for failure and 1 for success, then you can set this mode.

Sample Code Usage

The MapReduce sample program, described in this section, is an example on how to use the Protegrity MapReduce protector APIs. The sample program utilizes the following two Java classes:

• ProtectData.java – is the main class that calls the Mapper job.
• ProtectDataMapper.java – is the Mapper class that contains the logic to fetch the input data and store the protected content as output.

Main Job Class – ProtectData.java

ProtectData.java

package com.protegrity.samples.mapreduce;

import org.apache.hadoop.conf.Configuration;
import org.apache.hadoop.conf.Configured;
import org.apache.hadoop.fs.Path;
import org.apache.hadoop.io.NullWritable;
import org.apache.hadoop.io.Text;
import org.apache.hadoop.mapreduce.Job;
import org.apache.hadoop.mapreduce.lib.input.FileInputFormat;
import org.apache.hadoop.mapreduce.lib.input.TextInputFormat;
import org.apache.hadoop.mapreduce.lib.output.FileOutputFormat;
import org.apache.hadoop.mapreduce.lib.output.TextOutputFormat;
import org.apache.hadoop.util.Tool;
import org.apache.hadoop.util.ToolRunner;

public class ProtectData extends Configured implements Tool {
  @Override
  public int run(String[] args) throws Exception {
    //Create the Job 
    Job job = new Job(getConf(), "ProtectData");

    //Set the output key and value class
    job.setOutputKeyClass(NullWritable.class);
    job.setOutputValueClass(Text.class);

    //Set the output key and value class
    job.setMapOutputKeyClass(NullWritable.class);
    job.setMapOutputValueClass(Text.class);

    //Set the Mapper class which will perform the protect job
    job.setMapperClass(ProtectDataMapper.class);

    //Set number of reducer task
    job.setNumReduceTasks(0);

    //Set the input and output Format class
    job.setInputFormatClass(TextInputFormat.class);
    job.setOutputFormatClass(TextOutputFormat.class);

    //Set the jar class    
    job.setJarByClass(ProtectData.class);

    //Store the input path and print the input path
    Path input = new Path(args[0]);
    System.out.println(input.getName());
    //Store the output path and print the output path 
    Path output = new Path(args[1]);
    System.out.println(output.getName());

    //Add input and set output path
    FileInputFormat.addInputPath(job, new Path(args[0]));
    FileOutputFormat.setOutputPath(job, new Path(args[1]));

    //Call the job
    return job.waitForCompletion(true) ? 0 : 1;
  }

  public static void main(String args[]) throws Exception {
    System.exit(ToolRunner.run(new Configuration(), new ProtectData(), args));
  }
}

Mapper Class – ProtectDataMapper.java

ProtectDataMapper.java

package com.protegrity.samples.mapreduce;

import java.io.IOException;
import java.util.StringTokenizer;
import org.apache.hadoop.io.NullWritable;
import org.apache.hadoop.io.Text;
import org.apache.hadoop.mapreduce.Mapper;
//Need to import the ptyMapReduceProtector class to use the Protegrity MapReduce protector
import com.protegrity.hadoop.mapreduce.ptyMapReduceProtector;

//Create the Mapper class i.e. ProtectDataMapper which will extends the Mapper Class
public class ProtectDataMapper extends Mapper<Object, Text, NullWritable, Text> {

    //Declare the member variable for the ptyMapReduceProtector class
    private ptyMapReduceProtector mapReduceProtector;
    //Declare the Array of Data Elements which will be required to do the protection/unprotection
    private final String[] data_element_names = { "TOK_NAME", "TOK_PHONE", "TOK_CREDIT_CARD", "TOK_AMOUNT" };

    //Initialize the mapreduce protector i.e ptyMapReduceProtector in the default constructor
    public ProtectDataMapper() throws Exception {
        // Create the new object for the class ptyMapReduceProtector
        mapReduceProtector = new ptyMapReduceProtector();
        // Open the session using the method " openSession("0") "
        int openSessionStatus = mapReduceProtector.openSession("0");
    }

    //Override the map method to parse the text and process it line by line
    //Split the inputs separated by delimiter "," in the line
    //Apply the protect/unprotect operation
    //Create the output text which will have protected/unprotected outputs separated by delimiter ","
    //Write the output text to the context
    @Override
    public void map(Object key, Text value, Context context) throws IOException,
            InterruptedException
    {
        // Store the line in a variable strOneLine
        String strOneLine = value.toString();
        // Split the inputs separated by delimiter "," in the line
        StringTokenizer st = new StringTokenizer(strOneLine, ",");
        // Create the instance of StringBuilder to store the output
        StringBuilder sb = new StringBuilder();
        // Store the no of inputs in a line
        int noOfTokens = st.countTokens();
        if (mapReduceProtector != null) {
            //Iterate through the string token and apply the protect/unprotect operation
            for (int i = 0; st.hasMoreElements(); i++) {
                String data = (String)st.nextElement();
                if(i == 0) {
                    sb.append(new String(data));
                } else {
                    //To protect data, call the function protect method with parameters data element and input data in bytes
                    //mapReduceProtector.protect( <Data Element> , <Data in bytes> )
                    //Output will be returned in bytes
                    //To unprotect data, call the function unprotect method with parameters data element and input data in bytes
                    //mapReduceProtector.unprotect( <Data Element> , <Data in bytes> )
                    //Output will be returned in bytes
                    byte[] bResult =
                            mapReduceProtector.protect(data_element_names[i-1], data.trim().getBytes());
                    if (bResult != null) {
                        // Store the result in string and append it to the output sb
                        sb.append(new String(bResult));
                    }
                    else {
                        // If output will be null, then store the result as "cryptoError" and append it to the output sb
                        sb.append("cryptoError");
                    }
                }
                if(i < noOfTokens -1 ) {
                    // Append delimiter "," at the end of the processed result
                    sb.append(",");
                } } }
        // write the output text to context
        context.write(NullWritable.get(), new Text(sb.toString()));
    }
    //clean up the session and objects
    @Override
    protected void finalize() throws Throwable {
        //Close the session
        int closeSessionStatus = mapReduceProtector.closeSession();
        mapReduceProtector = null;
        super.finalize();
    }
}

openSession( )

This method opens a new user session for protect and unprotect operations. It is a good practice to create one session per user thread.

Warning: This API is redundant and will be removed in the future releases.

Signature:

public synchronized int openSession(String parameter)

Parameters:

• parameter: An internal API requirement that should be set to 0.

Result:

• 1: The function returns 1 if the session is successfully created.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector(); 
int openSessionStatus = mapReduceProtector.openSession("0");

Exception and Error Codes:
The function throws the ptyMapRedProtectorException exception if the session creation fails.

closeSession ()

This function closes the current open user session. Every instance of ptyMapReduceProtector opens only one session, and a session ID is not required to close it.

Warning: This API is redundant and will be removed in the future releases.

Signature:

public synchronized int closeSession()

Parameters:

• None
  

Result:
The function returns:

• 1 - if the session is successfully closed.
• 0 - if the session closure is a failure.

Example

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector(); 
int openSessionStatus  = mapReduceProtector.openSession("0"); 
int closeSessionStatus = mapReduceProtector.closeSession();

Exception and Error Codes:

• None
  

getVersion()

The function returns the current version of the protector.

Signature:

public String getVersion()

Parameters:

• None

Result:

• The function returns the current version of the protector.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
String version = mapReduceProtector.getVersion();

getVersionExtended()

The function returns the extended version information of the protector.

Signature:

public String getVersionExtended()

Parameters:

• None

Result:

The function returns a String in the following format:

"BDP: <1>; JcoreLite: <2>; CORE: <3>;"

where:

• 1 - Current version of Protector
• 2 - Jcorelite library version
• 3 - Core library version

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
String extendedVersion = mapReduceProtector.getVersionExtended();

checkAccess()

The function checks the access of the user for the specified data element(s).

Signature:

public boolean checkAccess(String dataElement, byte bAccessType, String... newDataElement)

Parameters:

• dataElement: Specifies the name of the data element. (old data element when checking for reprotect access)

• bAccessType: Specifies the type of the access of the user for the data element(s).

• newDataElement: Specifies the name of the new data element when checking for reprotect access.

  The following are the different values for the bAccessType variable:

  Access	Value
  PROTECT	0x06
  UNPROTECT	0x07
  REPROTECT	0x08

Result:

• The function returns true if the user has access to the data element(s) for the specified operation. Else, the function returns false.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
byte bAccessType = 0x06;
boolean isAccess = mapReduceProtector.checkAccess("DE_PROTECT" , bAccessType );

checkAccess() with Permission enum argument

The function checks the access of the user for the specified data element(s).

Signature:

public boolean checkAccess(String dataElement, Permission permission, String... newDataElement)

Parameters:

• dataElement: Specifies the name of the data element. (old data element when checking for reprotect access).

• permission: Specifies the type of the access using BDPProtector.Permission enum of the user for the data element(s).

• newDataElement: Specifies the name of the new data element when checking for reprotect access.

  The following are the different values for the permission variable:

  Access	Value
  PROTECT	Permission.PROTECT
  UNPROTECT	Permission.UNPROTECT
  REPROTECT	Permission.REPROTECT

Result:

• The function returns true if the user has access to the data element(s) for the specified operation. Else, the function returns false.

Example:

import com.protegrity.bdp.protector.BDPProtector.Permission;
String dataElement = "dataelement"; 

ptyMapReduceProtector protector = new ptyMapReduceProtector();

boolean accessProtectType = protector.checkAccess(dataElement, Permission.PROTECT);
boolean accessReprotectType = protector.checkAccess(dataElement, Permission.REPROTECT,dataElement);
boolean accessUnprotectType = protector.checkAccess(dataElement, Permission.UNPROTECT);

protect() - Byte array data

The function protects the data provided as a byte array. The type of protection applied is defined by the dataElement.

Note: For Date and Datetime type of data elements, the protect API returns an invalid input data error if the input value falls between the non-existent date range 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 the section Date and Datetime tokenization in Protection Method Reference.

Signature:

public byte[] protect(String dataElement, byte[] data, String... CharSet)

Parameters:

• dataElement: Specifies the name of the data element to protect the data.
• data: Is the byte array of data to be protected.
• charset: Specifies the charset of the input data. The applicable charsets are UTF-8 (default), UTF-16LE, and UTF-16BE.

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

Note: If you are using the Protect API which accepts byte as input and provides byte as output, then ensure that when unprotecting the data, the Unprotect API, with byte as input and byte as output is utilized. In addition, ensure that the byte data being provided as input to the Protect API has been converted from a string data type only.

Note: When the charset of input byte[] data is UTF-16LE or UTF-16BE, ensure to pass the charset argument.

Result:

• The function returns the byte array of protected data.

Exception:

• The function throws the ptyMapRedProtectorException in case of a failure to protect the data.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
byte[] protectedResult = mapReduceProtector.protect("DE_PROTECT", "protegrity".getBytes(), "UTF-8");

Supported Protection Methods:

protect() - Int data

The function protects the data provided as an int. The type of protection applied is defined by the dataElement.

Signature:

public int protect(String dataElement, int data)

Parameters:

• dataElement: Specifies the name of the data element to be protected.
• data: Specifies the data in the integer format to be protected.

Result:

• The function returns the protected int data.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
int bResult = mapReduceProtector.protect("DE_PROTECT",1234);

Exception:

• The function throws the ptyMapRedProtectorException exception in case of failure to protect the data.

Supported Protection Methods:

protect() - Long data

This function protects the data provided as long. The type of protection applied is defined by dataElement.

Signature:

public long protect(String dataElement, long data)

Parameters:

• dataElement: Specifies the name of the data element used to protect the data.
• data: Specifies the data in the long format to be protected.

Result:

• The function returns the protected data in the long format.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
long bResult = mapReduceProtector.protect("DE_PROTECT",123412341234);

Exception:

• The function throws the ptyMapRedProtectorException exception in case of failure to protect the data.

Supported Protection Methods:

unprotect() - Byte array data

This function returns the data in its original form.

Note: For Date and Datetime type of data elements, the protect API returns an invalid input data error if the input value falls between the non-existent date range 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 the section Date and Datetime tokenization in Protection Method Reference.

Signature:

public byte[] unprotect(String dataElement, byte[] data, String... charset)

Parameters:

• dataElement: Is the name of data element to be unprotected.
• data: Is an array of data to be unprotected.
• charset: Specifies the charset of the input data. The applicable charsets are UTF-8 (default), UTF-16LE, and UTF-16BE.

Note: When the charset of input byte[] data is UTF-16LE or UTF-16BE, ensure to pass the charset argument.

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

Result:
The function returns a byte array of unprotected data.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector(); 
byte[] protectedResult   = mapReduceProtector.protect( "DE_PROTECT_UNPROTECT", "protegrity".getBytes(), "UTF-8" ); 
byte[] unprotectedResult = mapReduceProtector.unprotect( "DE_PROTECT_UNPROTECT", protectedResult, "UTF-8" ); 

Exception:

• The function throws the ptyMapRedProtectorException exception in case of a failure to unprotect the data.

Supported Protection Methods:

unprotect() - Int data

This function returns the data in its original form.

Signature:

public int unprotect(String dataElement, int data)

Parameters:

• dataElement: Specifies the name of data element to unprotect the data.
• data: Is the data in the int format to unprotect.

Result:

• The function returns the unprotected int data.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
int protectedResult = mapReduceProtector.protect( "DE_PROTECT_UNPROTECT",1234);
int unprotectedResult = mapReduceProtector.unprotect("DE_PROTECT_UNPROTECT", protectedResult);

Exception:
The function throws the ptyMapRedProtectorException exception in case of a failure to unprotect the data.

Supported Protection Methods:

unprotect() - Long data

This function returns the data in its original form.

Signature:

public long unprotect(String dataElement, long data)

Parameters:

• dataElement: Specifies the name of data element to unprotect the data.
• data: Is the data in the long format to unprotect.

Result:

• The function returns the unprotected long data.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
long protectedResult = mapReduceProtector.protect( "DE_PROTECT_UNPROTECT", 123412341234 );
long unprotectedResult = mapReduceProtector.unprotect("DE_PROTECT_UNPROTECT", protectedResult );

Exception:
The function throws the ptyMapRedProtectorException exception in case of a failure to unprotect the data.

Supported Protection Methods:

bulkProtect() - Byte array data

This is used when a set of data needs to be protected in a bulk operation. It helps to improve performance.

Note: For Date and Datetime type of data elements, the protect API returns an invalid input data error if the input value falls between the non-existent date range 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 the section Date and Datetime tokenization in the Protection Method Reference.

Signature:

public byte[][] bulkProtect(String dataElement, List<Integer> errorIndex, byte[][] inputDataItems, String... charset)

Parameters:

• dataElement: Specifies the name of data element used to protect the data.
• errorIndex: Is a list used to store all the error indices encountered while protecting each data entry in inputDataItems.
• inputDataItems: Is a two-dimensional array to store the bulk data for protection.
• charset: Specifies the charset of the input data. The applicable charsets are UTF-8 (default), UTF-16LE, and UTF-16BE.

Result:

• The function returns a two-dimensional byte array of protected data.
• If the Backward Compatibility mode is not set, then the appropriate error code appears. For more information about the return codes, refer PEP Log Return Codes and PEP Result Codes.
• If the Backward Compatibility mode is set, then the Error Index includes one of the following values, per entry in the bulk protect operation:
  • 1: The protect operation for the entry is successful.
  • 0: The protect operation for the entry is unsuccessful.
    For more information about the failed entry, view the logs available in the ESA forensics.
  • Any other value or garbage return value: The protect operation for the entry is unsuccessful. For more information about the failed entry, view the logs available in ESA forensics.

Example:

 ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector(); 
 List<Integer> errorIndex = new ArrayList<Integer>();

 byte[][] protectData     = {"protegrity".getBytes(), "protegrity".getBytes(), "protegrity".getBytes(), "protegrity".getBytes()}; 

 byte[][] protectedData = mapReduceProtector.bulkProtect( "DE_PROTECT", errorIndex, protectData, "UTF-8" );

 System.out.print("Protected Data: ");    
 for(int i = 0; i < protectedData.length; i++)
     {  
         //THIS WILL PRINT THE PROTECTED DATA
         System.out.print(protectedData[i] == null ? null : new String(protectedData[i]));
         if(i < protectedData.length - 1)
         {
         System.out.print(",");
         }
     }

 System.out.println("");         
 System.out.print("Error Index: ");
 for(int i = 0; i < errorIndex.size(); i++)
 {
  System.out.print(errorIndex.get( i ));
  if(i < errorIndex.size() - 1)
  {
    System.out.print(",");
  }
 }
 //ABOVE CODE WILL PRINT THE ERROR INDEXES

Exception:
The function throws the ptyMapRedProtectorException if an error is encountered during bulk protection of the data.

Supported Protection Methods:

bulkProtect() - Int data

The function is used when a set of data needs to be protected in a bulk operation. It helps to improve performance.

Signature:

   public int[] bulkProtect(String dataElement, List <Integer> errorIndex, int[] inputDataItems)

Parameters:

• dataElement: Specifies the name of data element to protect the data..
• errorIndex: Is a list used to store all the error indices encountered while protecting each data entry in input Data Items.
• inputDataItems: Is an array to store the bulk int data for protection.

Result:

• The function returns the int array of protected data.

• If the Backward Compatibility mode is not set, then the appropriate error code appears. For more information about the return codes, refer PEP Log Return Codes and PEP Result Codes.

• If the Backward Compatibility mode is set, then the Error Index includes one of the following values, per entry in the bulk protect operation:

  • 1: The protect operation for the entry is successful.
  • 0: The protect operation for the entry is unsuccessful.
    For more information about the failed entry, view the logs available in the ESA forensics.
  • Any other value or garbage return value: The protect operation for the entry is unsuccessful.
    For more information about the failed entry, view the logs available in ESA forensics.

Example:

 ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector(); 
 List<Integer> errorIndex = new ArrayList<Integer>();

 int[] protectData     = {1234, 5678, 9012, 3456}; 

 int[] protectedData = mapReduceProtector.bulkProtect( "DE_PROTECT", errorIndex, protectData ); 

 //CHECK THE ERROR INDEXES FOR ERRORS
 System.out.print("Error Index: ");
 for(int i = 0; i < errorIndex.size(); i++)
 {
  System.out.print(errorIndex.get( i ));
  if(i < errorIndex.size() - 1)
     {
     System.out.print(",");
     }
 }
 //ABOVE CODE WILL ONLY PRINT THE ERROR INDEXES

Exception:
The function throws the ptyMapRedProtectorException exception if an error is encountered during bulk protection of the data.

Supported Protection Methods:

bulkProtect() - Long data

The function is used when a set of data needs to be protected in a bulk operation. It helps to improve performance.

Signature:

public long[] bulkProtect(String dataElement, List <Integer> errorIndex, long[] inputDataItems)

Parameters:

• dataElement: Specifies the name of data element to protect the data.
• errorIndex : Is a list used to store all the error indices encountered while protecting each data entry in input Data Items.
• inputDataItems: Is the array to store the data for protection.

Result:

• The function returns the long array of protected data.
  
• If the Backward Compatibility mode is not set, then the appropriate error code appears. For more information about the return codes, refer.
• If the Backward Compatibility mode is set, then the Error Index includes one of the following values, per entry in the bulk protect operation:
  • 1: The protect operation for the entry is successful.
  • 0: The protect operation for the entry is unsuccessful.
    For more information about the failed entry, view the logs available in the ESA forensics.
  • Any other value or garbage return value: The protect operation for the entry is unsuccessful.
    For more information about the failed entry, view the logs available in the ESA forensics.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
List<Integer> errorIndex = new ArrayList<Integer>();
long[] protectData = {123412341234, 567856785678, 901290129012, 345634563456};
long[] protectedData = mapReduceProtector.bulkProtect( "DE_PROTECT", errorIndex, protectData );
//CHECK THE ERROR INDEXES FOR ERRORS
System.out.print("Error Index: ");
for(int i = 0; i < errorIndex.size(); i++)
    {
    System.out.print(errorIndex.get( i ));
    if(i < errorIndex.size() - 1)
    {
    System.out.print(",");
    }
    }
//ABOVE CODE WILL ONLY PRINT THE ERROR INDEXES    

Exception:
The function throws the ptyMapRedProtectorException exception if an error is encountered during bulk protection of the data.

Supported Protection Methods:

bulkUnprotect() - Byte array data

This method unprotects in bulk the inputDataItems with the required data element.

Note: For Date and Datetime type of data elements, the protect API returns an invalid input data error if the input value falls between the non-existent date range 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 Date and Datetime tokenization.

Signature:

public byte[][] bulkUnprotect(String dataElement, List<Integer> errorIndex, byte[][] inputDataItems, String... charset)

Parameters:

• dataElement: Specifies the name of data element to unprotect the data.
• errorIndex: Is a list of the error indices encountered while unprotecting each data entry in inputDataItems.
• inputDataItems: Is a two-dimensional array to store the bulk data to unrpotect.
• charset: Specifies the charset of the input data. The applicable charsets are UTF-8 (default), UTF-16LE, and UTF-16BE.

Result:
The function returns the two-dimensional byte array of unprotected data.

• If the Backward Compatibility mode is not set, then the appropriate error code appears. For more information about the return codes, refer PEP Log Return Codes and PEP Result Codes.
• If the Backward Compatibility mode is set, then the Error Index includes one of the following values, per entry in the bulk unprotect operation:
  • 1: The unprotect operation for the entry is successful.
  • 0: The unprotect operation for the entry is unsuccessful.
    For more information about the failed entry, view the logs available in ESA forensics.
  • Any other value or garbage return value: The unprotect operation for the entry is unsuccessful.
    For more information about the failed entry, view the logs available in ESA forensics.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector(); 
List<Integer> errorIndex = new ArrayList<Integer>();

byte[][] protectData     = {"protegrity".getBytes(), "protegrity".getBytes(), "protegrity".getBytes(), "protegrity".getBytes()}; 
byte[][] protectedData = mapReduceProtector.bulkProtect( "DE_PROTECT", errorIndex, protectData, "UTF-8" );

//THIS WILL PRINT THE PROTECTED DATA
System.out.print("Protected Data: ");
for(int i = 0; i < protectedData.length; i++)
{
    System.out.print(protectedData[i] == null ? null : new String(protectedData[i]));
    if(i < protectedData.length - 1)
    {
       System.out.print(",");
    }
}

//THIS WILL PRINT THE ERROR INDEX FOR PROTECT OPERATION
System.out.println("");  
System.out.print("Error Index: ");
for(int i = 0; i < errorIndex.size(); i++)
{
     System.out.print(errorIndex.get( i ));
     if(i < errorIndex.size() - 1)
     {
       System.out.print(",");
     }
}

byte[][] unprotectedData = mapReduceProtector.bulkUnprotect( "DE_PROTECT", errorIndex, protectedData, "UTF-8" );

//THIS WILL PRINT THE UNPROTECTED DATA
System.out.print("UnProtected Data: ");
for(int i = 0; i < unprotectedData.length; i++)
{
    System.out.print(unprotectedData[i] == null ? null : new String(unprotectedData[i]));
    if(i < unprotectedData.length - 1)
    {
       System.out.print(",");
    }
}

//THIS WILL PRINT THE ERROR INDEX FOR UNPROTECT OPERATION
System.out.println("");  
System.out.print("Error Index: ");
for(int i = 0; i < errorIndex.size(); i++)
{
     System.out.print(errorIndex.get( i ));
     if(i < errorIndex.size() - 1)
     {
       System.out.print(",");
     }
}

Exception:
The function throws the ptyMapRedProtectorException exception for errors when unprotecting the data.

Supported Protection Methods:

bulkUnprotect() - Int data

This method unprotects in bulk the inputDataItems with the required data element.

Signature:

public int[] bulkUnprotect(String dataElement, List<Integer> errorIndex, int[] inputDataItems)

Parameters:

• dataElement: Specifies the name of data element to unprotect the data.
• errorIndex: Is a list of the error indices encountered while unprotecting each data entry in inputDataItems.
• inputDataItems: Is the int array that contains the data to be unprotected.

Result:

• The function returns the unprotected int array data.
• If the Backward Compatibility mode is not set, then the appropriate error code appears.
  For more information about the return codes, refer PEP Log Return Codes and PEP Result Codes.
• If the Backward Compatibility mode is set, then the Error Index includes one of the following values, per entry in the bulk unprotect operation:
  • 1: The unprotect operation for the entry is successful.
  • 0: The unprotect operation for the entry is unsuccessful.
    For more information about the failed entry, view the logs available in ESA forensics.
  • Any other value or garbage return value: The unprotect operation for the entry is unsuccessful. For more information about the failed entry, view the logs available in ESA forensics.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
List<Integer> errorIndex = new ArrayList<Integer>();
int[] protectData = {1234, 5678,9012,3456 };
int[] protectedData = mapReduceProtector.bulkProtect( "DE_PROTECT", errorIndex, protectData );
//THIS WILL PRINT THE ERROR INDEX FOR PROTECT OPERATION
System.out.println("");
System.out.print("Error Index: ");
for(int i = 0; i < errorIndex.size(); i++)
{
System.out.print(errorIndex.get( i ));
if(i < errorIndex.size() - 1)
{
System.out.print(",");
}
}
int[] unprotectedData = mapReduceProtector.bulkUnprotect( "DE_PROTECT", errorIndex, protectedData );
//THIS WILL PRINT THE ERROR INDEX FOR UNPROTECT OPERATION
System.out.println("");
System.out.print("Error Index: ");
for(int i = 0; i < errorIndex.size(); i++)
{
System.out.print(errorIndex.get( i ));
if(i < errorIndex.size() - 1)
{
System.out.print(",");
}
}

Exception:
The function throws the ptyMapRedProtectorException exception for errors while unprotecting the data.

Supported Protection Methods:

bulkUnprotect() - Long data

This method unprotects in bulk the inputDataItems array with the required data element.

Signature:

public long[] bulkUnprotect(String dataElement, List<Integer> errorIndex, long[] inputDataItems)

Parameters:

• dataElement: Specifies the name of data element to unprotect the data.
• errorIndex: Is a list of the error indices encountered while unprotecting each data entry in inputDataItems
• inputDataItems: Is the long array that contains the data to unprotect.

Result:

• The function returns the unprotected long array data.
• If the Backward Compatibility mode is not set, then the appropriate error code appears. For more information about the return codes, refer PEP Log Return Codes and PEP Result Codes.
• If the Backward Compatibility mode is set, then the Error Index includes one of the following values, per entry in the bulk unprotect operation:
  • 1: The unprotect operation for the entry is successful.
  • 0: The unprotect operation for the entry is unsuccessful.
    For more information about the failed entry, view the logs available in the ESA forensics.
  • Any other value or garbage return value: The unprotect operation for the entry is unsuccessful. For more information about the failed entry, view the logs available in ESA forensics.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
List<Integer> errorIndex = new ArrayList<Integer>();
long[] protectData = { 123412341234, 567856785678, 901290129012, 345634563456 };
long[] protectedData = mapReduceProtector.bulkProtect( "DE_PROTECT", errorIndex, protectData );
//THIS WILL PRINT THE ERROR INDEX FOR PROTECT OPERATION
System.out.println("");
System.out.print("Error Index: ");
for(int i = 0; i < errorIndex.size(); i++)
{
System.out.print(errorIndex.get( i ));
if(i < errorIndex.size() - 1)
{
System.out.print(",");
}
}
long[] unprotectedData = mapReduceProtector.bulkUnprotect( "DE_PROTECT", errorIndex, protectedData );
//THIS WILL PRINT THE ERROR INDEX FOR UNPROTECT OPERATION
System.out.println("");
System.out.print("Error Index: ");
for(int i = 0; i < errorIndex.size(); i++)
{
System.out.print(errorIndex.get( i ));
if(i < errorIndex.size() - 1)
{
System.out.print(",");
}
}

Exception:

• The function throws the ptyMapRedProtectorException for errors when unprotecting data.

Supported Protection Methods:

reprotect() - Byte array data

The function is used to reprotect the data that is protected earlier with a separate data element.

Signature:

public byte[] reprotect(String oldDataElement, String newDataElement, byte[] data, String... charset)

Parameters:

• oldDataElement: Specifies the name of data element to protect the data earlier.
• newDataElement: Specifies the name of new data element to protect the data.
• data : Is an array that contains the data to be protected.
• charset: Specifies the charset of the input data. The applicable charsets are UTF-8 (default), UTF-16LE, and UTF-16BE.

Note: If you are using Format Preserving Encryption (FPE) and Byte APIs, then ensure that the encoding, which is used to convert the string input data to bytes, matches the encoding that is selected in the Plaintext Encoding drop-down for the required FPE data element.

Result:

• The function returns the byte array of reprotected data.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
byte[] protectedResult = mapReduceProtector.protect( "DE_PROTECT_1", "protegrity".getBytes(), "UTF-8" );
byte[] reprotectedResult = mapReduceProtector.reprotect( "DE_PROTECT_1", "DE_PROTECT_2", protectedResult, "UTF-8" );

Exception:

• The function throws the ptyMapRedProtectorException for errors while reprotecting the data.

Supported Protection Methods:

reprotect() - Int data

The function is used to protect the data again, that is protected earlier, with a new data element.

Signature:

public int reprotect(String oldDataElement, String newDataElement, int data)

Parameters:

• oldDataElement: Specifies the name of data element to protect the data earlier.
• newDataElement: Specifies the name of new data element to protect the data.
• data: Is an array that contains the data to be protected.

Result:

• The function returns the reprotected int data.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
int protectedResult = mapReduceProtector.protect( "DE_PROTECT_1", 1234 );
int reprotectedResult = mapReduceProtector.reprotect( "DE_PROTECT_1", "DE_PROTECT_2", protectedResult );

Exception:

• The function throws the ptyMapRedProtectorException for errors while reprotecting the data.

Supported Protection Methods:

reprotect() - Long data

The function is used to re-protect the data that has been protected earlier with a separate data element.

Signature:

public long reprotect(String oldDataElement, String newDataElement, long data)

Parameters:

• oldDataElement: Specifies the name of data element to protect the data earlier.
• newDataElement: Specifies the name of new data element to protect the data.
• data: Is an array that contains the data to be protected.

Result:

• The function returns the reprotected long data.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
long protectedResult = mapReduceProtector.protect( "DE_PROTECT_1", 123412341234 );
long reprotectedResult = mapReduceProtector.reprotect( "DE_PROTECT_1", "DE_PROTECT_2", protectedResult );

Exception:

• The function throws the ptyMapRedProtectorException for errors while reprotecting the data.

Supported Protection Methods:

hmac()

Warning: It is recommended to use the HMAC data element with the protect() and bulkProtect() Byte APIs for hashing byte array data, instead of using the hmac() API.

This method performs data hashing using the HMAC operation on a single data item with a data element, which is associated with hmac. It returns hmac value of the given data with the given data element.

Warning: This function is marked for deprecation and will be removed from the future releases.

Signature:

public byte[] hmac(String dataElement, byte[] data)

Parameters:

• String dataElement: Specifies the name of the data element to hash the data.
• byte[] data: Is an array that contains the data to be hashed.

Result:

• The function returns the byte array of HMAC data.

Example:

ptyMapReduceProtector mapReduceProtector = new ptyMapReduceProtector();
byte[] protectedResult = mapReduceProtector.hmac( "HMAC_DE", "protegrity".getBytes() );

Exception:

• The function throws the ptyMapRedProtectorException if an error occurs while hashing the data.

Supported Protection Methods: