Privacera Platform master publication

PEG REST API on Privacera Platform

:
PEG API Endpoint

For the Privacera Platform, by default, the PEG API endpoint is:

https://<privacera_hostname>:6869/api/peg/public

Check with your installation team for the value of <privacera_hostname> and if they have changed this default port.

Encryption Endpoint Summary for Privacera Platform

The PEG REST API consists of the following endpoints:

  • /authenticate - Generates a token to be used with subsequent /protect and /unprotect endpoints.

  • /getSchemes - Returns the names of Privacera-supplied and user-defined encryption schemes.

  • /protect - Encrypts the data.

  • /unprotect - Decrypts the data.

Authentication Methods on Privacera Platform

There are two different ways to authenticate to the PEG REST API:

  • Basic authentication with username and password.

  • An authentication token.

Basic Authentication

A Portal user needs to have the ROLE_ENCRYPTION_ALL or ROLE_ENCRYPTION_READ role to authenticate to the PEG REST API via basic authentication.

For basic authentication, you pass your username and password credentials in the <username>:<password> argument directly on the /protect or /unprotect endpoint. For an example of this argument, see /authenticate.

If you are a privileged user, you can also make calls on another user's behalf.

For details on assigning roles, see User Management.

Authentication Token

The PEG REST API authentication token can be created in two ways:

  • In the Privacera Portal

  • With the /authenticate REST API endpoint

The token must be included in the HTTP header of subsequent endpoints.

The token has a configurable validity period. See Add Keytab Expiry Date.

Generate Token in Privacera Portal

The token can be generated in the Portal as follows:

  1. Login to the Privacera Portal.

  2. From the left navigation menu, select Launch Pad and click Privacera Token.

  3. Click +Generate Token and generate a new token after you enter the expiration details, etc.

  4. An Access Key and a Secret Key, the components of the token, are generated as shown in the example below:

    Image 283538

  5. Store the Access Key and Secret Key credentials safely.

The token is a combination of <AccessKey and SecretKey> delimited by a colon (:):

<AccessKey:SecretKey>

It is required in the header of the /protect or /unprotect endpoints in the following form:

X-API-KEY:<AccessKey>:<SecretKey>
Get Token with /authenticate endpoint

The token is generated with the /authenticate endpoint as follows:

  1. The client uses the /authenticate endpoint with basic authentication user credentials to authenticate the end-user. PEG is integrated with the Privacera Portal. For definitions of <service_user> and <application_user>, see Anatomy of a PEG API Endpoint on Privacera Platform.

    curl -u <service_user>:<password> \
     --header "Accept: application/json" \
     --header "Content-Type: application/json" \
     --data-raw '"user":"<application_user>"' \
        https://<privacera_hostname>:6869/api/peg/public/authenticate

  2. If the authentication is successful, PEG returns the colon-delimited token <AccessKey>:<SecretKey>.

  3. Subsequent calls to /protect and /unprotect endpoints must include the X-API-KEY header with the token.

    X-API-KEY:<token_from_authenticate>;
curl -k for testing with self-signed certificate

If you are testing with a self-signed certificate, to bypass the certificate validation check, add the curl -k option.

Anatomy of the /protect API Endpoint on Privacera Platform

This example of the /protect endpoint illustrates some common fields of the PEG REST API on the Privacera Platform.

Instead of basic authentication, this example uses token authentication with an X-API-KEY:<token_from_authenticate>. If you want basic authentication, remove the token line in this example and replace it with -u <service_user>:<password>.

curl \
--request 'POST https://<privacera_hostname>:6869/api/peg/public/protect'
--header "X-API-KEY:<token_from_authenticate>" \
--header "Accept: application/json" \
--header 'Content-Type: application/json' \
--data-raw '{"schemelist":["<encryption_scheme>,..."], \
     "datalist":[["<data_to_encrypt>",...]], \
     "maskSchemelist": ["<masking_scheme>",...], \
     "maskDatalist": [[data_to_mask,...], \
     "user":"<application_user>"}'

