Skip to main content

Privacera Platform

Privacera Encryption REST API

:
PEG API endpoint

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

PEG REST API encryption endpoints

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.

PEG REST API authentication methods on Privacera Platform

There are two ways to authenticate the PEG REST API:

  • Basic authentication with username and password.

  • An authentication token.

Basic PEG REST API 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 Common PEG REST API fields.

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

For details on assigning roles, see User Management.

PEG REST API 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 PEG REST API authentication token in Privacera Portal

You can generate the PEG REST API authentication token in Privacera Portal.

The token is a combination of an <AccessKey and a SecretKey> delimited by a colon (:): <AccessKey:SecretKey>. The authentication token is required in the header of the /protect or /unprotect endpoints in the following form:

X-API-KEY:<AccessKey>:<SecretKey>

To generate the token, do the following:

  1. Log in to the Privacera Portal.

  2. From the navigation menu, select Launch Pad > Privacera Token.

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

    An Access Key and a Secret Key are generated.

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

Get PEG REST API authentication token using the /authenticate endpoint

The PEG REST API authentication token is generated using the /authenticate endpoint.

To generate the token, use 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 Common PEG REST API fields.

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

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

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

X-API-KEY:<token_from_authenticate>;

Note

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

Common PEG REST API fields

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>"}'

The following table displays common PEG REST API fields with descriptions of each:

Table 7. Common PEG REST API fields

Line

Description

<token_from_authenticate>

The /authenticate request (detailed in PEG REST API 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.



Construct the datalist for the /protect endpoint

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 by doing the following:

  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.

Deconstruct the response from the /unprotect endpoint

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 by doing the following:

  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 data transformation with the /unprotect endpoint 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.

  • 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 ??? or the example of ???.

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

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": [
        [
            "mNM-^@RUWqb.qRK"
        ]
    ],
    "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"]],
"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, see Audit.