Change Field Encryption Entry (CHGFLDENC)

The Change Field Encryption Entry (CHGFLDENC) command allows authorized users to change an existing entry in the Field Encryption Registry.

This command is only allowed for changing an entry with an *INACTIVE status.

The following users can use this command:

  • QSECOFR user profile (unless excluded in the Key Officer settings)
  • A user profile with *SECADM authority (unless excluded in the Key Officer settings)
  • A Key Officer who has a *YES specified for the "Maintain Field Enc. Registry" authority setting

This command requires the user to have *CHANGE authority to the CRVL002 Validation List (*VLDL) object which contains the Field Encryption Registry.

NOTE: The CHGFLDENC command only changes the field entry settings in the registry. It will not cause any action to be performed on the actual database field in the file. The field will not be activated for encryption until the ACTFLDENC (Activate Field Encryption) command is executed.

How to Get There

From the Field Encryption Menu, choose option 3. Or, submit the command CHGFLDENC.

Options

Field identifier (FLDID)

Indicate the unique name of the entry up to 30 characters.

Rules for field identifier:

  • The field identifier does not have to be the same name as the database field name to encrypt.
  • The field identifier cannot contain spaces or certain special characters.
  • The field identifier can contain underscore characters.
  • The field identifier is not case sensitive. It will be stored in upper case.
Database field name (DBFLD)

Indicate the actual name of the database field to register for encryption. A field name up to 30 characters is supported.

The possible values are:

field-name The name of the field (or column name) in the database file to encrypt.
*REMOTE The field is located in a remote database file (not local). Powertech Encryption will manage the encryption and storage of the field values through Tokenization. See Tokenization for Centralizing Sensitive Data for more information.
Database file name (DBFILE)

Indicate the name and library of the database file which contains the field to register.

Database field type (DBFLDTYP)

Indicate the data type of the database field.

The possible values are:

*BLOB The field is a binary large object type.
*CHAR The field is character type.
*CLOB The field is a character large object type.
*DATE The field is a date data type. This option is only valid when using a DB2 Field Procedure to automatically encrypt/decrypt the field values.
*DEC The field is decimal type. This includes packed decimal and zoned decimal types.

If using a DB2 Field Procedure to automatically encrypt/decrypt the field values, then *DEC can also be used to indicate an Integer data type.

*TIME The field is a time data type. This option is only valid when using a DB2 Field Procedure to automatically encrypt/decrypt the field values.
*TIMESTAMP The field is a timestamp data type. This option is only valid when using a DB2 Field Procedure to automatically encrypt/decrypt the field values.
Database field length (DBFLDLEN)

Indicate the length of the values within the database field to encrypt.

For *CHAR type fields, the maximum allowable length is 32624.

For VARCHAR, the length parameter must be the length of the DB2 field plus 2 bytes (to accommodate the end-of-string delimiter).

For *DEC type fields, the maximum allowable length is 30.

If not using a DB2 Field Procedure and if you only want to encrypt a left portion of an alphanumeric field, then you can specify a length that is less than the actual field length.

NOTE: If you specify a length that is less than the actual database field length, then any remaining bytes in the field will be cleared during the field activation process.
Database field decimal pos (DBFLDDEC)

For *DEC type database fields, indicate the number of decimal positions (scale) in the field.

Allowable range is 0 to 4.

Encryption algorithm (ALGORITHM)

Indicate the encryption algorithm to use for encrypting and decrypting the database field values.

This should match the algorithm used to create the Symmetric Key specified on the ENCKEYLBL parameter.

The possible values are:

*AES256 Use Advanced Encryption Standard (AES) algorithm and a 256 bit key.
*AES192 Use Advanced Encryption Standard (AES) algorithm and a 192 bit key.
*AES128 Use Advanced Encryption Standard (AES) algorithm and a 128 bit key.
*TDES Use Triple Data Encryption Standard (TDES) algorithm.
Algorithm mode (MODE)

Indicate the mode to use within the encryption algorithm.

The possible values are:

*CBC Mode is Cipher Block Chaining (CBC). This is a block-based mode. When using this mode with the AES algorithm, the length of the encrypted data will be a minimum of 16 bytes long. Its block-based length will be divisible by 16 or 24. When using this mode with the TDES algorithm, the length of the encrypted data will be a minimum of 8 bytes long. Its block-based length will be divisible by 8. With CBC mode, you can optionally specify an Initialization Vector (IV) to use as an additional input to the encryption algorithm.

