Manages the encryption policies for the specified DB policy or database object, controls autostart status, and administers keystore access.

Syntax

proutil <db-name> -C epolicy manage 
      { <object-type> { encrypt | cipher | rekey | update } 
                      <object-name> [ -Cipher <cipher-number> ] |
        dbpolicy { rekey [ pending ] [ -Cipher <cipher-number> ] | activate | retire } |
        reconstruct | 
        userphrase | 
        adminphrase |
        autostart { admin | user | disable | refreshhsm } |
        rebind [ { -HSMSlotID <slot-number> | -HSMLabel <label-name> } ] |
        enablehsm <hsm-config> -HSMLibrary <library-path> 
            { -HSMSlotID <slot-number> | -HSMLabel <label-name> }
            [ -HSMAutostart { enable | disable } ] [ -HSMPrivate ] }

Parameters

db-name
Specifies the name of the database.
object-type
Specifies the type of database object being managed. Valid object types are: area, index, lob, and table.
encrypt
Specifies that the action on the object is to encrypt the blocks.
If a pending DB policy is found, you cannot run EPOLICY MANAGE … ENCRYPT.
cipher
Specifies that the action on the object is to change the cipher. You must have previously encrypted the object.
rekey
Specifies that the action on the object is to change the cipher key. You must have previously encrypted the object.
update
Specifies that the action on the object is to update all the blocks of the object. This parameter scans all the blocks in an object and updates the blocks to the current.
object-name
Specifies the name of the object identified by object-type. For the object-type area, the object type must specify a Type I area. For all other object-type values, the specific object must reside in a Type II area.
dbpolicy rekey
Specifies to change the database master key. A new active database master key is created in the keystore.
If no pending or previous encryption DB policy exists in the database, EPOLICY MANAGE DBPOLICY REKEY creates a new active encryption DB policy with the cipher specified in -Cipher. If you do not supply -Cipher, the new policy uses the same cipher as the existing current encryption DB policy.
If a previous encryption DB policy is found and if no object policy uses it, then this parameter retires it This qualifier gives you an option to delete pending encryption DB policies and pending object policies, and then exit.
dbpolicy rekey pending
Specifies to change the database master key, but to place the change in a pending state that can be activated at a later time.
Create a pending DB policy if you want to change the cipher for any encrypted object. You can run EPOLICY MANAGE... UPDATE once to update all object policies to the latest, after you run EPOLICY MANAGE DBPOLICY ACTIVATE.
This qualifier gives you an option to delete the pending policy and then exit.
dbpolicy activate
Specifies to activate a change to the database master key that is currently in a pending state. This command creates a new database master key in the keystore.
-Cipher cipher-number
Specifies the database master policy cipher. If not specified, cipher 1, "AES_CBC_128" is used by default. See PROUTIL EPOLICY INFO qualifier for a list of the supported ciphers and their corresponding ID numbers.
dbpolicy retire
Specifies to delete encryption DB policies in the pending state or retire policies in the previous state. If a policy is found in the pending state, it prompts you to delete the policy. If a policy is found in the previous state, it checks all objects' policies. If no object policy uses the previous encryption DB policy, it retires the previous encryption DB policy.
keystore reconstruct

Specifies regeneration of the database keystore. It prompts you for the database master key passphrase.

You can only reconstruct database master keys generated using a PBE cipher, that is cipher DBS_CBC_PBE for keystores created in Release 12.1 and lower, and cipher AES128_CBC_PBE or cipher AES256_CBC_PBE for Releases 12.2 and higher.

keystore userphrase
Specifies to change the keystore user passphrase. You must make an OS backup of the keystore file before you run this command. It prompts you for the user passphrase, and to confirm backup, unless you use the -silent parameter to suppress the prompt about OS backup. A blank passphrase is acceptable. The database must be in single-user mode to run this command.
keystore adminphrase
Specifies to change the keystore admin passphrase. You must make an OS backup of the keystore file before you run this command. The command prompts you for the admin passphrase, and to confirm backup, unless you use the -silent parameter to suppress the prompt about OS backup. A blank passphrase is not acceptable. The database must be in single-user mode to run this command.
keystore rebind
Specifies to rebind a new database GUID (globally unique identifier) with the database master policy after executing PROCOPY -newinstance. Running this command always prompts you for the keystore admin passphrase.
keystore EnableHSM
Enables HSM as secondary authentication for TDE keystore, when you upgrade an encryption-enabled database to OpenEdge 12.6.
hsm-config
Specifies the name of the keystore file encryption key identified by hsm-config.
-HSMLibrary library-path

Specifies the location of the library, which must be an absolute path. This library is loaded at runtime and must be secured by the server administrator. For OpenEdge Replication, this location must be the same for the source and target machines because this record is replicated. Symlinks are disallowed because they are a security vulnerability. The library must meet the requirements in the Notes section.

