Rotating the Key Encryption Key - Encrypted Alpha Keywords - Foundation 23.1 - Foundation 23.1 - Ready - OnBase - Essential - Premier - Standard - external - Standard - Essential - Premier

Encrypted Alpha Keywords

Platform
OnBase
Product
Encrypted Alpha Keywords
Release
Foundation 23.1
License
Standard
Essential
Premier
Note:

Before rotating the Key Encryption Key (KEK), it is considered a best practice to backup your database.

Rotating the KEK entails modifying certain files in your OnBase solution. These files must then be pushed out, or deployed, to user workstations. After rotating the KEK, users cannot connect to OnBase with previous versions of the OnBase Client and Configuration executables, or by using Core Services with previous versions of Hyland.Core.GrabIcon.dll. They can only connect to OnBase using versions of the OnBase Client and Configuration executables containing the new KEK, or by using Core Services with the new Hyland.Core.GrabIcon.dll.

To rotate the KEK in the OnBase Configuration module:

Note:

You only need to perform these steps on the workstation that will be used to deploy the KEK. After the KEK is rotated, the new files can be copied to other user workstations, as long as those workstations are using the same version of OnBase.

  1. Lock your OnBase database and ensure that there are no users in the system.
    For instructions on locking your OnBase database, see the System Administration documentation.
  2. Stop all OnBase instances, processes, and services.
  3. Stop the OnBase database. This ensures that all users are logged out of the system and all instances, processes, and services are stopped.
  4. Restart the OnBase database.
  5. Log on to the Configuration module as the user and/or workstation configured during system lockout.
  6. Select Utils | Rotate Database Password and KEK (key encryption key).
    Note:

    This option is unavailable if the OnBase database has not been locked.

  7. The Rotate Database Password and KEK (key encryption key) dialog box is displayed:
  8. Click Add. Navigate to the folder containing your OnBase Client executable. Select the executable and click Open. The OnBase Client executable is added to the Executable Files list.
    In a default installation, this file is located at C:\Program Files\Hyland\ OnBase Client for 32-bit operating systems or C:\Program Files(x86)\Hyland\ OnBase Client for 64-bit operating systems.
  9. Click Add. Navigate to the folder containing your OnBase Configuration executable. Select the executable and click Open. The OnBase Configuration executable is added to the Executable Files list.
    In a default installation, this file is located at C:\Program Files\Hyland\ OnBase Client for 32-bit operating systems or C:\Program Files(x86)\Hyland\ OnBase Client for 64-bit operating systems.
  10. If you are using a legacy OnBase Core (released prior to OnBase 8.0), you will also need to add the dmcore.dll to the Executable Files list.
    1. Click Add.
    2. Navigate to the folder containing the OnBase Core files. In a default installation, this file is located at C :\Program Files\Hyland\Core\ for 32-bit operating systems or C:\Program Files(x86)\Hyland\Core\ for 64-bit operating systems.
    3. Select the dmcore.dll file.
    4. Click Open. The dmcore.dll is added to the Executable Files list.
  11. If your OnBase version is older than OnBase 11.0 and includes the OnBase Core, you will also need to add the OBCorePlatMgmt.dll to the Executable Files list.
    1. Click Add.
    2. Navigate to the folder containing the OnBase Core files. In a default installation, this is located at C:\Program Files\Hyland\Core\ for 32-bit operating systems or C:\Program Files(x86)\Hyland\Core\ for 64-bit operating systems.
    3. Select the OBCorePlatMgmt.dll file.
    4. Click Open. OBCorePlatMgmt.dll is added to the Executable Files list.
  12. If your solution includes an OnBase Application Server, select the Generate Core dll check box and complete the Core KEK Rotation Parameters:
    Note:

    By selecting this option and performing the steps below, you are choosing to create a new version of Hyland.Core.GrabIcon.dll. If you would like to back up the original version, place it another directory, or rename it to something else before completing the process.

    1. Enter the path to the GrabIcon.NET.exe file in the Core KEK Rotation Utility Path (GrabIcon.NET.exe) field, or select a path using the Browse button.
      Note:

      This file is not included with your OnBase installation. Contact your first line of support to obtain the GrabIcon.NET.exe executable.

      Note:

      The GrabIcon.NET.exe executable requires Microsoft .NET Framework 4.8 or later to be installed.

    2. Enter the version of your OnBase Application Server in the Version field.
  13. To change the HSI, HSICORE, and HSINET database passwords, select the respective Change Password check box. Type a new password in the corresponding text field.
  14. To change the viewer account password, select the Change Viewer Password check box. The viewer account is a database account that allows only SQL SELECT statements to be executed. It is used by areas of OnBase that allow SQL statements to be run against the database. Type a new password in the VIEWER field to change the viewer account password.
    Note:

    You do not need to change these database passwords in order to rotate the KEK. If you do need to change these database passwords, you should do so here if you are licensed for the Encrypted Alpha Keywords module.

    CAUTION:

    If you change any of these database passwords, you are required to provide these passwords before you can upgrade your OnBase solution. Retain these passwords in a secure location.

  15. Determine the type of KEK you want to use:
    • To use a random KEK, click Generate KEK.

    • To use a KEK based on your own string of text, type the string in the User Entered String field (i.e., this is my new kek), then click Format.

      Note:

      The text in the User Entered String field must be exactly 16 characters. The User Entered String field can support letters, numbers, and symbols that are in a standard ANSI character set. Unicode is not supported for the User Entered String.

    • To use a previous KEK, enter the previous KEK in the Formatted KEK field.

      Note:

      The text in the Formatted KEK field must be greater than or equal to 24 characters.

  16. If you chose to generate a KEK based on your own string of text or by clicking Generate KEK, a base64 string of text is displayed in the Formatted KEK field. This string represents the encrypted version of the text used to generate the KEK.
    Note:

    You should retain the text displayed in the Formatted KEK field in a secure location. If you created a KEK based on your own string of text, retaining the string you typed in the User Entered String field is also sufficient. You can reuse the KEK when upgrading your OnBase solution.

  17. To save any notes or comments about the KEK rotation, such as information on which files were modified and what environment the executables were set for, enter them in the Comments field. The text entered in this field is saved to a r eadme text file in the directory containing the new executables and DLL file.
  18. Click Update.
  19. OnBase rotates the KEK. Click OK at the prompt when the rotation is completed.
  20. Click No if you are prompted to reset the cache of the Application Server.

The OnBase Configuration module is closed automatically when you click OK after the rotation is completed. This is done to prevent the old executables being used to rotate the KEK again, which may corrupt encrypted documents. You must use the new executable to re-open the Configuration module. See, Deploying the Rotated Key Encryption Key.