Skip to content

Masking PETs User Guide

This guide provides an overview of the masking Privacy Enhancing Technologies (PETs) available for data protection. These PETs are accessible via API and Spark integrations.

Deterministic Masking and SnapshotDate

Most masking in eXate is deterministic: the same input always produces the same masked output, regardless of which system or user is requesting it (see List for how this works for substitution specifically). This matters for testing and analytics, since relationships between records stay consistent even though the underlying values are fake.

To keep that output consistent across runs, eXate uses a SnapshotDate, a seed value that anchors the masking calculation so repeated tests against the same data produce identical results. If you need masking to vary between runs instead (non-deterministic), this can be specified in the running context rather than relying on the default seeded behaviour.

Table of Contents

  1. Mask Attribute
  2. Mask Substitution
  3. Mask Unstructured
  4. Mask Conditional

Mask Attribute

The Mask Attribute PET provides deterministic masking for various data types while preserving data utility and format characteristics.

Supported Data Types

String

Masks string values with configurable character sets and partial masking options.

Configuration Parameters: - preserveStringLength (boolean, default: true) - Maintains original string length - maximumFieldLength (integer, optional) - Limits output length - attributeType (string) - Specifies string subtype: - none - Generic string masking - iban - International Bank Account Number format - email - Email address format - ipAddress - IP address format - phoneNo - Phone number format - charSet (string, optional) - Character set for output: - hash - Hexadecimal characters - numeric - Numbers only (0-9) - alphabets - Letters only (a-zA-Z) - alphanumeric - Letters and numbers - partMask (object, optional) - Partial masking configuration for preserving portions of data

Use Cases: - Masking names, addresses, and identifiers - Protecting email addresses while maintaining format - Anonymizing IBAN numbers with valid country codes - Masking IP addresses within specified ranges - Protecting phone numbers

Integer

Masks integer values while maintaining numeric properties.

Configuration Parameters: - preserveStringLength (boolean, default: true) - Maintains digit count - maxValue (integer, optional) - Upper bound for masked values - minValue (integer, optional) - Lower bound for masked values - attributeType (string) - Specifies integer subtype: - default - Standard integer masking - none - Integer masking with partial mask options - partMask (object, optional) - Partial masking configuration

Use Cases: - Masking account numbers - Protecting transaction IDs - Anonymizing age or count values

Decimal

Masks decimal/floating-point numbers while preserving precision structure.

Configuration Parameters: - preserveStringLength (boolean, default: true) - Maintains format structure - Automatically preserves decimal point position and fractional length

Use Cases: - Masking financial amounts - Protecting measurement values - Anonymizing percentages and rates

DateTime

Masks date and time values with flexible format preservation.

Configuration Parameters: - datetimeInputFormat (string, default: "yyyy-MM-dd HH:mm:ss[.SSS]") - Input date format - datetimeOutputFormat (string, default: "yyyy-MM-dd HH:mm:ss[.SSS]") - Output date format - preservePart (array, optional) - Parts to preserve: - Year - Keep original year - Month - Keep original month - Day - Keep original day - Time - Keep original time components - preserveData (boolean, optional) - Enable safe mode for invalid dates

Use Cases: - Masking birth dates while preserving year - Protecting transaction timestamps - Anonymizing appointment dates

Boolean

Masks boolean values deterministically.

Configuration Parameters: - No additional configuration required - Produces consistent true/false output based on input

Use Cases: - Masking yes/no flags - Protecting binary status indicators

Unique Numeric

Provides format-preserving encryption for numeric values, ensuring uniqueness and reversibility.

Configuration Parameters: - precision (integer, optional) - Total number of digits - scale (integer, optional) - Number of decimal places - Minimum precision: 6 digits - Supports integers (Short, Integer, Long) and decimals

Use Cases: - Protecting unique identifiers that must remain unique - Masking account numbers requiring reversibility - Anonymizing customer IDs in analytics

Unique String

Provides format-preserving encryption for string values, ensuring uniqueness.

Configuration Parameters: - length (integer, default: 255) - String length - Minimum length: 4 characters - Maximum length for FPE: 63 characters (longer strings use hash-based masking)

Use Cases: - Protecting unique usernames - Masking product codes - Anonymizing reference numbers

Global Configuration

Common Parameters: - isConsistent (boolean) - Ensures consistent masking across runs using snapshot date - isDataConsistent (boolean) - Alternative consistency flag - attributeCode (string, required) - Unique identifier for the attribute - thirdPartyId (integer, required) - Third party identifier - firmId (integer, required) - Firm identifier - snapshotDate (datetime, optional) - Date for consistent masking - protectNullValues (boolean, default: true) - Whether to mask null values