Line

Description

<token_from_authenticate>

The /authenticate request (detailed in Authentication Token) returns a token that must be prepended with X-API-KEY and included in the header of subsequent requests.

If this anatomy showed basic authentication, it would use the curl option -u <service_user>:<password>:

  • <service_user>: The user issuing the API request. This user is authenticated by Privacera. Examples include Lambda functions servicing Snowflake or UDFs servicing end users. The <service_user> must have the administrative role (ROLE_ADMIN). to be able to issue the /protect and /unprotect requests on behalf of the <application_user>.

  • <password>: The service_user's password.

schemelist

List of <encryption_schemes>.

<encryption_scheme>

One or more <encryption_schemes> to encrypt or decrypt data in datalist. See Encryption Schemes.

datalist

List of data elements, one for each scheme in the schemelist parameter.

<data>

A data element to be encrypted with /protect or decrypted with /unprotect.

maskSchemeList

List of <masking_schemes>

<masking_scheme>

One or more <masking_schemes> to mask the data in maskDataList. See Masking schemes.

maskDataList

List of data elements for masking, with at least one for each masking scheme in maskSchemeList parameter or more data elements to be masked.

https://<privacera_hostname>:6869/api/peg/public

The PEG API endpoint and default port for Privacera Platform.

<application_user>

The application user or end-user that connects to a service, such as Snowflake, UDF, or ODBC application.

presentationSchemeList

Not shown here, the /unprotect request can include a field to specify an optional presentation scheme. On /unprotect, the server uses the presentation_scheme to obfuscate the data even more for display to authorized users. See Presentation Schemes.

presentationSchemeList on /protect is ignored.

About Constructing the datalist for protect

Suppose you want to encrypt two database fields tagged with Privacera metadata PERSON_NAME and EMAIL. The value of your API datalist to encrypt can be constructed like this:

  1. Extract from the database the unencrypted values of the tagged fields.

  2. Format a JSON array of those values.

  3. Make an API /protect request to encrypt the values in that array.

  4. Reformat the returned JSON array of the encrypted values to update the fields in your database.

About Deconstructing the datalist for unprotect

Suppose you want to decrypt two database fields tagged with Privacera metadata PERSON_NAME and EMAIL. The value of your API datalist to decrypt can be constructed like this:

  1. Extract from the database the encrypted values of the tagged fields.

  2. Format a JSON array of those values.

  3. Make an API /unprotect request to decrypt the values in that array.

  4. Reformat the returned JSON array of the decrypted values to update the fields in your database.

Example of Data Transformation with /unprotect and Presentation Scheme

This example shows some original input data, its representation when encrypted, and its obfuscated result after decryption with /unprotect and an optional presentation scheme, as shown in /unprotect with Presentation Scheme.

  • Original value: sally@gmail.com

  • Encrypted value: xy12zb@1mno2.rtz

  • Value after decryption and presentation scheme. The domain portion has been obfuscated: sally@ymxof.1dg

Example PEG API endpoints

Most of the examples do not show the full curl command and the required authentication. They show only the JSON bodies of the requests and responses. For authentication options, see Authentication Methods on Privacera Platform or the example of /authenticate.

/authenticate

As required for /authenticate, this example uses basic authentication to retrieve a token that is used in the other examples.

curl \
-u <service_user>:<password> \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data-raw '"user":"<application_user>"' \
https://privacera.com:6869/api/peg/public/authenticate

Response

