IBM Support

Updating Guardium Data Protection GIM clients with SHA256 certificates

How To


Summary

Guardium appliance versions 11.0p475, 11.0p530 and 12.0 updates the default self signed GIM certificate to SHA256.
Before you update your Guardium Data Protection system to these versions, understand how GIM is affected and what actions are required.

Objective

  • Understand how GIM certificates are changing
  • Understand actions you might need to take in different GIM upgrade and installation scenarios

Environment

What is changing?
  • Guardium default self signed GIM certificate is updating from SHA1 to SHA256. The exact Guardium patches and versions with this change are in section "Exact versions with SHA256 certificate"
  • This certificate is used for two parts of GIM functionality:
    • Verification of GIM bundles. To ensure that GIM bundles are generated by Guardium
    • Communications between GIM agents on database server and GIM server on Guardium appliance
  • After installing patches with the change, GIM agents will be green in GUI, but updating parameters or upgrading bundles (including S-TAPs, FAM, CAS, or Universal Connectors) using GIM will not work. Actions are required to return GIM functionality to normal
Is data activity monitoring affected?
  • Data activity monitoring from S-TAPs will not be affected
Exact versions with SHA256 certificate
  • The following versions of Guardium Data Protection use SHA256 GIM client certificates:
  • Versions of the Guardium appliance:
    • Guardium 11.4 patch 475 (11.0p475) and later
    • Guardium 11.5 patch 530 (11.0p530) and later
    • Guardium 12.0 and later
    • This change does not apply to Guardium 11.3 and earlier versions
  • Versions of GIM agents and its modules (including S-TAPs, FAM, CAS, or Universal Connectors)
    • Unix OS:
      • v11.4_r114889 and later
      • v11.5_r115368 and later
    • Windows OS:
      • v11.4.0.363 and later
      • v11.5.0.258 and later
Updating GIM agents with SHA256 certificates
Transitional bundles
After you upgrade an existing Guardium appliance to a version where GIM uses SHA256 certificates, GIM can only verify bundles signed with SHA256.
This means that the GIM client cannot install new SHA256-signed bundles (including S-TAPs, FAM, CAS, or Universal Connectors) on database servers with existing GIM clients until you install a transitional GIM bundle. 
Transitional GIM bundles:
  • Have the same functionality as a standard GIM bundle
  • Allow install of future bundles signed with SHA256 certificate
  • Installer files are included in GIM bundle downloads from fix central
Example bundles
Example of transitional GIM bundles. Transitional bundles include the word transitional in the bundle name.
Linux:
  • guard-bundle-GIM-11.5.4.1_r115368_v11_5_1-rhel-9-linux-x86_64_transitional.gim
Windows:
  • guard-GIM_transitional-11.5_r110500308_1-x86_x64.gim

Example of standard GIM bundles.
Linux:
  • guard-bundle-GIM-11.5.4.1_r115368_v11_5_1-rhel-9-linux-x86_64.gim
Windows:
  • guard-GIM-11.5_r110500308_1-x86_x64.gim
Basic procedure for upgrading an environment to use SHA256 GIM certificates
  1. Upgrade your existing Guardium appliance to 11.0p475, 11.0p530, or 12.0 or later versions
  2. For Guardium 12.0, enable openssl-sha1-signature before you upload a transitional bundle.  Use the show openssl_sha1_signature CLI command to verify that it is enabled; if it is disabled, use store openssl_sha1_signature on to enable it.
  3. Upload the GIM transitional bundle and install it. You need to install the transitional GIM bundles only once on that database server. After you install the transitional GIM bundle, you can use the standard GIM bundle for all future GIM upgrades.
  4. Upload and install the S-TAP bundle. Note: You must upload and install the transitional bundle before you upload the S-TAP bundle.
See the Steps section for detailed information about different scenarios.
Are custom GIM certificates affected?
  • Actions are still required with custom GIM certificates, see steps section for detailed steps for custom certificate environments
  • When you upgrade an existing Guardium system to 12.0, prior to installing 12.0p10, custom SHA256 GIM certificates maintained by your organization are required before you can deploy new GIM bundles.
    •  To continue using default self signed certificates, upgrade your Guardium appliance to 12.0p10. 
  • In all other cases, custom SHA256 GIM certificates maintained by your organization are not required but are recommended. For more information, see Creating and managing custom GIM certificates.

Steps

Before updating your Guardium Data Protection systems with a patch that supports SHA256 GIM client certificates, identify and follow the scenario that best matches your environment.
1. Upgrading existing GIM clients
1.1. Upgrade using default GIM certificates
If your Guardium system already has GIM clients connected, uses default certificates, and you need to upgrade GIM clients.
  1. Upgrade your existing Guardium appliance to 11.0p475, 11.0p530, or 12.0p10 with connected GIM clients
  2. For Guardium 12.0, enable openssl-sha1-signature before you upload a transitional bundle.  Use the show openssl_sha1_signature CLI command to verify that it is enabled; if it is disabled, use store openssl_sha1_signature on to enable it
  3. Upload the GIM transitional bundle and install it using the versions specified above
  4. Upload and install the S-TAP (or FAM, CAS, or Universal Connectors) bundle
