Using TLS

Tip. This feature is only available on GuardMode 2024.1 or higher.

Transport Layer Security (TLS) is an essential protocol for securing network communications. GuardMode's support for TLS ensures that data transmitted via the Swagger API is encrypted, safeguarding the integrity and confidentiality of your data. This chapter provides a guide on how to implement and manage TLS within GuardMode.

Preparing the TLS Certificate

To use HTTPS with the Swagger API, you will need a certificate file with a .pfx extension. Your certificate needs to be placed in the Certificate subdirectory within the GuardMode installation directory and protected with a password.

Note. If the certificate expires or the password is incorrect, you must replace the expired certificate with a new one or correct the password. Place the new certificate in the designated directory and use the correct password in the TLS enable command as shown below.

Enabling TLS

Attention! GuardMode ensures the TLS certificate's existence, accessibility, and expiration status at each agent launch. However, it does not validate the certificate against the domain it's intended for. Using a certificate for an incorrect domain will result in failure to establish secure connections.

To enable TLS in Guardmode, run the following CLI command:

./Catalogic.GuardMode.Agent config tls enable --certificate cert.pfx --password password

This command configures GuardMode to use the specified PFX certificate. If you do not specify a port using the --port option, GuardMode will default to port 5001.

Tip. Instead of using the password directly in the command, you can use the GM_CERTIFICATE_PASSWORD environment variable.

After enabling TLS, you must restart the GuardMode agent to apply the changes.

• To restart the GuardMode agent on Linux, run:

systemctl restart Catalogic.GuardMode.Agent.service
systemctl daemon-reload

• To restart the GuardMode agent on Windows, run:

Restart-Service -Name CatalogicGuardModeAgent

Once you restart the service on Windows, open a new PowerShell session.

Disabling TLS

Deactivate TLS with this CLI command:

./Catalogic.GuardMode.Agent config tls disable

A confirmation message will indicate that TLS has been successfully disabled. After disabling TLS, you must restart the GuardMode agent to apply the changes.

Managing Environment Variables

GuardMode handles environment variables differently on Linux and Windows.

• On Linux, enabling TLS adds an environment variable to etc/systemd/system/Catalogic.GuardMode.Agent.service.d/override.conf.

• On Windows, the environment variables active at the start of a session persist throughout that session. Consequently, any new environment variables are accessible only in future PowerShell sessions, not the current one.

Certificate Expiry and Replacement

An expired TLS certificate will prevent the use of the Swagger API, even with HTTP. The system checks the certificate every time the agent launches.

To update an expired certificate, run the enable command with the new certificate details. You don't need to disable the previous one.

GuardMode TLS CLI Help

For additional help with TLS configuration commands, use the --help option:

./Catalogic.GuardMode.Agent config tls enable --help

This displays usage information, descriptions, and options for the command.