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.
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 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:
-
Login to the Privacera Portal.
-
From the left navigation menu, select Launch Pad and click Privacera Token.
-
Click +Generate Token and generate a new token after you enter the expiration details, etc.
-
The components of the token, an Access Key and a Secret Key, are generated as shown in the example below:
-
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:
-
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
-
If the authentication is successful, the PEG returns the colon-delimited token
<AccessKey>:<SecretKey>
. -
Subsequent calls to
/protect
and/unprotect
endpoints must include theX-API-KEY
header with the token.X-API-KEY:<token_from_authenticate>;
Anatomy of a PEG 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 a 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>",...]], \
"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> :
|
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.
|
<application_user> |
The application user or end-user that connects to a service, such as Snowflake, UDF, or ODBC application. |
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. |
https://<privacera_hostname>:6869/api/peg/public |
The PEG API endpoint and default port for Privacera Platform. |
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:
- Extract from the database the unencrypted values of the tagged fields.
- Format a JSON array of those values.
- Make an API
/protect
request to encrypt the values in that array. - 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:
- Extract from the database the encrypted values of the tagged fields.
- Format a JSON array of those values.
- Make an API
/unprotect
request to decrypt the values in that array. - 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 on Privacera Platform
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.
/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
The two elements in the input datalist
array are encrypted with the
encryption schemes
PERSON_NAME
and EMAIL
.
This example uses the authentication token retrieved with /authenticate
`.
curl \
--request 'POST https://privacera.BigCo.com:6869/api/peg/public/protect'
--header "X-API-KEY: bWtpc2VyOjE6MTYxNzIyMTk4Njg2Mjo4NjM5OTEzOA==:U3AcayrrQW3eecXjocH8ArJNqDr1GmJAM92Fa/f8T/YxJitKuCqw/CIB7Lm9Szqk" \
--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":"jimmybob@BigCo.com"}'
Response
{"datalist":[["WjM5","5vpJF9zT","1EbplEYVBjy"],["i0bD@WKbMYpr.CvE","?9aqS8zV@YUym.hkd","d501shhJEO&@YpvfOc.VYH"]],"data":"","responseStatus:"SUCCESS"}
/unprotect
The two elements in the input datalist
array are decrypted with the
encryption schemes
PERSON_NAME
and EMAIL
.
This example uses the authentication token retrieved with /authenticate
.
curl \
--request 'POST https://privacera.compliance.BigCo.com:6869/api/peg/public/unprotect' \
--header 'X-API-KEY: bWtpc2VyOjE6MTYxNzIyMTk4Njg2Mjo4NjM5OTEzOA==:U3AcayrrQW3eecXjocH8ArJNqDr1GmJAM92Fa/f8T/YxJitKuCqw/CIB7Lm9Szqk' \
--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"]],"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
.
This example uses the authentication token retrieved with /authenticate
.
curl \
--request 'POST https://privacera.BigCo.com:6869/api/peg/public/unprotect' \
--header 'X-API-KEY: bWtpc2VyOjE6MTYxNzIyMTk4Njg2Mjo4NjM5OTEzOA==:U3AcayrrQW3eecXjocH8ArJNqDr1GmJAM92Fa/f8T/YxJitKuCqw/CIB7Lm9Szqk' \
--header "Accept: application/json" \
--header 'Content-Type: application/json' \
--data-raw '{"datalist":[["8283a@QhbpH.yOs","5fGP@RyZBO.UZE"]], \
"schemelist":["EMAIL2"], \
"presentationSchemelist":["EMAIL2_P"] \
"user":"jimmybob@BigCo.com"}'
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.