1.2. Upgrade using custom GIM certificates
If your Guardium system already has GIM clients connected, uses custom certificates, and you need to upgrade GIM clients.
  1. Upgrade your existing Guardium appliance to 11.0p475, 11.0p530, or 12.0p10 with connected GIM clients
  2. For Guardium 12.0, enable openssl-sha1-signature before you upload a transitional bundle.  Use the show openssl_sha1_signature CLI command to verify that it is enabled; if it is disabled, use store openssl_sha1_signature on to enable it
  3. Upload GIM transitional bundle using the versions specified above and install it
  4. Upload and install the S-TAP (or FAM, CAS, or Universal Connectors) bundle
2. Installing new GIM clients
2.1 Install new in an existing Guardium deployment using default GIM certificates
If your Guardium system already has GIM clients connected, uses default certificates, and you need to install new GIM clients.
  1. Upgrade your existing Guardium appliance with connected GIM clients to 11.0p475, 11.0p530, or 12.0p10.
  2. Install GIM bundle using the below versions or later. These versions contain both SHA1 and SHA2 GIM certificates:
    • For Unix OS: v11.4_r117207, v11.5_r117180 , v12.0_r117209
    • For Windows OS: v11.4.0.413, v11.5.0.338, v12.0.0.183
  3. Upload and install the S-TAP (or FAM, CAS, or Universal Connectors) bundle
2.2 Install new in an existing Guardium deployment using custom GIM certificates
If your Guardium system already has GIM clients connected, uses custom certificates, and you need to install new GIM clients.
  1. Upgrade your existing Guardium appliance with connected GIM clients to 11.0p475, 11.0p530, or 12.0p10. 
  2. Install GIM bundle using the versions specified above (Do not need GIM transitional bundle)
    • For Linux and UNIX installers (update the installer file name with the installer from the GIM bundle):
      • guard-bundle-GIM-11.5.1.0_r12345_trunk_1-rhel-9-linux-ppc64le.sh -- --cert_file "<GIM_CERT_FILE>" –-ca_file "<GIM_CA_FILE>" –key_file "<GIM_KEY_FILE>" --dir "<install directory>" --tapip "<IP or host name>" --sqlguardip "<IP or hostname>"
    • For Windows installers:
      • setup.exe -unattended -CERT_FILE "<GIM_CERT_FILE>" –CA_FILE "<GIM_CA_FILE>" -KEY_FILE "
  3. Upload and install the S-TAP (or FAM, CAS, or Universal Connectors) bundle.
2.3. Install new in a Guardium deployment without any connected GIM clients
If your Guardium system does not have any GIM clients connected (for example a newly built appliance), uses default or custom certificates, and you need to install new GIM clients.
  1. Install new or upgrade your existing Guardium appliance that does NOT have any previously connected GIM clients, to 11.0p475, 11.0p530, or 12.0p10
  2. Install GIM bundle using the versions specified above (Do not need GIM transitional bundle)
  3. Upload and install the S-TAP (or FAM, CAS, or Universal Connectors) bundle.
3. Troubleshooting
When upgrading GIM clients, if you accidentally upload and deploy a standard (non-transitional) bundle when a transitional bundle is required, the deployment fails (the UI allows the upgrade, but the installation itself fails).  To recover from this failure:
  1. Cancel the installation from the GIM UI.
    • Look for modules in the "FAILED" state and cancel their installation to return to the "INSTALLED" state.
    • Alternatively, use "reset client."
  2. Delete the bundle using Guardium APIs:
    • Use the following API command to identify the bundle to delete:

      grdapi gim_list_unused_bundles includeLatest=true

    • Use the following API command to delete the bundle:

      grdapi gim_remove_bundle bundlePackageName=<bundle name identified in previous step>

  3. Upload and deploy the correct transitional bundle.
When installing new GIM clients, if you accidentally attempt to install a transitional bundle when a standard (non-transitional) bundle is required, uninstall the transitional bundle and install the correct standard bundle directly on the database server.

Additional Information

For more information about managing GIM clients, see:

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB24","label":"Security Software"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSMPHH","label":"IBM Security Guardium"},"ARM Category":[{"code":"a8m0z000000Gp0JAAS","label":"APPLIANCE"},{"code":"a8m0z000000Gp0TAAS","label":"GIM"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"11.4.0;11.5.0;12.0.0"}]

Document Information

Modified date:
21 June 2024

UID

ibm17013031

Page Feedback