*CUSP Mode is Cryptographic Unit Support Program (CUSP). This is a stream-based mode, which means that the length of the encrypted data will equal the length of the input data. This mode is useful if the field data is not divisible by a block length of 16 or 24 (for AES), and if you want to store the encrypted values in your existing field (if not using DB2 Field Procedures). With CUSP mode, you can optionally specify an Initialization Vector (IV) to use as an additional input to the encryption algorithm.

*ECB Mode is Electronic Code Book (ECB). This is a block-based mode. When using this mode with the AES algorithm, the length of the encrypted data will be a minimum of 16 bytes long. Its block-based length will be divisible by 16 or 24. block-based length will be divisible by 8. With ECB mode, you cannot specify an Initialization Vector. When using this mode with the TDES algorithm, the length of the encrypted data will be a minimum of 8 bytes long. Its block-based length will be divisible by 8. With ECB mode, you cannot specify an Initialization Vector.
Initialization vector (INITVECTOR)

Optional. The Initialization Vector (IV) is an arbitrary value that you can enter, which will be used as an additional input to the encryption algorithm. Therefore, the encrypted output is dependent on the combination of the Initialization Vector, Encryption Key and the Plain Text (the data you want to encrypt).

The Initialization Vector is allowed for *CBC and *CUSP algorithm modes.

The length of the Initialization Vector must not exceed the block length, which is calculated as:

  • 32 bytes for *AES algorithm and *CUSP mode
  • 16 or 24 bytes for *AES algorithm and *CBC mode
  • 8 bytes for *TDES algorithm and *CBC mode
Mask option (MASKOPT)

Indicate the mask option to use for the field when the masked value is requested on a decrypt operation.

The possible values are:

