Creating and managing custom GIM certificates

You can replace the default Guardium®, privately signed, certificates with trusted CA certificates, without interrupting the GIM server to GIM client communication.

Before you begin

  • All GIM clients must be running v11.0 or higher.
    CAUTION:
    Failure to upgrade the clients before you start this procedure complicates the certificate distribution process and can require substantial efforts to recover the GIM clients running earlier versions.
  • Make sure that a GIM client is registered to the Guardium appliance.
  • In adherence to the mutual Transport Layer Security (mTLS) mandate for Guardium Installation Manager (GIM) client-server communication, custom certificates must comply with the following best practices:
    • To ensure streamlined verification processes, certificates must not contain Subject Alternative Name (SAN) entries.
    • If Extended Key Usage (EKU) is used within the certificates, it is essential that they possess both serverAuth and clientAuth properties. This ensures comprehensive authentication capabilities for both server and client endpoints.

About this task

The GIM server-GIM client communication is secured by an encrypted channel and authentication. When you install GIM, it uses default Guardium certificates that are privately signed. Best practice is to install your own certificates from a trusted CA. In both cases, certificates are stored on the GIM server, and distributed to the GIM clients.

When you enable this feature, each GIM client downloads its new certificate, but continues to communicate with the GIM server by using its current certificate. After the new certificates are downloaded to all of the GIM clients, you then install a new certificate on the GIM server, and each GIM client starts by using the new certificate. The clients and their server do not lose any communication.

You can activate GIM listeners after the GIM certificates on the appliance has been changed. See What to do next.

You can observe progress in the GIM Distributed Certificates report, and view GIM events in the GIM Events List report.

The pre-V11.0 method of deploying certificates is fully compatibility with this new method. If you want to deploy certificates by using your own applications, you can configure GIM to use these certificates by using the common GIM update parameters mechanism.

For authentication to succeed, all certificates must be signed by the same CA certificates (root, and intermediate if applicable), whether they are trusted or private.

Certificates expire at some point. Use the command show certificate warn_expired to view all expired certificates or certificates that expire within the next six months. When your certificates expire, perform this procedure again with the new certificates.

Procedure

  1. Enable the GIM certificate distribution feature. On the central manager, in the GIM Global Parameter page, enter the GIM command: gim_auto_certificate_distribution=1.
  2. Open the Guardium GUI, and in your Dashboard, add the GIM Distributed Certificates Report so you can view progress.
  3. Create GIM client certificates. If the Root CA did not change, you do not need to create a server certificate at all. If you are changing the Root CA, you need to create a server certificate, in steps 5, 6, and 8.
    1. Log in to Guardium CLI as CLI user.
    2. Run create csr gim client to create a new CSR with the alias gim. Complete the details:
      • Common Name
      • Organizational Unit
      • Organization
      • City or Locality
      • State or Province
      • Two-letter country code
      • Encryption algorithm (Default: RSA)
      • Keysize (Default: 2048)
      • Subject Alternative Name (Optional)
    3. Get the CSR signed by either a private CA or trusted CA. The Certificate needs to be in PEM format so that it can be imported into the Guardium appliance. Intermediate and root certificates must be appended.
    4. Run store certificate gim client <type> to store the GIM client certificate into its own keystore, where <type> represents the mode of import:
      • console: Paste the Certificate to the console
      • external: Import the Certificate from an external location
    5. If you entered console in 3.d, paste the end-entity and trusted CA certificates to the console, forming a trusted chain, then press Ctrl+D
    6. If you entered external in 3.d, you are prompted to provide the location of where the certificate is stored, and possibly a password.
  4. Check the GIM client status by one of:
    • Run the CLI command: show certificate gim client console. Verify that all intermediate (if applicable) and root certificates are concatenated.
    • Look at the GIM client states in the GIM Distributed Certificates report. They should change from Pending to Processing to one of:
      • If the root CA changed: Deployed. New certificates were downloaded but not actively used. The GIM client still uses its original certificates.
      • If the root CA was not changed: Deployed, then Active. New certificates were downloaded and are in use.
    If you're using a new CA for the new certificates, the GIM clients should be in the state Deployed. If you're using a new CA, continue with 5.
    If you're not using a new CA for the new certificates, the GIM clients should be in the state Active. If you're not using a new CA, continue with 9.
    If a GIM client remains in the state Processing (or N_A) after the alive cycle passes, the GIM client is either inactive or it cannot process its certificate. Contact Customer support.
  5. If you're using a new CA for the new certificates, verify in the GIM Distributed Certificates report that all the client certificates are in the Deployed state.
  6. If you're using a new CA for the new certificates, on the primary central manager, create and load the new GIM server certificate.
    1. Run create csr gim server to create a new csr with the alias gim for the gim server certificate.
    2. Get the GIM server CSR signed by the same CA certificate as used in step 3.c.
    3. Run store certificate keystore trusted console to import the trusted CA certificates into the keystore.
    4. Run store certificate gim server console to store the gim server certificate into the keystore. (You can also use the command store certificate gim server external. See step 3.f
    Do not change the GIM server certification on the backup central manager.
  7. Verify that the GIM Distributed Certificates report that all clients have the state ‘ACTIVE’ (meaning the clients are connected to the server by using new certificates). It can take up to one complete alive cycle before all clients are in their updated states.
  8. If you're using a new CA for the new certificates, update the backup central manager with the new GIM server certificate.
    1. Log in to the backup central manager.
    2. Run store certificate keystore trusted console to trust and store the CA certificate that was used to sign the gim server certificate.
    3. Run store certificate gim server console to store the gim server certificate into the keystore. The root and intermediary certificates (if applicable) also need to be concatenated.
  9. Verify in the GIM Distributed Certificates report that all the clients are in the Active state, whether you're using a new CA for the new certificates, or the original CA.

What to do next

You can add GIM clients after you replace the default GIM server certificate. The new GIM clients automatically retrieve the custom certificates in listener mode. Install the GIM client without specifying a collector's IP address (sqlguardip) to ensure it is in listener mode. Then activate the GIM clients. For more information, see GIM remote activation. The certificates are streamed during activation. You can also check that the activated GIM client is listed in the GIM Clients report.