This is the multi-page printable view of this section. Click here to print.
The following sections describe key concepts for understanding the REST API.
Base URL: https://{YOUR_REGION}-{YOUR_PROJECT_ID}.cloudfunctions.net/{FUNCTION_NAME}
Substitute:
Protegrity Policy roles defines the unique data access privileges for every member. The protector function protects the data with the username sent in either the JWT-formatted authorization header, the request body or service user in the environment variables.
The protector function behavior can be set in the cloud function environment variables as described in Install Protect Function via Terraform Scripts
| Authorization/allow_assume_user | 0 | 1 |
|---|---|---|
| Empty | User from the request body. / (Throw an error). | User from the request body. |
| JWT | User from JWT payload | User from request body. If not found user from JWT payload. |
Cloud Protect function can authenticate JWTs with an OpenID endpoint or a stored certificate/secret.
The protector must be able to reach specified OpenID endpoint to obtain the public key when OpenID settings are enabled. The retrieved key is used to verify the signature. Several additional claims are verified against the configuration provided to the protect function when OpenID is enabled: issuer, audience, appid (optional).
Availability of an OpenID endpoint from the protector may not be feasible or a non-OpenID issuer may be in use. In those cases, a stored certificate/secret may be used to validate the jwt signature by enabling jwt_verify and including a base64 encoded certificate/secret in jwt_secret_base64 configuration. Additional claims are not verified.
Stored secret verification example using jwt_verify and jwt_secret_base64 configurations:
Parameter | Value | Notes |
|---|---|---|
authorization | JWT | |
jwt_verify | 1 |
|
jwt_secret_base64 | Secret in base64 encoding. For example, the value of the public key is as follows. This public key will be stored as follows. | The secret must be in base64. We recommend using RSA public certificates, it is not recommended to keep Hash (symmetric) secrets in the clear. |
Verification example using openid_* configuration parameters:
| Parameter | Value | Notes |
|---|---|---|
| openid_enabled | true | |
| openid_audiences | Audience as it would appear in the aud claim, for example “https://management.azure.com/" | Can be either one value or comma separated list. |
| openid_issuers | Issuer as it would appear in the iss claim, for example “https://sts.windows.net/bca3157d-b8d9-4ca8-a724-1c7e2b96e1ef" | Can be either one value or comma separated list. |
| openid_appid | Appid as it would appear in the appid claim, for example “9ada3e7d-4ec4-48da-9d69-5379b7984fe1” | Optional. If value is “”, appid claim is ignored. When openid_appid is provided, it must match the appid claim of the token. |
Allowing unauthenticated HTTP function invocation on Google Cloud protector function.
The Protect function will validate the JWT in the Authorization header.
Authenticating for invocation on Google Cloud protector function. All requests to the protector function will need to send the Google JWT in the Authorization header.
When PTY_GCP_JWT_HEADER is not set or it is false the Protect function will validate the JWT in the Authorization header.
When PTY_GCP_JWT_HEADER = true the Protect function will validate the JWT in the X-PTY-Authorization header.
Once the Cloud API on GCP is installed, you can export the OpenAPI documentation file from:
{base url}/pty/v1/openapi
Authentication and Authorization configurations are enforced on the openapi endpoint URL.
To get the base url, login to Google Cloud console. Navigate to the Protect Cloud Function details and to the TRIGGER tab.
For testing the REST API, we recommend using a client tool, such as Postman.
AWS Lambda service limits maximum size of payload to 6 MB. Client applications of Protegrity Cloud API must ensure their payload size is within this limit. This applies to all types of requests described below.
Performs a policy operation such as protect, unprotect, or reprotect.
URI
/v1/protect or /v1/unprotect or /v1/reprotect
Method
POST
Parameters
data: Input data to the policy operation.
data_element: Data element to use for the policy operation.
encoding: Optional, encoding of the data. One of: base64, base64_mime, base64_pem, base64_url, hex, or utf8. Defaults to hex for binary data elements, otherwise defaults to utf8.
external_iv: Optional, external initialization vector.
old_data_element: (reprotect) Data element for unprotecting the input.
old_external_iv: (reprotect) Optional, external initialization vector for the input.
query_id: Optional, identifier for the request.
user: User performing the operation.
Result
Returns the output of the policy operation.
{
"encoding": "utf8",
"query_id": "1",
"user": "user1",
"data_element": "Alphanum",
"data":[<data1>,<data2>]
}
{
"encoding": "utf8",
"query_id": "1",
"user": "user1",
"data_element": "Alphanum",
"external_iv": "abc123",
"data":[<data1>,<data2>]
}
{
"encoding": "utf8",
"query_id": "1",
"user": "user1",
"data_element": "deName",
"old_data_element": "Alphanum",
"data":[<data1>,<data2>]
}
Performs policy operations using different data elements for each data set.
URI
/v1/protect or /v1/unprotect or /v1/reprotect
Method
POST
Parameters
encoding: Optional, encoding of the data. One of: base64, base64_mime, base64_pem, base64_url, hex, or utf8. Defaults to hex for binary data elements, otherwise defaults to utf8.
query_id: Optional, prefix for the request identifier.
user: User performing the operation.
arguments[].data: Input data to the policy operation.
arguments[].data_element: Data element to use for the policy operation.
arguments[].external_iv: Optional, external initialization vector.
arguments[].id: Optional, request identifier.
arguments[].old_data_element: (reprotect) Data element for unprotecting the input.
arguments[].old_external_iv: (reprotect) Optional, external initialization vector for the input.
{
"encoding": "utf8",
"query_id": "query1234",
"user": <policy_user>,
"arguments": [
{
"id": "1",
"external_iv": "<external iv>",
"data_element": "<data element name>",
"data":["<data1>","<data2>"]
},
{
"data_element": <data element name>,
"data":["<data1>","<data2>"]
}
]
}
External IV
The External IV feature provides an additional level of security by allowing different tokenized results across protectors for the same input data and token element, depending on the External IV set on each protector. External IVs must adhere to certain guardrails and not all data elements support External IV. To read more about the Tokenization model with External IV, refer to the External Initialization Vector (IV) chapter in the Protection Methods Reference.
responsePayloadV1:
type: object
properties:
success:
type: bool
error_msg:
type: string
description: When success is false, error_msg is included
results:
type: array
items:
type: string
Example success:
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
}
If the request was successful, the success flag will always be true.
Example failure:
{
"error_msg": "token expired",
"success": false
}
If the request fails, the success flag will always be false.
Multi Data Elements Support Payload
responsePayloadV2:
type: object
properties:
success:
type: boolean
results:
type: array
items:
type: object
properties:
success:
type: bool
error_msg:
type: string
description: When success is false, error_msg is included
id:
type: string
description: When id is sent in the request payload, id is included in the response
results:
type: array
items:
type: string
Example success:
{
"encoding": "utf8",
"results":[
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
},
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
}
],
"success": true
}
If the all the subrequests were successful, the success flag will be true.
Example failure:
{
"results": [
{
"error_msg":
"Protect failed. Data element not found. Refer to audit log for details",
"success": false
},
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
}
],
"success": false
}
It is possible to have a mix of successful and unsuccessful results. In this case, the global success flag will be false.
Protegrity has multiple products with REST API capabilities, such as Protection Server (out of support), DSG, and the latest product - IAP REST. Each one has its use case. To help you move to cloud-native implementation, Cloud Product REST API supports legacy payload.
Performs a policy operation such as protect, unprotect, or reprotect.
Method
POST
Parameters
dataelementname: (protect/unprotect) Data element to use for the policy operation.
externaliv: (protect/unprotect) Optional, external initialization vector.
newdataelementname: (reprotect) Data element to use for the output.
newexternaliv: (reprotect) Optional, external initialization vector for the output.
olddataelementname: (reprotect) Data element to use for the input.
oldexternaliv: (reprotect) Optional, external initialization vector for the input.
policyusername: User performing the operation.
bulk.id: Optional, identifier for the request.
bulk.data[].content: Input data to the policy operation.
Result
Returns the output of the policy operation.
{
"protect": {
"policyusername": "user1",
"dataelementname": "Alphanum",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
{
"protect": {
"policyusername": "user1",
"dataelementname": "Alphanum",
"externaliv": "abc123",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
{
"unprotect": {
"policyusername": "user1",
"dataelementname": "Alphanum",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
{
"reprotect": {
"policyusername": "user1",
"newdataelementname": "deName",
"olddataelementname": "Alphanum",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
Example:
{"protect":{"bulk":{"returntype":"success","data":[{"returntype":"success","message":"Data
protection was successful.","content":"RGZBUFR4ODAzejFwNjQ5TWg0TEFpcFNqbA=="},{"returntype":"success",
"message":"Data protection was successful.","content":"aHNnVVB5QWFDYw=="}]}}}
The following table explains the different HTTP Status Codes with their corresponding response.
Status Codes | Response | Description |
|---|---|---|
200 | | Success protected data is in results and success attribute is true |
400 | | There was an issue in the request, success is false, check error_msg attribute. For more information check the logs |
500 | | Configuration error in the Google Cloud function configuration variables. |
By default, the Google Cloud Functions support HTTPS.
Google Cloud Function HTTPS endpoint have TLS 1.0, TLS 1.1, TLS 1.2 and TLS1.3 enabled.
For more information on HTTPS setting on Google Cloud HTTP Functions, refer to Security levels
Verification example using openid_* configuration parameters:
| Parameter | Value | Notes |
|---|---|---|
| openid_enabled | true | |
| openid_audiences | Audience as it would appear in the aud claim, for example “https://management.azure.com/" | Can be either one value or comma separated list. |
| openid_issuers | Issuer as it would appear in the iss claim, for example “https://sts.windows.net/bca3157d-b8d9-4ca8-a724-1c7e2b96e1ef" | Can be either one value or comma separated list. |
| openid_appid | Appid as it would appear in the appid claim, for example “9ada3e7d-4ec4-48da-9d69-5379b7984fe1” | Optional. If value is “”, appid claim is ignored. When openid_appid is provided, it must match the appid claim of the token. |
Performs a policy operation such as protect, unprotect, or reprotect.
URI
/v1/protect or /v1/unprotect or /v1/reprotect
Method
POST
Parameters
data: Input data to the policy operation.
data_element: Data element to use for the policy operation.
encoding: Optional, encoding of the data. One of: base64, hex, or utf8. Defaults to hex for binary data elements, otherwise defaults to utf8.
external_iv: Optional, external initialization vector.
old_data_element: (reprotect) Data element for unprotecting the input.
old_external_iv: (reprotect) Optional, external initialization vector for the input.
query_id: Optional, identifier for the request.
user: User performing the operation.
Result
Returns the output of the policy operation.
{
"encoding": "utf8",
"query_id": "1",
"user": "user1",
"data_element": "Alphanum",
"data":[<data1>,<data2>]
}
{
"encoding": "utf8",
"query_id": "1",
"user": "user1",
"data_element": "Alphanum",
"external_iv": "abc123",
"data":[<data1>,<data2>]
}
{
"encoding": "utf8",
"query_id": "1",
"user": "user1",
"data_element": "deName",
"old_data_element": "Alphanum",
"data":[<data1>,<data2>]
}
Performs policy operations using different data elements for each data set.
URI
/v1/protect or /v1/unprotect or /v1/reprotect
Method
POST
Parameters
encoding: Optional, encoding of the data. One of: base64, hex, or utf8. Defaults to hex for binary data elements, otherwise defaults to utf8.
query_id: Optional, prefix for the request identifier.
user: User performing the operation.
arguments[].data: Input data to the policy operation.
arguments[].data_element: Data element to use for the policy operation.
arguments[].external_iv: Optional, external initialization vector.
arguments[].id: Optional, request identifier.
arguments[].old_data_element: (reprotect) Data element for unprotecting the input.
arguments[].old_external_iv: (reprotect) Optional, external initialization vector for the input.
Note: When multiple data elements are sent in the payload, the Cloud API generates an audit log per argument. The Cloud API appends the argument id, if it exists, to the query_id. For example: query_id.id:{id}. If an argument id is not provided then the index in the argument array is appended to the query_id. For example: query_id.index:{index}.
{
"encoding": "utf8",
"query_id": "query1234",
"user": <policy_user>,
"arguments": [
{
"id": "1",
"external_iv": "<external iv>",
"data_element": "<data element name>",
"data":["<data1>","<data2>"]
},
{
"data_element": <data element name>,
"data":["<data1>","<data2>"]
}
]
}
External IV
The External IV feature provides an additional level of security by allowing different tokenized results across protectors for the same input data and token element, depending on the External IV set on each protector. To read more about the Tokenization model with External IV, refer to the External Initialization Vector (IV) in the Protection Methods Reference guide.
Performs a policy operation such as protect, unprotect, or reprotect.
Method
POST
Parameters
dataelementname: (protect/unprotect) Data element to use for the policy operation.
externaliv: (protect/unprotect) Optional, external initialization vector.
newdataelementname: (reprotect) Data element to use for the output.
newexternaliv: (reprotect) Optional, external initialization vector for the output.
olddataelementname: (reprotect) Data element to use for the input.
oldexternaliv: (reprotect) Optional, external initialization vector for the input.
policyusername: User performing the operation.
bulk.id: Optional, identifier for the request.
bulk.data[].content: Input data to the policy operation.
Result
Returns the output of the policy operation.
{
"protect": {
"policyusername": "user1",
"dataelementname": "Alphanum",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
{
"protect": {
"policyusername": "user1",
"dataelementname": "Alphanum",
"externaliv": "abc123",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
{
"unprotect": {
"policyusername": "user1",
"dataelementname": "Alphanum",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
{
"reprotect": {
"policyusername": "user1",
"newdataelementname": "deName",
"olddataelementname": "Alphanum",
"bulk": {
"id": "1",
"data": [
{
"content": <Data encoded in base64>
}
]
}
}
}
responsePayloadV1:
type: object
properties:
success:
type: bool
error_msg:
type: string
description: When success is false, error_msg is included
results:
type: array
items:
type: string
Example success:
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
}
If the request was successful, the success flag will always be true.
Example failure:
{
"error_msg": "token expired",
"success": false
}
If the request fails, the success flag will always be false.
Multi Data Elements Support Payload
responsePayloadV2:
type: object
properties:
success:
type: boolean
results:
type: array
items:
type: object
properties:
success:
type: bool
error_msg:
type: string
description: When success is false, error_msg is included
id:
type: string
description: When id is sent in the request payload, id is included in the response
results:
type: array
items:
type: string
Example success:
{
"encoding": "utf8",
"results":[
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
},
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
}
],
"success": true
}
If the all the subrequests were successful, the success flag will be true.
Example failure:
{
"results": [
{
"error_msg":
"Protect failed. Data element not found. Refer to audit log for details",
"success": false
},
{
"encoding": "utf8",
"results":["str1","str2"],
"success": true
}
],
"success": false
}
It is possible to have a mix of successful and unsuccessful results. In this case, the global success flag will be false.
Example:
{"protect":{"bulk":{"returntype":"success","data":[{"returntype":"success","message":"Data
protection was successful.","content":"RGZBUFR4ODAzejFwNjQ5TWg0TEFpcFNqbA=="},{"returntype":"success",
"message":"Data protection was successful.","content":"aHNnVVB5QWFDYw=="}]}}}
Stored secret verification example using jwt_verify and jwt_secret_base64 configurations:
Parameter | Value | Notes |
|---|---|---|
authorization | JWT | |
jwt_verify | 1 |
|
jwt_secret_base64 | Secret in base64 encoding. For example, the value of the public key is as follows. This public key will be stored as follows. | The secret must be in base64. We recommend using RSA public certificates, it is not recommended to keep Hash (symmetric) secrets in the clear. |