*NONE No masking is performed.
*OPTION1 Exact positions within the field value can be shown or masked using the FLDMASK parameter.
*OPTION2 Only a specified number of digits or characters are shown on the left and right sides of the field using the DIGLEFT and DIGRIGHT parameters. Specify the masking character to use in the FLDMASKV parameter. When using field procedures, you must specify a masking character of 1-9, as only numbers are allowed in numeric fields. Examples when DIGLEFT(4) and DIGRIGHT(4) is specified with FLDMASKV(#) when using field procedures:
  • String ' 1234567890123456' is masked as ' 1234999999993456'
  • String '1234567890123456 ' is masked as '1234999999993456 '
  • Numeric 001234567890123456 is masked as 001234999999993456
  • Numeric 1234567890123456 is masked as 1234999999993456

If you are not using field procedures, a non-numeric character can be used, for example:

  • String ' 1234567890123456' is masked as ' 1234########3456'
  • String '1234567890123456 ' is masked as '1234########3456 '
  • Numeric 001234567890123456 is masked as 001234########3456
  • Numeric 1234567890123456 is masked as 1234########3456
*OPTION3 Used for Date, Time and Timestamp fields. The value entered will be used as the mask value. The mask value must be a proper Date, Time or Timestamp value for the field being masked. It is recommended to specify a mask value that does not conflict with an existing value in your database. For instance, for a date field, you may want to specify a mask value with a high value date of 9999-12-31. The format of the mask value must be in the format of the field format. For example if the "Date Format" of a field is *ISO, then the format of the masked value must be *ISO.

Examples:

  • Date '9999-12-31'
  • Time '24.00.00'
  • TimeStamp '9999-12-31-24.00.00.000000'
NOTE: When specifying *OPTION3, you should not specify a not-authorized fill value.
Field mask (FLDMASK)

Indicate the masking format to apply to the field when the masked value is requested on a decrypt operation. Valid for MASKOPT(*OPTION1) and MASKOPT(*OPTION3) masking.

  • For MASKOPT(*OPTION1) masking

Specify the number 9 in a position to show the underlying value for that position. Specify any other character (including spaces) or number in a position to mask the underlying value for that position.

For example, if a mask of '************9999' is specified for a credit card number, then a sample of a masked credit card number would be '************1234'.

As another example, if a mask of '##99##999' is specified for an account number, then a sample of a masked account number would be '##76##541'.

When the field type is numeric the whole number is masked. The decimals values are not. The Mask must not be longer than the whole number length. When using field procedures the mask value must be numeric. For example, if a mask of '779977999' is specified for an account number, then a sample of a masked account number would be '774577541'.

  • For MASKOPT(*OPTION3) masking

You must enter in a valid Date, Time or Timestamp value. This will be the value used as the mask.

Examples:

  • Date '9999-12-31'
  • Time '24.00.00'
  • TimeStamp '9999-12-31-24.00.00.000000'

Used for Date, Time and Timestamp fields. The value entered will be used as the mask value. The mask value must be a proper Date, Time or Timestamp value for the field being masked.

It is recommended to specify a mask value that does not conflict with an existing value in your database. For instance, for a date field, you may want to specify a mask value with a high value date of 9999-12-31.

The format of the mask value must be in the format of the field format. For example if the "Date Format" of a field is *ISO, then the format of the masked value must be *ISO.

Examples:

  • Date '9999-12-31'
  • Time '24.00.00'
  • TimeStamp '9999-12-31-24.00.00.000000'
NOTE: When specifying *OPTION3, you should not specify a not-authorized fill value.
Char/Digits to show on left (DIGLEFT)

When a masked value is requested on a decrypt operation, indicate the number of characters or digits to show on the left side of the field value. Valid for MASKOPT(*OPTION2) masking.

For a character field, any leading blank characters will be ignored when performing the masking. For a decimal field, any leading zeros will be ignored.

Char/Digits to show on right (DIGRIGHT)

When a masked value is requested on a decrypt operation, indicate the number of characters or digits to show on the right side of the field value. Valid for MASKOPT(*OPTION2) masking.

For a character field, any trailing blank characters will be ignored when performing the masking.

Masking Value (FLDMASKV)

The value to be used as the masking character or number. Valid for MASKOPT(*OPTION2) masking.

When masking a numeric field and using DB2 Field Procedures, the mask value must be a number between 1 and 9.

When masking a character field, or when masking a numeric field and not using DB2 Field Procedures, the mask value can be any character or number.

Auth. list for full value (AUTLDEC)

Indicate the IBM i Authorization List that should be used to determine which users have authority to the full field values on decrypt operations.

This Authorization List will be used in field decryption APIs and DB2 Field Procedures.

The possible values are:

authorization-list-name Indicate the name of the Authorization List. An Authorization List can be created with the IBM i command CRTAUTL. The users (or user groups) which need access to the decrypted values will need at least (*USE) authority to the Authorization List. Additionally, the users (or user groups) which need access to the decrypted values are required to have at least *USE authority to the Key Store object which holds the Decryption Key.

*NONE An Authorization List should not be used by the decrypt operations. Therefore the user can gain access to the fully decrypted values as long as they have at least *USE authority to the Key Store which holds the Decryption Key.
Auth. list for masked value (AUTLMASK)

Indicate the IBM i Authorization List that should be used to determine which users have authority to the masked field values on decrypt operations.

This Authorization List will be used in field decryption APIs and DB2 Field Procedures.

The possible values are:

authorization-list-name Indicate the name of the Authorization List. An Authorization List can be created with the IBM i command CRTAUTL. The users (or user groups) which need access to the masked values will need at least (*USE) authority to the Authorization List. Additionally, the users (or user groups) which need access to the masked values are required to have at least *USE authority to the Key Store object which holds the Decryption Key.

*NONE An Authorization List should not be used by the decrypt operations. Therefore the user can gain access to the masked values as long as they have at least *USE authority to the Key Store which holds the Decryption Key.
Auth. list caching (AUTLCACHE)

Indicate if the permissions for authorization lists are 'cached' in memory.

The possible values are:

*YES Caching will occur. When a field decrypt operation is performed, the permissions for the authorization lists will be saved (in memory) and used in future authority checks [for decrypt operations] within the job. This caching option provides the best performance.
NOTE: To recognize any permission changes to the authorization lists, the jobs [that are performing decrypt operations] will need to be restarted.
*NO Caching will not occur. The permissions to the authorization lists will be checked each time a decrypt operation is performed. This option is useful when you want changes to the authorization lists to be immediately recognized by jobs that are performing decrypt operations, or if you want to take advantage of program adopted authority when determining permissions to an authorization list.
Not authorized fill value (NOTAUTHFV)

Indicate the 1-byte value to fill the returned value on a decryption request (from a DB2 Field Procedure or a Powertech Encryption 'auth' API) if the user is not authorized to either the full or masked authorization lists.

For instance, if the fill value is '9' and the field length is 7, then the value of '9999999' will be returned on an unauthorized decryption request.

NOTE:  
  • The fill value is required when a DB2 Field Procedure is utilized and the return value (FLDPROCOPT) is set to *AUTH.
  • If the field type is *CHAR, then the fill value can be a number, letter or special character (e.g. #, *, %).
  • If the field type is *DEC, then the fill value can be a number from 1 through 9 if a DB2 Field Procedure is being utilized, otherwise it can be number from 0 through 9.
  • The fill value is not allowed for field types of *DATE, *TIME and *TIMESTAMP.
Store values in external file (STREXTFILE)

Indicate if the encrypted field values should be stored in a separate external file.

The encrypted values must be stored in an external file if not using a DB2 Field Procedure and if any of the following conditions are met:

  • If the field type is *DEC.
  • For *AES128, *AES192 and *AES256 algorithms with *CBC or *ECB modes: If the field type is *CHAR and the length specified for DBFLDLEN is not divisible by 16 or 24.
  • For *TDES algorithm: If the field type is *CHAR and the length specified for DBFLDLEN is not divisible by 8.

The possible values are:

*YES Store the encrypted field values in an external file.
*NO Store the encrypted values in the existing database field.
External file name (EXTFILE)

Indicate the name and library of the external physical file which will be created to contain the encrypted field values.

The possible values are:

external-file-name Indicate the name of the external physical file object to store the encrypted values.

This object name must NOT already exist.

*GEN Powertech Encryption will automatically generate the external physical file object name, which uses the naming convention of CRXXnnnnn (where nnnnn is a sequential number from 1 to 99999).

The possible library values are:

library-name Indicate the name of the library to create the external physical file in.
*DBLIB Specify *DBLIB for the library name to indicate that the external physical file should be created in the same library as where the database file (which contains the field to encrypt) resides.

The external physical file will be keyed by the Field Identifier (XXFLDID) and the Index Number (XXINDEX).

External logical file name (EXTFILEL)

Indicate the name and library of the logical file which will be built over the external physical file, which will be keyed by the Field Identifier (XXFLDID) and the Encrypted Value (XXVALUE).

The possible values are:

*NONE The logical file will not be created.
external-logical-file-name Indicate the name of the logical file object over the external physical file.

This object name must NOT already exist.

*GEN Powertech Encryption will automatically generate the logical file object name, which uses the naming convention of CRXXnnnnnL (where nnnnn is a sequential number from 1 to 99999).

The possible library values are:

library-name Indicate the name of the library to create the external logical file in.
*DBLIB Specify *DBLIB for the library name to indicate that the external logical file should be created in the same library as where the database file (which contains the field to encrypt) resides.
Store hash for security check (EXTSTRHASH)

Indicate if a HASH value should be stored for each record in the external file.

The possible values are:

*YES A HASH value will be stored for each record in the external file. The HASH value is an encrypted value which is calculated based on the Field identifier, Index number and Key id for each record. When Powertech Encryption retrieves a record from the external file, it will recalculate the HASH and compare it to the stored HASH. A mismatch in the HASH values will indicate that an unauthorized change was made to the external file record's Field identifier, Index number and/or Key id.

*NO A HASH value will not be stored in the external file.
Store last retrieved user/time (EXTSTRRTV)

Indicate if the user id and timestamp of when a field's value was last retrieved(decrypted) should be stored for each record in the external file.

NOTE: You can additionally turn on audit logging for a Decryption key to log each time the key is used to decrypt data.

The possible values are:

*YES Stores the last retrieved user/time in the external file.
*NO Does not store the last retrieved user/time in the external file.
Align index number (INDEXALIGN)

When encrypting a character (alphanumeric) type field which is stored in an external file, then indicate how the external index number should be aligned in the field.

The possible values are:

*LEFT The index number should be aligned on the left side of the database field.
*RIGHT The index number should be aligned on the right side of the database field.
Index padding character (INDEXPAD)

When encrypting a character (alphanumeric) type field, indicate a padding character to place in the unused positions of the field.

For instance, if a padding character of "*" is specified with an alignment of *LEFT, then a 10 position field value with an index of 895 would appear as "895*******".

The padding character cannot be a number, a single quote (') or a dash (-).

Last index number storage (LSTINDSTG)

Indicate the object type to store the 'last index number used'.

Each time a record is written (inserted) to the external file, the 'last index number used' is retrieved from the object, increased by 1, assigned to the new record and saved back to the object.

The possible values are:

*FLDREG Store the last index number used in the field registry object, which is a validation list (*VLDL) with the name of CRVL002.
*PF Store the last index number used in a physical file with the name of CRPF002. A physical file may be easier to replicate (than a *VLDL) with a High Availability tool. A physical file will also provide better performance (than a *VLDL) when a high volume of inserts occurs for the field, due to the file's ability to handle locks more efficiently.
NOTE: If the CRPF002 physical file does not exist, it can be created using the CRTPF command. The source is located in the CRPF002 member in the source file of CRYPTO/QDDSSRC.
Use triggers to auto encrypt (USETRG)

Indicate if SQL triggers should be created over the database file, which will automatically encrypt the database field values without having to change your applications.

NOTE: SQL triggers are not allowed for encryption if a DB2 Field Procedure is already specified with USEFLDPROC(*YES).

They are mutually exclusive.

The possible values are:

*YES SQL triggers will be created over the database file.
*NO SQL triggers will not be created. You will need to use a DB2 Field Procedure or call Powertech Encryption encryption APIs from within your application programs to encrypt the field values.
Trigger name for inserts (INSTRG)

Indicate the name and library of the trigger to create. This trigger will be used to automatically encrypt the field value when records are inserted (added) into the database.

The possible values are:

trigger-name Specify the name of the trigger to create. Rules for trigger names:
  • The trigger name cannot exceed 80 characters in length.
  • The trigger name cannot be the same name as a trigger that is already on the database file.
  • The trigger name cannot contain spaces or certain special characters.
  • The trigger name can contain underscore characters.
  • The trigger name is not case sensitive. It will be stored in upper case.
*GEN Specify *GEN to automatically generate the trigger name, which uses the naming convention of "FILENAME_FIELDNAME_CryptoInsert".

The possible library values are:

library-name Indicate the name of the library to create the trigger object in.
*DBLIB The trigger will be created in in the same library as where the database file resides.
Trigger name for updates (UPDTRG)

Indicate the name and library of the trigger to create. This trigger will be used to automatically encrypt the field value when records are updated in the database.

This is a column trigger, so it is only called when the particular field value is changed.

The possible values are:

trigger-name Specify the name of the trigger to create. Rules for trigger names:
  • The trigger name cannot exceed 80 characters in length.
  • The trigger name cannot be the same name as a trigger that is already on the database file.
  • The trigger name cannot contain spaces or certain special characters.
  • The trigger name can contain underscore characters.
  • The trigger name is not case sensitive. It will be stored in upper case.
*GEN Specify *GEN to automatically generate the trigger name, which uses the naming convention of "FILENAME_FIELDNAME_CryptoUpdate".

The possible library values are:

library-name Indicate the name of the library to create the trigger object in.
*DBLIB The trigger will be created in in the same library as where the database file resides.
Trigger name for deletes (DLTTRG)

This is only valid if an external file is used to store the encrypted values: Indicate the name and library of the trigger to create. This trigger will be used to automatically remove the encrypted field value (record) from the external file when a database record is deleted.

The possible values are:

trigger-name Specify the name of the trigger to create. Rules for trigger names:
  • The trigger name cannot exceed 80 characters in length.
  • The trigger name cannot be the same name as a trigger that is already on the database file.
  • The trigger name cannot contain spaces or certain special characters.
  • The trigger name can contain underscore characters.
  • The trigger name is not case sensitive. It will be stored in upper case.
*GEN Specify *GEN to automatically generate the trigger name, which uses the naming convention of "FILENAME_FIELDNAME_CryptoDelete".

The possible library values are:

library-name Indicate the name of the library to create the trigger object in.
*DBLIB The trigger will be created in in the same library as where the database file resides.
Trigger exit type (TRGEXITTYP)

Indicate if the triggers should call a custom exit program before performing any inserts, updates or deletes of the field value.

Listed below are some examples of how a Trigger exit program could be utilized:

  • To write out additional audit entries in the audit journal file.
  • To direct Powertech Encryption to not process (ignore) the requested insert/update/delete of the field value based on custom criteria, such as the user id or application performing the request.
  • To perform additional custom logic.

A trigger exit program can be written in RPG, COBOL or C on the System i. Source examples of RPG trigger programs are provided in the members of TRGEXTPGM and TRGEXTSRV within the source file of CRYPTO/QRPGLESRC.

The possible values are:

*NONE No Trigger exit program is used.
*PGM The Trigger exit is a Program (*PGM) object.
*SRVPGM The Trigger exit is a Service Program (*SRVPGM) object.
Trigger exit program (TRGEXITPGM)

Indicate the name and library of the trigger exit program to call.

program-name Enter the name of the program or service program.

The possible library values are:

library-name Enter the name of the library where the program is located.
*LIBL Locate the program within the library list.
Trigger exit procedure (TRGEXITPRC)

Indicate the name of the procedure to call if the TRGEXITTYP is *SRVPGM.

Use DB2 field procedure (USEFLDPROC)

Indicate if a DB2 Field Procedure will be used to automatically encrypt/decrypt the field values, which is an alternative approach to using triggers and API calls. A DB2 Field Procedure also allows storing the 'encoded' encrypted values within the existing file, which is especially useful for numeric fields. [You will not need to create a separate external file to store the values for numeric fields.]

DB2 Field Procedures are available in IBM i version V7R1 and higher.

NOTE: DB2 Field Procedures are not allowed if SQL triggers are already specified with USETRG(*YES). They are mutually exclusive.

Before using DB2 Field Procedures in a production environment, read the manual to understand the potential performance issues and risks.

The possible values are:

*YES A DB2 Field Procedure will be used to automatically encrypt and decrypt the field values.
*NO A DB2 Field Procedure will not be used. You must use triggers or APIs to encrypt the values. APIs must be used to decrypt the values.
Field procedure return value (FLDPROCOPT)

Indicate which field value is returned (based on user permissions) from the DB2 Field Procedure to the application on a read operation.

The possible values are:

*FULL Returns the fully decrypted value if the user has at least *USE rights to the authorization list specified on the AUTLDEC parameter (or if *NONE is specified on that parameter). Otherwise an error with the message id of CPF504D will be generated in the application performing the read. The *FULL option is available for *CHAR, *DEC, *DATE, *TIME and *TIMESTAMP data types.

*AUTH For character (*CHAR) fields up to 30 bytes in length, this option returns either: 1) the full value if the user has at least *USE rights to the authorization list specified on the AUTLDEC parameter (or if *NONE is specified on that parameter) or 2) the masked value if the user has at least *USE rights to the authorization list specified on the AUTLMASK parameter (or if *NONE is specified on that parameter) or 3) the fill value if the user does not have at least *USE rights to either authorization list. For decimal/numeric (*DEC) fields or character fields over 30 bytes in length, this option returns either: 1) the full value if the user has at least *USE rights to the Authorization List specified on the AUTLDEC parameter (or if *NONE is specified on that parameter) or 2) the numeric masking character and the left/right digit (to show) logic (MASKOPT *OPTION2) if the user has at least *USE rights to the authorization list specified on the AUTLMASK parameter (or if *NONE is specified on that parameter). The fill value is defined in the Change Field Encryption Entry panel (CHGFLDENC). Otherwise (if not authorized), the fill value is returned.
NOTE: A zero value in a numeric field is displayed in clear text and is not masked with the Mask character or Not Authorized character.
The *AUTH option is valid for *DATE, *TIME and *TIMESTAMP data types only when the MASKOPT parameter is either *NONE or *OPTION3.
Decryption Accelerator (PERFACCEL)

Allows Powertech Encryption for IBM i to apply methods to attempt to improve performance gains when possible with native i/o.

The possible values are:

*YES See Appendix G: Decryption Accelerator Prerequisites and Limitations for considerations and prerequisites. Apply methods to attempt to improve performance gains when possible.
*NO Do not apply methods to attempt to improve performance gains when possible.