Consistently masks the given values while preserving the original length and (optionally) character group formats. When comparing this function to the similar FORMATFPE1, note that Mask As Number is implied and is not switchable.
The function produces unique values as long as the original values are unique, making it ideal for masking unique columns or fields, such as keys. This function implements (and is compatible with) the FF1 algorithm - the format-preserving algorithm approved by NIST.
Unless specific runtime options are set (see PARM 2), the input is converted to English Lower Case, with French-accented characters replaced by English equivalent. The generated alphabet will depend upon the options set; however, the ‘standard’ is LCENG (a-z) with DIGITS (0-9).
Note: This function doesn't have an associated decrypt functionality.
- Parm1 Master Key or Label (Mandatory) : Values: (See the example for the possible values)
Specifies the encryption key (or label) to be used for underlying AES encryption. The key/label can be defined individually for each column or field. When a Label is used, it must be coded within double quotes.
If an actual Master Key is input, it must be expressed by EBCDIC representation of hexadecimal characters of length 32, 48, or 64, enclosed in double-quotes AND prefixed by a single @ sign.
Note: The keys are translated internally into AES encryption keys of length 128, 192, or 256 bits.
- Parm2 Runtime Options (Optional) : Values: (See the example for the possible values)
This is a ‘combination string’ containing 5 single-byte indicators, NOT separated by commas. Each can be set to Y or N – the default for all 5 is N, known as ‘Case Insensitive.’ Their mapping is as follows:
- Mask Extended: Extended characters are included in the masking alphabet
- Include Special: Special characters are included in the masking alphabet
- Keep Capital: Upper/Lower case attributes are preserved after masking
- Keep Format: Character, Numeric, and Special character attributes are preserved
- Use Tweak: Original value should be used to improve the randomness of the masked value.
- Parm3 Ignore First 'n' (Optional) : Values: 0000 – 9999
Do not process the first 'n' bytes of the input field. These are replicated in the output data stream unchanged
- Parm4 Ignore Last 'n' (Optional) : Values: 0000 – 9999
Do not process the last 'n' bytes of the input field. These are replicated in the output data stream unchanged.
Note: Parms 3 and 4 should be specified as a pair and can be used to define a ‘subset’ to be masked.
- Parm5 Delimiter Value(s) (Optional) : Values: (See the following for the possible values)
Specifies optional delimiter(s) as a space-separated list of single-character and/or keyword delimiters, similar in format to the FORMATENCRYPTDELIMITER runtime option. The given value for encryption is split into (a maximum of 30) segments by the provided delimiters. Each segment is then masked separately. The delimiters themselves are NOT masked and reproduced in the function's encrypted value.
A maximum of 5 (five) delimiter values and/or keywords may be specified, enclosed by double-quotes.
Example: "- SPACE @ /"
- Parm6 Include First 'n' (Optional) : Values: 0000 – 9999
Extract and mask the first 'n' bytes of the input field.
- Parm7 Include Last 'n' (Optional) : Values: 0000 – 9999
Extract and mask the last 'n' bytes of the input field.
Note: Parms 6 and 7, used as a pair, form a data segment from the middle of an input field.
- Parm8 Specifies the replacement character (Optional) : Values: Any character in the masking alphabet
Every character from the input value which is not found in the alphabet is replaced by this character in the masked output. If it isn't specified (which is the default) then the first character not found in the alphabet aborts the masking.