pingcap / pingcap/tidb

[Column Masking] MEDIUM: Design document and implementation signature mismatch

Open
#67,046 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
40.5k
Forks
6.2k
PR merge metrics
PR metrics pending

Description

## Severity
MEDIUM

## Description
The design document describes `MASK_PARTIAL`/`MASK_DATE` (and optional parameters for `MASK_FULL`) inconsistently with the actual implementation.

This directly causes users to write policy expressions that are "parseable but not executable", and amplifies the risk of Issue-2 (point-get fail-open).

## Signature Mismatch Details

### MASK_PARTIAL

**Design Document** (`docs/design/2026-02-27-column-level-masking.md:166`):
```
MASK_PARTIAL(expr[, replace[, start[, length]]])
```

**Actual Implementation** (`pkg/expression/builtin_masking.go:333`):
```go
// Actual signature: MASK_PARTIAL(str, pad, start, length)
// arg count registered in: pkg/expression/builtin.go:655
```

### MASK_DATE

**Design Document**:
```
MASK_DATE(expr, format)
```

**Actual Implementation** (`pkg/expression/builtin_masking.go:503`):
```go
// MASK_DATE(col, 'YYYY-MM-DD') - format is a fixed literal
// Actual behavior may differ from document description
```

### MASK_FULL

The design document describes optional parameters, but actual implementation behavior may not match the documentation.

## Impact

1. **Document Misleading**: Policies written by users following the documentation may not execute
2. **Runtime Errors**: When users use the signature from the document, parsing errors may be triggered
3. **Amplifies fail-open Risk**: If expression parsing fails, per Issue-2, original data may be leaked directly

## Example Risk
```sql
-- User creates policy following documentation (signature may be wrong)
CREATE MASKING POLICY p AS MASK_PARTIAL(col, '****', 2, 4) ENABLE;

-- If signature doesn't match, parsing error may be triggered
-- Based on current fail-open behavior, query returns original value!
SELECT col FROM t WHERE pk = 1; -- leaks original value
```

## Related Code Locations
- `docs/design/2026-02-27-column-level-masking.md:166` - design document signatures (incorrect)
- `pkg/expression/builtin_masking.go:333` - MASK_PARTIAL implementation
- `pkg/expression/builtin_masking.go:503` - MASK_DATE implementation
- `pkg/expression/builtin.go:655` - arg count registration
- `.agents/skills/column-masking-auto-validation/references/column-masking-test-plan.md:17` - test plan claims "AT RESULT semantics"

## Proposed Fix

**Option A (Recommended)**: Update documentation to match implementation

1. Update function signatures in `docs/design/2026-02-27-column-level-masking.md`
2. Update test plan document if needed
3. Add actual function signature documentation
4. Ensure documentation and implementation are completely consistent

**Option B**: Reverse-adjust implementation to match documentation (Not recommended - involves large parser/test changes, may affect existing users)

## Parent Issue
Relates to #65744

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.