Format-Preserving Encryption (FPE) via KMIP + Anonymization REST endpoint #869

Overview

This issue covers two separate but related features:

1. Format-Preserving Encryption (FPE) — cryptographic, key-based, reversible — exposed via KMIP operations only
2. Anonymization / Tokenization REST endpoint — non-cryptographic or irreversible privacy methods — exposed via the dedicated /tokenize endpoint

These two features share no endpoint. FPE is a KMIP cryptographic operation; anonymization is a REST utility.

Part 1 — Format-Preserving Encryption (FPE) via KMIP

Algorithm

FPE-FF1 as specified in NIST SP 800-38G using 18 Feistel rounds. Implementation comes from the cloudproof_rust/crates/fpe library already vendored in the project.

Three data types are supported:

• fpe::Alphabet — encrypts text strings character-by-character, non-alphabet characters (spaces, punctuation, dashes) are preserved in their original positions
  • Pre-defined alphabets: numeric() (0–9), alpha_lower(), alpha_upper(), alpha(), alpha_numeric(), hexa_decimal(), chinese(), latin1sup()
  • Custom alphabets: Alphabet::instantiate("custom_chars")
  • Example: "1234-5678-9012-3456" → "6271-3548-2091-7834" (dashes preserved)
• fpe::Integer — encrypts non-negative integers (u64 or BigUint) with configurable radix (2–16) and digit count
• fpe::Float — encrypts f64 floating-point values

Key material

• Key: 256-bit AES symmetric key (32 bytes)
• Tweak: arbitrary bytes, public per-instance parameter — allows context-dependent encryption without changing the key (e.g. per-column, per-table tweak for database field encryption)
• Constraint: radix^min_len > 1_000_000 must hold

KMIP interface

FPE is exposed exclusively via the KMIP Encrypt and Decrypt operations on the /kmip or /kmip_2_1 endpoints. No dedicated REST endpoint is created for FPE.

Implementation steps:

1. Add FPE_FF1 value to CryptographicAlgorithm enum in crate/kmip/src/
2. Create crate/crypto/src/crypto/fpe/ module wrapping cloudproof_rust/crates/fpe; expose encrypt_fpe / decrypt_fpe functions that accept the KMIP Data, CryptographicParameters (algorithm + alphabet hint), and IV/Tweak fields
3. Route CryptographicAlgorithm::FPE_FF1 in crate/server/src/core/operations/encrypt.rs and decrypt.rs
4. Implement key creation for FPE-FF1 keys (256-bit symmetric AES key, tagged fpe or alphabet)

CLI — ckms fpe

New ckms fpe subcommand modeled on ckms sym, located at crate/clients/clap/src/actions/fpe/:

ckms fpe keys create    # create a 256-bit AES key for FPE-FF1 (tagged fpe-ff1)
ckms fpe encrypt        # encrypt text, integer, or float via KMIP Encrypt
ckms fpe decrypt        # decrypt text, integer, or float via KMIP Decrypt

Encrypt/decrypt commands accept:

• --key-id / --tag — identify the FPE key
• --alphabet — chosen alphabet (numeric, alpha, alpha-numeric, hexa, custom) for Alphabet mode
• --tweak — optional tweak bytes (hex-encoded)
• --type — data type: text (default), integer, float
• Input: stdin or --input-file; Output: stdout or --output-file

Documentation

• Add FPE-FF1 row to the encryption schemes table in documentation/docs/certifications_and_compliance/cryptographic_algorithms/algorithms.md
• Add ### FPE-FF1 detail section in the same file
• Reference FPE from the ckms fpe CLI documentation

Part 2 — Anonymization via /tokenize endpoint

The /tokenize REST endpoint is reserved exclusively for anonymization / privacy-preserving transformations that do not require cryptographic keys managed by KMS. The existing ckms tokenize CLI is kept.

Available methods (from cloudproof_rust/crates/anonymization)

REST interface

POST /tokenize/{method}
Content-Type: application/json

The {method} path segment identifies the anonymization method. Each method accepts a JSON body specific to its parameters.

Documentation

• Create documentation/docs/use_cases/anonymization.md describing all anonymization methods with JSON request/response examples, RFC3339 date format note, and comparison table vs FPE
• Update documentation/mkdocs.yml to add the new page under Use cases

Acceptance criteria

• CryptographicAlgorithm::FPE_FF1 added to KMIP types
• crate/crypto/src/crypto/fpe/ module implemented and tested
• Encrypt/Decrypt KMIP operations route FPE-FF1 correctly
• ckms fpe keys create, ckms fpe encrypt, ckms fpe decrypt commands work end-to-end
• /tokenize endpoint implemented for all 8 anonymization methods
• ckms tokenize CLI updated / verified
• algorithms.md updated with FPE-FF1 row + detail section
• documentation/docs/use_cases/anonymization.md created
• Unit tests for FPE encrypt/decrypt roundtrip with all data types
• Integration tests via ckms fpe encrypt + ckms fpe decrypt roundtrip
• Add necessary UI elements for anonymization

Effort: 8 weeks | No prerequisites | Sprint C