The location of the library in the database is controlled by EnableHSM, a PROUTIL EPOLICY MANAGE option that requires the TDE Admin passphrase to operate.

-HSMSlotID slot-number
Specifies the numeric ID of the HSM device token as seen by the server HSM client library. The Slot ID is used to locate and connect to a specific HSM device token on the server.
This slot is stored in the database and must be retrievable to open the keystore.
-HSMLabel label-name
Specifies an HSM Admin assigned tag in the HSM device token. This token, is unique among all HSM tokens and can be used to locate and connect to your database’s assigned HSM token instead of using an HSM Slot ID. This label must be retrievable at all times to open the keystore.
-HSMAutostart
Enables or disables autostart in the HSM, ignoring the TDE keystore's autostart configuration. If this parameter is not specified, EnableHSM puts the HSM token into autostart according to the TDE keystore's autostart configuration.
-HSMPrivate
Configures EnableHSM to store all OpenEdge data in the private storage space. Because OpenEdge by default stores some data into public storage space in the HSM, EnableHSM fails if an HSM configuration does not offer public storage space, unless this parameter is specified.
HSMAutostart is not supported with the HSMPrivate parameter. A user must always enter a PIN when opening the database and logging into the keystore.
keystore DisableHSM
Disables HSM as secondary authentication for TDE keystore.
keystore RepairHSM
Repairs the HSM in case of a system or environment issue, such as an upgrade in the library that changes the absolute path to the library. Also used if the HSM administrator needs to move the token to a different slot number or rename the label. If you specify a library, you must also specify the PIN. The library must meet the requirements in the Notes section.
autostart user
Specifies that the database can be started in unattended mode with the keystore user account.
autostart admin
Specifies that the database can be started in unattended mode with the keystore admin account.
autostart disable
Specifies that the database cannot be started in unattended mode.
autostart RefreshHSM
Repairs user or admin autostart if you enable HSM, then the HSM administrator changes the token's PIN.
-userid userid -password password
Specifies the user ID and password of an authenticated Database Administrator.
-Passphrase
Specifies to prompt the user for the keystore administrator passphrase for authenticating the keystore before running this command.
-Pin
Required along with passphrase to authenticate the keystore after you enable HSM as a secondary authentication requirement for a TDE-enabled database, The -Pin qualifier never applies for a remote connection.
-silent
Suppresses the message that asks if you backed up the existing keystore.

Notes

  • PROUTIL EPOLICY MANAGE requires Database Administrator and keystore administrator privileges.
  • Operations on areas must be performed while the database is offline.
  • For details on TDE, see Transparent Data Encryption and OpenEdge Getting Started: Core Business Services - Security and Auditing.
  • PROUTIL EPOLICY MANAGE DBPOLICY REKEY and DBPOLICY ACTIVATE create new epolicy cache entries for each encrypted object in one transaction. There is an existing limitation on the minimal size of the BI cluster to support the operation. PROUTIL EPOLICY MANAGE DBPOLICY REKEY and DBPOLICY ACTIVATE precalculate the needed BI cluster size. If the existing BI cluster size is too small, the operation fails, and you need to increase the BI cluster size offline to the minimal size required.
  • PROUTIL EPOLICY MANAGE DBPOLICY REKEY PENDING is not limited by BI cluster size.
  • While a DB policy or object policy is pending, you can use PROUTIL EPOLICY MANAGE commands to change the cipher for an object, but cannot use ABL or SQL to change object ciphers.

  • PROUTIL EPOLICY MANAGE DBPOLICY REKEY and DBPOLICY ACTIVATE create a new database master key and active database security policy record. The new DB policy becomes current and the old DB policy becomes previous.

    PROUTIL EPOLICY MANAGE DBPOLICY REKEY also creates a new active object policy for all encrypted objects. This new object policy becomes current and the old object policy becomes previous.

    Before the operations proceed, the utility prompts you to back up your database and keystore. A failed disablement DB policy management or encryption will work only with a backup keystore. To ensure that there is always a keystore backed up before disablement, disablement backs up the keystore without prompting.
    Note: Keystore changes do not automatically apply to a hot standby database during the after-imaging roll-forward operations. To ensure propagation of keystore changes in a replication environment, see Perform roll-forward recovery on encryption-enabled databases.
  • When you enable HSM, you may specify only one token identifier, either the HSM slot ID or the HSM label. Specifying both parameters returns an error.
  • The HSM library must meet one or both platform-specific requirements:
    • On Linux:

      • The library must be in one of these four directories: /lib, /usr/lib,/lib64,/usr/lib64.

      • The file and group owner are both root.

    • On Windows:

      • The library is in C:\Program Files, C:\Windows, C:\Windows\System32, or anywhere below those folders.

      • The owner of the library is the Administrator or SYSTEM account.

  • You may run only one command to enable or disable HSM at one time.