In-Flight Masking Basic Setup and Use

• Overview
• Managing Ruleset Plans
  • Viewing Ruleset Plans
  • Creating a Ruleset Plan
  • Editing a Ruleset Plan
  • Deleting a Ruleset Plan
  • Advanced Options
  • Managing Ruleset Plans via the API
• Masking Data
  • Getting Started with curl
  • Authentication
  • Sending Data to a Ruleset Plan
• Consistent Masking with Run Secrets and Hashing

Overview

This page walks through setting up and using in-flight masking. It covers creating a ruleset plan, masking data, and introduces consistent masking.

There are two ways to manage ruleset plans (create, edit, and delete):

1. The DataMasque web interface — a built-in editor with YAML validation and an intuitive workflow. This is the recommended approach and is covered first.
2. The REST API — for automation and programmatic management. Documented in the API Reference.

Masking data is always done via the REST API, by sending data to a ruleset plan's endpoint. This is covered in the Masking Data section.

Note: In-flight masking is not available to Single Sign-On (SSO) users. See Authentication and Permissions for details.

Managing Ruleset Plans

A ruleset plan is a masking endpoint created from a YAML ruleset. Data sent to the endpoint is masked according to the ruleset's rules and returned in real-time.

Ruleset plans can be managed through the DataMasque web interface by navigating to In-Flight Masking in the sidebar.

Permissions

The actions available depend on the user's role:

Action	Admin	Mask Builder	Mask Runner
View the list of ruleset plans	Yes	Yes	Yes
Create, edit, and delete ruleset plans	Yes	Yes	No

Mask Runners can see the list of ruleset plans and their names, but cannot view ruleset content or make changes.

Viewing Ruleset Plans

The In-Flight Masking page shows all ruleset plans in a searchable list.

The search bar filters the list by name and ruleset content. For example, searching for from_file will show any ruleset plan whose name or YAML body contains that text.

Creating a Ruleset Plan

To create a new ruleset plan, click the Add button on the list page.

1. Enter a name for the ruleset plan. A random 6-character suffix will be appended to the name automatically when saved, ensuring each plan has a unique name. For example, entering name-masking will create a plan named something like name-masking-bzdqsp.

2. Write or paste a YAML ruleset into the editor. The editor validates the YAML against the in-flight ruleset schema as you type. A green checkmark indicates the YAML is valid; a red warning indicates errors.

Note: Unlike database and file masking rulesets, which can be saved in an invalid state, In-Flight ruleset plans cannot be saved with invalid YAML or schema errors. Fix any errors shown in the editor before saving.

This example uses a simple ruleset that masks data using random first names:

   version: "1.0"
   rules:
   - masks:
     - type: "from_file"
       seed_file: "DataMasque_firstNames_mixed.csv"

Note: The version indicates the version of the ruleset schema, not the version of the ruleset itself. It should not be confused with the serial of the ruleset plan, which tracks how many times the plan has been updated.

3. Click Save to create the plan, or Save & Exit to create it and return to the list.

After saving, the editor shows the plan's metadata:

• Endpoint URL — the full URL to use when masking data. Click the copy button to copy it to the clipboard.
• Created and Modified timestamps.

The endpoint URL has the format https://<your-dm-instance>/ifm/ruleset-plans/<plan-name>/mask/ and is used to send data for masking, as described in Masking Data.

Editing a Ruleset Plan

To edit an existing ruleset plan, click the edit icon on its row in the list, or navigate directly to its URL.

The name of a ruleset plan cannot be changed after creation. All other fields - the YAML ruleset, enabled status, and advanced options - can be updated.

After making changes, click Save to apply them. The plan's serial number is automatically incremented each time it is updated.

If you navigate away from the editor with unsaved changes, a confirmation dialog will ask whether you want to discard them.

Deleting a Ruleset Plan

Ruleset plans can be deleted from the list page or from the editor.

• From the list: click the delete icon on the plan's row.
• From the editor: click the Delete button.

A confirmation dialog will appear before the plan is deleted.

Note: Deleting a ruleset plan is permanent and removes its masking endpoint. Any clients sending data to the endpoint will receive errors after deletion.

Advanced Options

Click Advanced Options in the editor to configure additional settings for a ruleset plan.