Mask Substitution

The Mask Substitution PET replaces values with predefined alternatives from a lookup list or AI-generated values.

Configuration Parameters

  • lookupsValue (array, required) - List of substitution values
  • Standard list: ["value1", "value2", "value3"]
  • AI-generated: ["$genai$: Generate 50 common first names"]
  • isConsistent (boolean) - Deterministic substitution based on snapshot date
  • isDataConsistent (boolean) - Alternative consistency flag
  • preserveStringLength (boolean, default: false) - Truncate to original length
  • maxLength (integer, optional) - Maximum output length
  • dataType (string) - Expected data type: string, integer, decimal, datetime
  • protectNullValues (boolean, default: true) - Whether to mask null values

Use Cases

  • Replacing names with pseudonyms from a predefined list
  • Substituting product names with generic alternatives
  • Using AI to generate realistic replacement values (e.g., addresses, company names)
  • Masking categorical data with consistent alternatives

AI-Generated Substitutions

Prefix lookup values with $genai$: followed by a prompt: - $genai$: Generate 50 common street names - $genai$: Generate 30 technology company names - $genai$: Generate 40 job titles

The system caches AI responses for performance and consistency.

Mask Unstructured

The Mask Unstructured PET identifies and masks sensitive entities in free-text data using machine learning models.

Configuration Parameters

  • targetLabels (array, required) - Entity types to detect and mask:
  • PERSON - Personal names
  • LOCATION - Geographic locations
  • ORGANIZATION - Company/organization names
  • DATE - Date references
  • EMAIL - Email addresses
  • PHONE - Phone numbers
  • CREDIT_CARD - Credit card numbers
  • SSN - Social Security Numbers
  • Custom labels based on model
  • modelType (string, required) - ML model to use for entity detection
  • authorisationToken (string, required) - Authentication token for the service

Functionality

Masking Mode: - Replaces detected entities with 'X' characters - Preserves text structure and length - Processes text in chunks for large documents

Classification Mode: - Returns detected entities with positions and confidence scores - Useful for analysis without modification

Use Cases

  • Redacting personal information from documents
  • Masking sensitive data in customer feedback
  • Protecting PII in email content
  • Anonymizing medical records
  • Sanitizing legal documents

Mask Conditional

The Mask Conditional PET applies different masking strategies based on runtime conditions and access rules.

Configuration Parameters

  • petConditionGroups (array, required) - Ordered list of condition groups
  • groupOrder (integer) - Evaluation order
  • petConditions (array) - Conditions within the group
    • conditionType (string) - Type: ClaimPack or DataUsage
    • entityId (integer) - Entity identifier to check
    • logicalOperator (string) - AND, OR, or NONE
    • conditionOrder (integer) - Order within group
  • petToBeApplied (integer) - PET ID to apply if conditions match
  • applyDefaultPETFromAttribute (boolean) - Use attribute's default PET if no conditions match
  • defaultPETToBeApplied (integer, optional) - Fallback PET ID

Evaluation Logic

  1. Conditions are evaluated in order by groupOrder
  2. Within each group, conditions are evaluated by conditionOrder
  3. Logical operators combine condition results
  4. First matching group determines the PET to apply
  5. If no groups match:
  6. If access is granted, return original value
  7. Otherwise, apply default PET

Use Cases

  • Applying different masking levels based on user roles
  • Conditional data protection based on data usage agreements
  • Dynamic masking based on claim pack authorization
  • Context-aware data anonymization
  • Implementing data access policies with varying protection levels

Example Scenario

Condition Group 1 (Order: 1):
  - ClaimPack ID 100 AND DataUsage ID 5 → Apply PET 10 (Full masking)

Condition Group 2 (Order: 2):
  - ClaimPack ID 100 → Apply PET 20 (Partial masking)

Default:
  - Apply PET 30 (Minimal masking)

Best Practices

  1. Consistency: Enable isConsistent for reproducible results across multiple runs
  2. Testing: Validate masking configurations with sample data before production use
  3. Performance: Use appropriate precision/length settings to balance security and performance
  4. Null Handling: Configure protectNullValues based on your data quality requirements
  5. Format Preservation: Use preserveStringLength when maintaining data structure is important
  6. Unique Values: Use Unique Numeric/String PETs when uniqueness must be preserved
  7. Unstructured Data: Select appropriate target labels and models for your text content
  8. Conditional Logic: Order condition groups from most specific to most general

Notes

  • All masking operations are deterministic when consistency flags are enabled
  • Masked values maintain referential integrity within the same snapshot date
  • Format-preserving encryption (FPE) is used for unique value masking
  • Keys are managed securely through the vault service
  • Unstructured masking requires external ML service connectivity