{"token":"bWtpc2VyOjE6MTYxNzIyMTk4Njg2Mjo4NjM5OTEzOA==:U3AcayrrQW3eecXjocH8ArJNqDr1GmJAM92Fa/f8T/YxJitKuCqw/CIB7Lm9Szqk",
"tokenid":1,
"tokenExpiry":"2021-04-01T12:19:30Z",
"tokenName":"service_user",
tokenStatus":"ENABLED",
userName":"application_user"}
/protect with encryption scheme

The two elements in the input datalist array are encrypted with the encryption schemes PERSON_NAME and EMAIL.

--data-raw '{"schemelist":["PERSON_NAME", "EMAIL"],
"datalist": [
              ["Mark", "Jonathan","Christopher"],
              ["mark@example.com","jonathan@test.com","christopher@google.com"]
	    ],
           "user":"jimmybob@BigCo.com"}'

Response

{"datalist":[
      ["WjM5","5vpJF9zT","1EbplEYVBjy"],
      ["i0bD@WKbMYpr.CvE","?9aqS8zV@YUym.hkd","d501shhJEO&@YpvfOc.VYH"]
    ],
      "data":"","responseStatus:"SUCCESS"}
/protect with masking scheme

The element in the input maskDataList array is masked by the masking scheme MASKING_SCHEME.

--data-raw '{
    "maskSchemelist": [
        "MASKING_SCHEME"
    ],
    "maskDatalist": [
       [
         "",null,"12-12-2012","12/12/2025T09:01:02"
       ]
     ]
     "user":"<application_user>"}'

Response

{
"datalist":[],
"data":"",
"maskDatalist": [
      ["**-**-****","**/**/*******:**:**"],
      ["*****@*****.***","",null]
    ],"responseStatus":"SUCCESS" }
]
/protect with both encryption and masking

The element in the input datalist array is encrypted with the encryption scheme SYSTEM_EMAIL and at the same time the data in the input maskDataList is masked with the masking scheme MASKING_SCHEME.

--data-raw '{"schemelist":["SYSTEM_EMAIL"], \
"datalist":[
        ["sally@gmail.com"]
        ], \
      "maskSchemelist":["DATE_MASKING_SCHEME"], \ 
      "maskDatalist":[
        ["",null,"12-12-2012","12/12/2025T09:01:02"]
        ], \
"user":"padmin" }'

Response

{
{"datalist":[
    ["*btaV@CyilS.Jvk"]
    ],
"data":"",
"maskDatalist":[
    ["",null,"**-**-****","**/**/*******:**:**"],
"responseStatus":"SUCCESS
}
/unprotect without presentation scheme

The two elements in the input datalist array are decrypted with the encryption schemes PERSON_NAME and EMAIL.

--data-raw '{"schemelist":["PERSON_NAME", "EMAIL"], 
           "datalist": [["WjM5","5vpJF9zT","1EbplEYVBjy"],["i0bD@WKbMYpr.CvE","?9aqS8zV@YUym.hkd","d501shhJEO&@YpvfOc.VYH"]], \
           "user":"<application_user>"}'

Response

{"datalist": [
    ["Mark","Jonathan","Christopher"],
    ["mark@example.com","jonathan@test.com","christopher@google.com"]i
    ],
    "data":"",
"responseStatus":"SUCCESS"}
/unprotect with Presentation Scheme

The input in the datalist array is decrypted with the encryption scheme EMAIL2 and then obfuscated with the presentation scheme EMAIL2_P.

--data-raw '{"datalist":[["8283a@QhbpH.yOs","5fGP@RyZBO.UZE"]], \
           "schemelist":["EMAIL2"], \
           "presentationSchemelist":["EMAIL2_P"] \
           "user":"jimmybob@BigCo.com"}'
/unprotect with masking scheme

Masking schemes must not be used with /unprotect, which returns an error because the masked data cannot be unmasked.

REST API Response Partial Success on Bulk Operations

For bulk operations, in which multiple data elements are included in the datalist JSON array of the /protect or /unprotect request, if an error is encountered in processing one of those elements, the endpoint returns the response as "Partial Success" but does not fail the entire batch.

Audit Details for PEG REST API Accesses

Privacera records access to the PEG REST API encryption keys and schemes. For details, Audit.

REST API Reference

See REST API Documentation for Privacera Platform.REST API Documentation for Privacera Platform