Skip to main content

How to use transformation (FPE and masking)

Strongbox transformation lets you protect sensitive values while keeping their format intact. Two modes are available:

  • FPE (format-preserving encryption): the output has the same format as the input and can be decrypted to recover the original.
  • Masking: characters are replaced with a masking character (default *). Masking is irreversible and is suitable for logs and audit trails.

Set up a transform service​

Credit card numbers (built-in template)​

The creditcardnumber template covers 16-digit credit card numbers using a numeric alphabet.

supctl create strongbox transform <<EOF
name: cc-protect
type: fpe
template: creditcardnumber
distribute:
  to: all
EOF

Custom template​

Specify a template block with an alphabet and a pattern. The pattern is a regular expression where each capturing group is the part subject to transformation.

Alphabet valueCharacters included
numeric0-9
alphalowera-z
alphaupperA-Z
alphanumericlower0-9, a-z
alphanumericupper0-9, A-Z
alphanumeric0-9, a-z, A-Z
custom binary stringSupply the exact set of characters to allow

Example -- protect only the middle group of a hyphenated identifier (for example PROD-000123-EU):

supctl create strongbox transform <<EOF
name: order-id
type: fpe
template:
  alphabet: numeric
  pattern: "[A-Z]+-([0-9]+)-[A-Z]+"
distribute:
  to: all
EOF

Masking setup​

Masking replaces matched characters with * (or a custom character). It is useful when you need to record that a value was present without storing the actual value.

supctl create strongbox transform <<EOF
name: cc-mask
type: masking
masking-character: "*"
template: creditcardnumber
distribute:
  to: all
EOF

Encrypt data (FPE)​

Encrypt a credit card number. The result has the same 16-digit format.

supctl do strongbox transform cc-protect encrypt --plaintext 4111111111111111
ciphertext: 7823049165830274

Encrypt with a tweak. The surrounding context (for example the cardholder name) is supplied as tweak. The same tweak must be provided at decryption time.

supctl do strongbox transform cc-protect encrypt \
  --plaintext 4111111111111111 \
  --tweak "alice"

Decrypt data (FPE only)​

supctl do strongbox transform cc-protect decrypt --ciphertext 7823049165830274
plaintext: 4111111111111111

With a tweak:

supctl do strongbox transform cc-protect decrypt \
  --ciphertext 7823049165830274 \
  --tweak "alice"

Mask data​

Masking is performed with the same encrypt command. The result cannot be reversed.

supctl do strongbox transform cc-mask encrypt --plaintext 4111111111111111
ciphertext: ****************

Understanding tweaks​

A tweak is additional input supplied alongside the data being encrypted. It prevents an attacker from correlating encrypted values by comparing different ciphertexts.

For example, if you encrypt only the middle four digits of a longer number, the same four digits at different positions in different numbers would encrypt to the same ciphertext -- unless the surrounding digits are provided as a tweak. With the surrounding text as tweak, the same four digits encrypt differently in different contexts.

Three tweak modes are available:

tweak-source valueBehavior
calculatedTweak is derived automatically from surrounding text
suppliedCaller provides the tweak on each encrypt/decrypt call
generatedTweak is generated by Strongbox and returned

The same tweak used during encryption must be supplied during decryption. If no tweak is required, omit the --tweak flag.

Key rotation​

Transform services use an underlying AES key that can be rotated independently of the transform configuration. Rotate the key:

supctl do strongbox transform cc-protect rotate

After rotation, data encrypted with the previous key can still be decrypted (the key version is embedded in the ciphertext). New encryptions use the latest key version.