Configure custom certs from a predefined directory
You can use your own certs to secure Prisma Cloud communication channels by simply copying your custom certs to a predefined directory that the Console and Defender containers mount at runtime. No additional configuration in the Console UI is required to use your custom certs. This mechanism is enabled by default.
The communication channels you can secure with this mechanism are:
- Console web UI and API over HTTPSBy default, web and API clients connect to Console over HTTPS on port 8083. Out of the box, traffic is TLS encrypted using self-signed certs.
- Console-Defender communication over a WebSocketBy default, Defender connects to Console over a WebSocket on TCP port 8084. Out of the box, traffic between Defender and Console is TLS encrypted using self-signed certs.By design, Console and Defender don’t trust each other. When Defender initiates a connection with Console, mutual TLS is used to verify both parties.
In general, the keys and certs used for Defender-Console communication are considered an internal implementation detail. Prisma Cloud generates, manages, and rotates the keys internally. However, if your organization’s policy calls for directly managing all keys and certs, Prisma Cloud gives you the control to do so.
How it works
Configure Console and Defender to use custom certs by saving the certs into a known, predefined directory. The predefined directory is /var/lib/twistlock/custom-certificates. The directory must be mounted in the Console and Defender container file systems when the Prisma Cloud containers are started.
When establishing a connection, the directory is checked for the required certificates. If the required files exist, they are used to establish the connection.
If there’s any error in the cert files (e.g., corrupt files, key-cert mismatch, etc.), the connection fails to be established, and an error is logged.
Prisma Cloud monitors the predefined directory for file system changes. If a relevant change is detected, the connection is restarted. For example, if console-cert.pem or console-key.pem are changed, the HTTPS listener is restarted. This system is designed to make rotating certificates easy by simply copying new certs to the predefined directory.
Loading a TLS configuration
When Console and Defender start, they create TLS configurations.
Depending on the environment, a number of scenarios are possible.
Scenario: Console/Defender starts and the predefined custom certificates directory doesn’t exist and isn’t mounted in the container.
In this case, the feature is switched off. Console/Defender uses its own self-signed certificates.
Scenario: Console/Defender starts and finds the predefined custom certificates directory mounted, but not all of the required files exist.
For example, Defender requires three files to secure Console-Defender communication: defender-ca.pem, defender-client-cert.pem, defender-client-key.pem. In this scenario, assume the defender-ca.pem file is missing.
In this case, Prisma Cloud initializes the connection using its own self-signed certificates, and then watches the predefined custom directory for changes. If there are changes to the predefined directory, Prisma Cloud checks if all certificate files exist. If they do, it tries to create a TLS configuration using those certs. If it succeeds, the connection is reset and new connection is established with the custom certs. If it fails, Prisma Cloud logs an error and keeps the existing connection.
Scenario: Console/Defender starts and finds the required certificates in the mounted directory
Prisma Cloud reads the certs and creates a TLS configuration. If reading a cert fails, Console/Defender logs the following messages, and exits:
DEBU 2021-10-27T17:37:46.645 defender.go:1928 Using custom directory certificates CRIT 2021-10-27T17:37:46.645 defender.go:285 Failed to construct defender client TLS config error reading X509 key pair (/var/lib/twistlock/custom-certificates/defender-client-cert.pem, /var/lib/twistlock/custom-certificates/defender-client-key.pem): tls: failed to parse private key
If there’s an error loading your certs (for example, malformed key material), you can fix the problem by simply copying fixed certs to the predefined directory. As long as the Prisma Cloud container starts with the predefined directory mounted, it can watch the directory for changes, and try to reestablish a new connection with the latest certs when new files are detected
This, in conjunction with the verbose log messages, will help you get your configuration right.
Required certificate files
To secure a connection with your custom certs, Prisma Cloud looks for specific files in /var/lib/twistlock/custom-certificates.
For the Console HTTPS listener (for securing the web UI and API), the following files must be available in the predefined directory:
For Console’s WebSocket listener (for securing Console-Defender communication), the required files are:
For Defender’s WebSocket listener (for securing Console-Defender communication), the required files are: