Using the IBM Optim Data Privacy for z/OS API to apply advanced masking

Edit online

The IBM® Optim Data Privacy for z/OS® advanced masking API enables you to apply masking policies to data values and return masked values. You can use this capability for advanced masking methods such as format-preserving encryption and tokenization, ensuring data privacy while maintaining usability.

To apply masking, use the following API endpoint: 
POST /optim/v1/masking/text/process

The masking API accepts:

  • A masking policy that defines the masking method and format.
  • A payload containing input values to be masked.

The IBM Optim Data Privacy for z/OS API returns masked values in the response.

Request body structure

The POST body is a JSON object that includes the following objects:

policy
The policy object specifies the processor type (masking method) and format.
  • The processor type defines the masking method. Different processors have different behaviors, such as input validation and repeatability. The processor type is defined in policy.processors[0].type.
  • The format specifies the domain of values, such as government identification numbers or credit card numbers. The format is required for some processors. The format is defined in policy.processors[0].configuration.format.
Note: To get a list of available masking methods and formats, submit the following API endpoint:
GET /optim/v1/masking/types
payload
The payload object contains an array of input values to be masked.
  • Optional fields:
    • iv: Initialization vector (seed for value generation).
    • key: Encryption key (required for certain processors).

Processor requirements

Processors have different request body requirements.
Processors that require configuration.format
  • FormatPreservingRedactionProcessor
  • RandomFormatFabricationProcessor
  • RepeatableNoiseProcessor
  • RandomNoiseProcessor
Processors that require "iv" in the top-level JSON
  • EncryptionProcessor
  • FormatPreservingEncryptionProcessor
  • FormatPreservingTokenizationProcessor
  • RepeatableFormatFabricationProcessor
  • RepeatableNoiseProcessor
  • TokenizationProcessor
Processors that require ""key" in the top-level JSON
  • EncryptionProcessor
  • FormatPreservingEncryptionProcessor
Processors that require "mode": "tokenize" in configuration
  • FormatPreservingTokenizationProcessor
  • TokenizationProcessor
Processors that require "mode": "encrypt" in configuration
  • EncryptionProcessor
  • FormatPreservingEncryptionProcessor
Processors that require "millipercent" in configuration
  • RandomNoiseProcessor
  • RepeatableNoiseProcessor

Example request and response

Use the sample requests and responses in this section to help you work with the API.

Example input file
Here are the contents of the sample input file mask1.json that will be used in this example scenario.
{
  "policy": {
    "version": "1.0",
    "graph": {
      "nodes": [
        {
          "id": "FPT",
          "root": true
        }
      ],
      "edges": []
    },
    "processors": [
      {
        "id": "FPT",
        "type": "FormatPreservingTokenizationProcessor",
        "configuration": {
          "format": "Countries_CaseSensitive",
          "mode": "tokenize"
        },
        "loggable": true
      }
    ],
    "selectors": [],
    "expressions": [],
    "formats": []
  },
  "iv": "b6dd4a74115729165b063d823b0275a85054f6db7d252dd5ff4dd2278e3268a8",
  "payload": ["Albania", "Chile"]
}
Example request (curl)
Here is the sample request command:
curl -skX POST https://localhost:7725/optim/v1/masking/text/process \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d @mask1.json
Example response
Here is the sample response from the IBM Optim Data Privacy for z/OS masking API:
{
    "_statusCode_": 200,
    "message": "Get masked text successful",
    "messageID": "OPTTC0601I",
    "requestObj": [
        "Маршалловы Острова",
        "澤西"
    ]
}
Explanation of the response
The response masked the values provided in the input JSON. Here are the relevant details:
Processor

FormatPreservingTokenizationProcessor validated the input and generated repeatable masked values.

Format

Countries_CaseSensitive defined the valid domain (country names).

iv

Contained the seed that was used for value generation.

Payload
The results of the masking:
  • Albania → Маршалловы Острова
  • Chile → 澤西