Option	Description	Default
Enabled	Whether the plan accepts masking requests. Disabled plans will reject data.	Enabled
Default Encoding	The encoding format for masking requests.	json
Default Charset	The character set for masking requests. Options: utf-8, utf-16, iso-8859-1, ascii.	utf-8
Default Log Level	The minimum log level included in masking responses. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL.	WARNING

These options set defaults for the ruleset plan. They may be overridden on a per-request basis when masking data.

Seed Files

If the ruleset references seed files (e.g. for from_file masks), click the Seed Files button in the editor to see a list of available seed files and their contents.

Managing Ruleset Plans via the API

Ruleset plans can also be created, updated, and deleted via the REST API. This is useful for automation, CI/CD pipelines, or managing plans programmatically.

Refer to the In-Flight API Reference for full details, including request formats, curl examples, and response schemas.

Masking Data

Once a ruleset plan has been created (via the web interface or API), data is masked by sending HTTP requests to the plan's endpoint.

Getting Started with curl

The examples in this section use the command line tool curl to make HTTP requests. It's recommended to also install jq for formatting JSON output.

The output from curl can be piped through jq to pretty-print JSON:

$ curl -s <url> | jq

If your DataMasque instance uses self-signed SSL certificates, add the -k flag to curl to disable certificate verification.

Authentication

Masking requests require a JSON Web Token (JWT) for authentication. Fetch one by sending your credentials to the login endpoint:

$ curl -X POST "https://<your-dm-instance>/api/auth/jwt/login/" \
-H "Content-Type: application/json" \
-d '{"username": "<your username>", "password": "<your password>"}'

The response includes an access_token:

{
  "refresh_token": "eyJhbGc…JlRU",
  "access_token": "eyJhbGci…_0z1",
  "token_type": "Bearer"
}

Note: JWT tokens in this document are truncated for brevity.

Store the token in a variable for use in subsequent requests:

$ JWT="eyJhbGci…_0z1"

Or as a single command using jq:

$ JWT=$(curl -s -X POST "https://<your-dm-instance>/api/auth/jwt/login/" \
-H "Content-Type: application/json" \
-d '{"username": "<your username>", "password": "<your password>"}' | jq -r '.access_token')

For more details, see Authentication and Permissions.

Sending Data to a Ruleset Plan

Data is masked by making a POST request to the ruleset plan's masking URL.

If you created the plan via the web interface, the masking URL is displayed in the editor and can be copied to the clipboard. For example: https://<your-dm-instance>/ifm/ruleset-plans/name-masking-bzdqsp/mask/.

The data to mask is sent as a JSON object with a data field containing an array of values:

$ curl -X POST "https://<your-dm-instance>/ifm/ruleset-plans/name-masking-bzdqsp/mask/" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-d '{"data": ["Brian"]}'

The response includes the masked values and request metadata:

{
  "request_id": "721fca71-c211-4faa-80f2-2d5e356ef13a",
  "encoding": "json",
  "charset": "utf-8",
  "logs": [],
  "ruleset_plan": {
    "name": "name-masking-bzdqsp",
    "serial": 0
  },
  "data": [
    "Tay"
  ]
}

The response includes:

• Masked values in the data array (maintaining one-to-one mapping with input).
• A unique request_id (automatically generated if not provided).
• Request logs with timestamps and messages.
• Information about the ruleset_plan that performed the masking.
  • The name of the ruleset plan.
  • The serial number of the ruleset plan. This lets you know if masking has been performed with an older version of a ruleset than you expected, which could happen if running in-flight masking on a distributed system (like Kubernetes) and you send a masking request before all instances of DataMasque have updated with the new ruleset.
• Metadata about the encoding and charset.

Consistent Masking with Run Secrets and Hashing

Overview of Consistency

DataMasque allows consistent masked value generation across different masking operations. This means you can mask the same data in different contexts (in-flight, database, or file masking) and get identical results. To generate consistent output values, use the same run secret and hash value(s) across operations. If consistency across multiple DataMasque instances is required, then the instance secret should be disabled too.

At a high level, given the same instance secret, run secret, and hash value, the output value generated will be the same. Depending on the mask type, the output value may also depend on the input value.

