Skip to content

PEG REST API on PrivaceraCloud

PEG API Endpoint#

The PEG API endpoint is obtained using the Copy Url link in Settings > ApiKey.

In the examples here, we call this endpoint <cloud_peg_api_endpoint>.

Request Summary for PrivaceraCloud#

The PEG REST API consists of the following requests:

  • /protect - Encrypts the data
  • /unprotect - Decrypts the data

Prerequisites#

API Key#

For the REST API requests protect and unprotect, you need an API key. See API Key.

Scheme Policy Required for protect and unprotect API Requests#

For the REST API requests protect and unprotect, you must create a scheme policy that grants these permissions to the user. See Create Scheme Policies on PrivaceraCloud.

Anatomy of a PEG API Request on PrivaceraCloud#

This example of the /protect request illustrates some common fields of the PEG REST API on PrivaceraCloud. The example is split across separate lines for clarity but in actual use is a single line.

curl -il
--request POST https://<cloud_peg_api_endpoint>/api/<api-key>/api/peg/public/protect
-u <service_user>:<password>
--header "Accept: application/json"
--header 'Content-Type: application/json'
--data-raw '{"schemelist":["<encryption_scheme>"],
           "datalist":[["<data>"]],
           "user":"<application_user>"}'
  • <cloud_peg_api_endpoint>: Your own API endpoint, as described in PEG API Endpoint.
  • <api_key>: Your API key, as described in API Key.
  • schemelist: List of schemes.
  • <scheme>: Single scheme to use for encrypting or decypting data. See Encryption Schemes.
  • 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.
  • <application_user>: The application user or end-user that connects to a service, such as Snowflake, UDF, or ODBC application. By way of scheme policies, the permission to use Privacera Encryption. of this user is verified.
  • datalist: List of list of data elements, one for each scheme in the schemelist parameter.
  • <data>: Single data element to be encrypted or decrypted. This is a JSON array that you must construct.
  • <cloud_peg_api_endpoint>/api: The endpoint of the PEG service for PrivaceraCloud. See PEG API Endpoint.

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 Response from /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 REST API Requests for PrivaceraCloud#

These examples use the Linux line continuation character \.

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

/protect#

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

curl -u <service_user>:<password> \
--request POST https://<cloud_peg_api_endpoint>/api/<api_key>/api/peg/public/protect'
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data-raw {"schemelist":["PERSON_NAME", "EMAIL"], \
           "datalist": [["Mark","Jonathan","Christopher"], ["mark@example.com","jonathan@test.com","christopher@google.com"]], \
           "user":"<application_user>"} 

Response

"datalist": [["WjM5","5vpJF9zT","1EbplEYVBjy"],["i0bD@WKbMYpr.CvE","?9aqS8zV@YUym.hkd","d501shhJEO&@YpvfOc.VYH"]]

/unprotect#

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

curl \
--request POST https://<cloud_peg_api_endpoint>/api/<api_key>/api/peg/public/unprotect \
--header Content-Type: application/json \
--header Accept: application/json \
--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"]]

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

curl \
--request POST https://<cloud_peg_api_endpoint>/api/<api_key>/api/peg/public/unprotect \
--header "Accept: application/json" \
--header Content-Type: application/json \
--data-raw {"datalist":[["8283a@QhbpH.yOs","5fGP@RyZBO.UZE"]], \
           "schemelist":["EMAIL2"], \
           "presentationSchemelist":["EMAIL2_P"] \
           "user":"<application_user>"}'

Audit Details for PEG REST API Accesses#

PrivaceraCloud records access to the PEG REST API encryption keys and schemes. For details, Audits.


Last update: February 18, 2022