Using the AP .Net APIs

Sample application for the AP .Net.

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

It is assumed that the ESA is already available.

The tasks can be divided in the following order.

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

Creating a Data Element and Data Store

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

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

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

Creating a Member Source and Role

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

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

Configuring a Policy

Configure a policy in the ESA by performing the following.

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

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

Configuring a Trusted Application

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

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

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

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

Adding a Trusted Application to Data Store

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

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

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

Installing the AP .Net

Install the AP .Net by performing the following.

  1. To install the AP .Net, refer to Application Protector .Net Installation.
  2. Verify if the AP .Net 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 .Net.
    For more information about the AP .Net initialization API, refer to getProtector.
    c. Run the GetVersion method to check the version of the installed AP .Net.
    For more information about the GetVersion method, refer to GetVersion API.

Running the AP .Net APIs

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

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

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

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

using System;
using System.Collections.Generic;
using System.Text;
using Protegrity.Net;
using Protegrity.PException;

namespace APDotNetTest
{
    /**********************************************************************************************/
    /**
     * @class   Program
     *
     * @brief   A sample program for Application .NET Protector.
     *
     **************************************************************************************************/
    class Program
    {
        private const string dataElementName = "alphanum";
        private const string newDataElementName = "alphanumreprot";
        private const string userName = "policyuser";


        /**********************************************************************************************/
        /**
         * @fn  static void Main(string[] args)
         *
         * @brief   Main entry-point for this application
         *
         * @param   args    An array of command-line argument strings.
         **************************************************************************************************/