Typically, an identifier (such as a user ID) serves as the hash value, ensuring consistent masking across systems.

Consistency With In-Flight Using hash_sources

In-flight rulesets can specify hash_sources. These are a list of places from which to retrieve the hash value. Hash values can be:

• A value inside POSTed JSON data, by specifying a json_path.
• A value inside POSTed XML data (XML inside JSON strings), by specifying an xpath.
• A value from a hash_values array in the request, by specifying from_request.
• An entire pre-masked data element from data, by specifying self.

More information about hash_sources, including the YAML syntax, can be found on the Rulesets documentation.

For this example below, using from_request as a hash source will be illustrated.

Controlling Run Secrets and Instance Secrets with In-Flight Masking

When DataMasque's in-flight server starts, or when a ruleset plan is updated, the ruleset plan receives a random run secret value. This means that value generation with hashing will be consistent only as long as the ruleset plan is unchanged and DataMasque continues running.

Furthermore, the run secret in this case is unknown, and therefore cannot be used when performing database or file masking.

When sending a masking request, if no run_secret is present in the request, then that random run secret will be used. As such, controlling consistency across different masking types is impossible.

Instead, to use a specific run secret when masking with in-flight, specify it as the run_secret value in a masking request.

For consistency across multiple DataMasque instances, the instance secret should be disabled, too. This is done by specifying "disable_instance_secret": true in the masking request.

Note: disable_instance_secret can not be set without also specifying a run_secret.

Now that run secrets have been introduced, let's look at some examples of using hash_sources.

Hashing Examples

The following examples show how to use hash values for consistent masking. We'll start by configuring a ruleset with hash_sources, then explore how hash values affect masked output. Finally, we'll see how run secrets and instance secrets provide additional control over the masking process.

First, update the ruleset plan to add hash_sources. This can be done in the web interface by editing the plan's YAML, or via the API using a PATCH request (see the API Reference).

The updated ruleset:

version: "1.0"
hash_sources:
  - source: from_request
rules:
- masks:
  - type: "from_file"
    seed_file: "DataMasque_firstNames_mixed.csv"

After updating, the plan's serial number will be incremented.

Now hash_values can be sent as part of the request. In this case, we will not send a run_secret, thus the unknown random run secret will be used. This still allows for consistency until the endpoint is updated or DataMasque is restarted.

In this example, we send an array of hash_values of equal length to the data being sent.

Note: The curl commands are omitted for these examples, instead just the body of the request and response are shown. Each will be POSTed to the same masking URL that was used earlier.

{
  "data": ["Darcy", "Molly", "Evelyn"],
  "hash_values": [1283, 1416, 1283]
}

In the example, two hash values are the same, so we got the same output for them.

{
  "data": ["Salma", "Emmie", "Salma"]
}

hash_values may also be a single value instead of an array, but this should only be used when sending a single value for data, as it means all masked values will be the same.

For example, if sending:

{
  "data": ["Darcy", "Molly", "Kye"],
  "hash_values": 1283
}

The response data would be:

{
  "data": ["Salma", "Salma", "Salma"]
}

Each value matches where the hash value was 1283 before, as it is now applied to each item in data.

Note: hash_values must either be an array of the same length as data, or a scalar value. If an array of a different length than data is provided an error will occur.

Run Secret Examples

Now we'll introduce run_secret.

In this example, we will specify a run secret and notice how the output values change even with the same hash_values we saw earlier:

{
  "data": ["Darcy", "Molly", "Evelyn"],
  "hash_values": [1283, 1416, 1283],
  "run_secret": "L7HKnasUhjNC6KsiD7bpo"
}

The output has different values:

{
  "data": ["Tina", "Evie", "Tina"]
}

Similarly, if we disable the instance secret for this request, the output will have different values again:

{
  "data": ["Darcy", "Molly", "Evelyn"],
  "hash_values": [1283, 1416, 1283],
  "run_secret": "L7HKnasUhjNC6KsiD7bpo",
  "disable_instance_secret": true
}

Response:

{
  "data": ["Emmie", "Lana", "Emmie"]
}

Before using run secrets or disabling the instance secret, please refer to Performance Considerations for Run Secrets.

This is the end of the basic setup and introduction. Please refer to the full guides for more information.