Creating and managing custom GIM certificates

Edit online

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, they must possess both serverAuth and clientAuth properties. These properties ensure 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 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 changed. See What to do next.

You can view the progress of the GIM certificate distribution in the GIM Certificate Deployment Status report, and view GIM events in the GIM Events List report.

The pre-V11.0 method of deploying certificates is fully compatible 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, complete the tasks in this procedure again with the new certificates.

Procedure

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.
Open the Guardium GUI, and in your Dashboard, add the GIM Certificate Deployment Status report so you can view progress.
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 a 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 a 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.
  You can use one of the following types: console to paste the certificate to the console or external to 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.
  Draft comment: JILLGOLDBERG
  get more details from omar
Check the GIM client status by using one of the following methods:
- 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 Certificate Deployment Status report.
  Tip: If the root CA changed, the GIM client state changes from Pending to Processing and then to Deployed. This state indicates that new certificates were downloaded but not actively used, and the GIM client still uses its original certificates.
  If the root CA was not changed, the GIM client state changes from Pending to Processing to Deployed and then to Active. This state indicates that new certificates were downloaded and are in use.
If you're using a new CA for the new certificates, the GIM clients must be in Deployed state and you must continue with 5.
If you're not using a new CA for the new certificates, the GIM clients must be in Active state and you must got to step 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.
Draft comment: JILLGOLDBERG
really?? Nothing else to do before contacting Support? How long can alive cycle take?
Verify that all the client certificates are in the Deployed state in the GIM Certificate Deployment Status report.
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.
Verify that all clients have the Active state (meaning the clients are connected to the server by using new certificates) in the GIM Certificate Deployment Status report. It can take up to one complete alive cycle before all clients are in their updated states.
Draft comment: JILLGOLDBERG
how much time? Oren
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.
Verify that all the clients are in the Active state in the GIM Certificate Deployment Status report, 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 make such that 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.