        static void Main(string[] args)
        { 
            try
            {
                /* Dispose() is a method defined by the IDisposable interface in .NET. 
                 * Its used to release unmanaged resources.
                 * .NET garbage collector only cleans up managed memory. If your class uses unmanaged resources, 
                 * you must clean them up manually  and thats what Dispose() is for.
                 * 
                 * ====================
                 * With using 
                 * ====================
                 * You're telling the compiler:
                 * "Create this object, and automatically call Dispose() on it 
                 * when it goes out of scope."
                 * This is called a using declaration, and it ensures that cleanup happens even if
                 * an exception occurs.
                 * 
                 * ======================
                 * Without using
                 * ======================
                 * You have to call dispose manually.
                 */

                using Protector protector = Protector.GetProtector();

                /**
                 * Sample input string data for single operations.
                 */
                string singleInput = "Hello Protegrity";
                byte[] singleByteInput = Encoding.UTF8.GetBytes(singleInput);

                Console.WriteLine("#########################################");
                Console.WriteLine("# Protegrity Application .NET Protector #");
                Console.WriteLine("#########################################\n");

                /**
                 * Calling GetVersion to print APDotNet sdk and Core version.
                 */
                Console.WriteLine(protector.GetVersion() + "\n");
                Console.WriteLine("--------------------------------------");
                Console.WriteLine("-     Single Protect API             -");
                Console.WriteLine("--------------------------------------");
                Console.WriteLine($"Input Data is:        {singleInput}\n");


                /**
                 * Use protector object to call single string Protect API.
                 */
                string protectedData = protector.Protect(singleInput, userName, dataElementName);
                Console.WriteLine("With String Data Type");
                Console.WriteLine("-----------------------");
                Console.WriteLine($"Protected Data is:    {protectedData}");

                /**
                 * Use protector object to call single string Unprotect API
                 */
                string unprotectedData = protector.Unprotect(protectedData, userName, dataElementName);
                Console.WriteLine($"Unprotected Data is:  {unprotectedData}\n");

                /**
                * Use protector object to call single string Reprotect API.
                */
                string reprotectedData = protector.Reprotect(protectedData, userName, dataElementName, newDataElementName);
                Console.WriteLine($"Reprotected Data is:  {reprotectedData}");

                /**
                 * Use protector object to call single string Unprotect API
                 */
                string unprotectReprotectedData = protector.Unprotect(reprotectedData, userName, newDataElementName);
                Console.WriteLine($"Unprotected Data is:  {unprotectReprotectedData}\n");

                /** 
                 * Use protector object to call single byte Protect API.
                 */
                byte[] byteProtectedData = protector.Protect(singleByteInput, userName, dataElementName);
                Console.WriteLine("With Byte Data Type");
                Console.WriteLine("----------------------");
                Console.WriteLine($"Protected Byte Data is:    {Encoding.UTF8.GetString(byteProtectedData)}");

                /**
                 * Use protector object to call single byte Unprotect API
                 */
                byte[] byteUnprotectedData = protector.Unprotect(byteProtectedData, userName, dataElementName);
                Console.WriteLine($"Unprotected Byte Data is:  {Encoding.UTF8.GetString(byteUnprotectedData)}\n");

                /**
                 * Use protector object to call single byte Reprotect API.
                 */
                byte[] byteReprotectedData = protector.Reprotect(byteProtectedData, userName, dataElementName, newDataElementName);
                Console.WriteLine($"Reprotected Byte Data is:  {Encoding.UTF8.GetString(byteReprotectedData)}");

                /**
                 * Use protector object to call single byte Unprotect API
                 */
                byte[] byteUnprotectReprotectedData = protector.Unprotect(byteReprotectedData, userName, newDataElementName);
                Console.WriteLine($"Unprotected Byte Data is:  {Encoding.UTF8.GetString(byteUnprotectReprotectedData)}");
                Console.WriteLine("\n");

                /**
                 * Sample bulk string input data
                 */
                string[] bulkInput = { "The Alpha-numeric token type tokenizes all alphabetic symbols (both lowercase and uppercase letters), as well as digits.", "Digits 0 through 9, Lowercase letters a through z, Uppercase letters A through Z", "alphanumeric data 1234567890 !@#$%^&* with special characters", "ALL THE CHARACTERS IN THIS STRING ARE UPPERCASE", "UPPERCASE WITH 1234567890 NUMBERS AND !@#$%^&*() SPECIAL CHARACTERS" };
                List<byte[]> byteBulkInput = new List<byte[]>(bulkInput.Length);

                Console.WriteLine("--------------------------------------");
                Console.WriteLine("-         Bulk Protect API           -");
                Console.WriteLine("--------------------------------------");

                Console.WriteLine("Input Data is:");

                /**
                 * Converting string data to byte data.
                 */
                for (int i = 0; i < bulkInput.Length; i++)
                {
                    Console.WriteLine($"{bulkInput[i]}");
                    byteBulkInput.Add(Encoding.UTF8.GetBytes(bulkInput[i]));
                }

                Console.WriteLine("\n");
                Console.WriteLine("With String Data Type");
                Console.WriteLine("----------------------");

                /**
                 * Use protector object to call bulk string Protect API
                 */
                Tuple<string[], int[]> bulkProtectedData = protector.Protect(bulkInput, userName, dataElementName);
                Console.WriteLine("Protected Data is: ");
                for (int i = 0; i < bulkProtectedData.Item1.Length; i++)
                {
                    Console.WriteLine(bulkProtectedData.Item1[i] + " " + bulkProtectedData.Item2[i]);
                }
                Console.WriteLine("\n");

                /**
                 * Use protector object to call bulk string Unprotect API
                 */
                Tuple<string[], int[]> bulkUnprotectedData = protector.Unprotect(bulkProtectedData.Item1, userName, dataElementName);
                Console.WriteLine("Unprotected Data is: ");
                for (int i = 0; i < bulkUnprotectedData.Item1.Length; i++)
                {
                    Console.WriteLine(bulkUnprotectedData.Item1[i] + " " + bulkUnprotectedData.Item2[i]);
                }
                Console.WriteLine("\n");

                /**
                 * Use protector object to call bulk string Reprotect API
                 */
                Tuple<string[], int[]> bulkReprotectedData = protector.Reprotect(bulkProtectedData.Item1, userName, dataElementName, newDataElementName);
                Console.WriteLine("Reprotected Data is: ");
                for (int i = 0; i < bulkReprotectedData.Item1.Length; i++)
                {
                    Console.WriteLine(bulkReprotectedData.Item1[i] + " " + bulkReprotectedData.Item2[i]);
                }
                Console.WriteLine("\n");

                /**
                * Use protector object to call bulk string Unprotect API
                */
                Tuple<string[], int[]> bulkUnprotectReprotectedData = protector.Unprotect(bulkReprotectedData.Item1, userName, newDataElementName);
                Console.WriteLine("Unprotected Data is: ");
                for (int i = 0; i < bulkUnprotectReprotectedData.Item1.Length; i++)
                {
                    Console.WriteLine(bulkUnprotectReprotectedData.Item1[i] + " " + bulkUnprotectReprotectedData.Item2[i]);
                }
                Console.WriteLine("\n");

                Console.WriteLine("With Byte Data Type");
                Console.WriteLine("----------------------");

                /**
                 * Use protector object to call bulk byte Protect API
                 */
                Tuple<List<byte[]>, int[]> byteBulkProtectedData = protector.Protect(byteBulkInput, userName, dataElementName);
                Console.WriteLine("Protected Data is: ");
                for (int i = 0; i < byteBulkProtectedData.Item1.Count; i++)
                {
                    Console.WriteLine(Encoding.UTF8.GetString(byteBulkProtectedData.Item1[i]) + " " + byteBulkProtectedData.Item2[i]);
                }
                Console.WriteLine("\n");

                /**
                * Use protector object to call bulk byte Unprotect API
                */
                Tuple<List<byte[]>, int[]> byteBulkUnprotectedData = protector.Unprotect(byteBulkProtectedData.Item1, userName, dataElementName);
                Console.WriteLine("Unprotected Data is: ");
                for (int i = 0; i < byteBulkUnprotectedData.Item1.Count; i++)
                {
                    Console.WriteLine(Encoding.UTF8.GetString(byteBulkUnprotectedData.Item1[i]) + " " + byteBulkUnprotectedData.Item2[i]);
                }
                Console.WriteLine("\n");

                /**
                * Use protector object to call bulk byte Reprotect API
                */
                Tuple<List<byte[]>, int[]> byteBulkReprotectedData = protector.Reprotect(byteBulkProtectedData.Item1, userName, dataElementName, newDataElementName);
                Console.WriteLine("Reprotected Data is: ");
                for (int i = 0; i < byteBulkReprotectedData.Item1.Count; i++)
                {
                    Console.WriteLine(Encoding.UTF8.GetString(byteBulkReprotectedData.Item1[i]) + " " + byteBulkReprotectedData.Item2[i]);
                }
                Console.WriteLine("\n");

                /**
                * Use protector object to call bulk byte Unprotect API
                */
                Tuple<List<byte[]>, int[]> byteBulkUnprotectReprotectedData = protector.Unprotect(byteBulkReprotectedData.Item1, userName, newDataElementName);
                Console.WriteLine("Unprotected Data is: ");
                for (int i = 0; i < byteBulkUnprotectReprotectedData.Item1.Count; i++)
                {
                    Console.WriteLine(Encoding.UTF8.GetString(byteBulkUnprotectReprotectedData.Item1[i]) + " " + byteBulkUnprotectReprotectedData.Item2[i]);
                }
                Console.WriteLine("\n");
            }
            catch (ProtectorException e)
            {
                Console.WriteLine(e);
            }
        } /* End scope of main function */

    } /* End scope of class */

} /* closure of namespace */

Application Protector .Net APIs

The various APIs of the AP .Net.


Last modified : December 18, 2025