By enabling support in PCA for the X.509 public key infrastructure (PKI) standard, you can secure communications between the PCA and other Acoustic™ Experience Analytics (Tealeaf) services, and help protect the system and data from potential attackers.
Make sure that you coordinate the steps for securing communications between the PCA and other services, with the steps for securing communications between the Experience Analytics servers and other services. You can start with either the PCA or the Experience Analytics servers, but the step for enabling communications needs to be done simultaneously on both the PCA and Experience Analytics servers.
Site administrators are encouraged to take advantage of this feature to protect the local environment and data from potential attackers.
Use the information in this section to learn how enable the X.509 public key infrastructure (PKI) standard to secure communications in PCA.
The following tasks must be performed in the sequence listed.
Keep the following in mind before you enable secure communications:
- When presenting certificates from a browser, you must copy the valid *.p12 and add to the browser
- The steps for enabling secure communications can vary from browser to browser
- A valid password is required in order to import the
*.p12into a browser.
The password for importing the
*.p12is the same password that used when creating
- Consider the following with regard to PCA Web Console behavior while accessing Web Console from the browser:
- If a client presents a valid certificate, the user gains access to the PCA web UI.
- If a client presents no certificate, the user is prompted for a user name and password
- If a client presents an invalid certificate, the connection fails.
- Upgrade the PCA server(s), to version 18.104.22.168 or higher.
- Create or acquire an X.509 certificate with an associated private key and key password, stored in PKCS#12 (PFX) format.
You can create the X.509 certificate with a tool provided by Experience Analytics or by using your organization's own public key infrastructure.
- Import the certificate onto the PCA server.
- Enable the X.509 protocol on the PCA server.
Enabling the X.509 protocol requires stopping and restarting the services that run on the PCA server.
Servers with the X.509 protocol enabled cannot communicate with those servers that do not have it enabled, so make sure you enable communications as quickly as possible across the site.Note: For Secure PCA-to-canister delivery, you are not required to have to have TLS enabled on all of Experience Analytics. You can still use an older PCA or the latest PCA without X.509 changes to connect to HBR.
Creating X.509 certificates
You can create a self-signed X.509 certificate with the tlstool.exe provided by Acoustic Experience Analytics (Tealeaf) or you can create an X.509 certificate using your organization's certificate infrastructure.
The method that you choose to create the X.509 certificate depends on your organization's security requirements.
You create one certificate only for the entire site.
The following sections provide information on creating self-signed X.509 certificates and on creating certificates using your organization's certificate infrastructure .
- Run the tlstool.exe command on an Experience Analytics server as follows:
"install_directory\Tools\TLSTool.exe" create -site path password
where path is the path name where you want the certificate file to be created, and password is the password used to encrypt the private key.Note: The password must consist entirely of ASCII characters.For example:
"install_directory\Tools\TLSTool.exe" create -site "C:\test\TCXcert.pfx" password
- To use an X.509 certificate created with your organization's certificate infrastructure, the following conditions must exist:
- The certificate must have a subject name of
Tealeaf CXand be suitable for use by both TLS 1.2 clients and servers.
- The certificate must be stored in a single file in
PKCS#12format containing both the certificate and its associated private key.
- The private key must be protected by a password consisting entirely of ASCII characters.
- The certificate must have a subject name of
Importing the X.509 site certificate onto the PCA server
You can import the X.509 site certificate onto the PCA server.
Use the following procedure to import the X.509 site certificate onto the PCA server.
- Transfer the certificate file to the PCA installation path
The default PCA installation directory is /usr/local/ctccap.
- Extract the
.keyfile from the .p12 or .pfx file.
To extract the key: <install_directory>/bin/openssl pkcs12 -in TCXcert.pfx -nocerts -out TCXkey.pem.
To extract the cert: <install_directory>/bin/openssl pkcs12 -in TCXcert.pfx -clcerts -nokeys -out TCXcert.pem.
After you have imported the X.509 site certificate onto the PCA server(s), you can enable secure communication.
Enabling secure communications
Servers that use X.509 will not be able to communicate with servers that do not use X.509.
Perform the following procedure to enable secure communication between services running on the PCA server.
- In the PCA Web Console, under the Delivery tab and under Target Recipients, click Add.
- Configure the delivery peer with the Secure option checked.
- Click OK and Save Changes.
- In the
<install_directory>/etc/ctc-conf.xml, edit the following Global fields:Note: If the following fields are not present in the
ctc-conf.xml, refer to the default file ctc-conf-defaults.xml located in <install_directory>/etc/ctc-conf-defaults.xml and add the fields under "Delivery" section. This default file is always updated to the latest version on installs and upgrades. Please merge the applicable fields from the
ctc-conf-defaults.xmlfile to your local
<ServerCertPath></ServerCertPath> <ClientP12Path></ClientP12Path> <ClientP12Pass></ClientP12Pass> <ServerCertEnable>false</ServerCertEnable> <ClientCertEnable>false</ClientCertEnable>
Table 1. Settings for ctc-conf.xml Field Set value to. . .
The full path (including filename) to the extracted certificate .pem.
The full path (including filename) of TCXcert.pfx imported/copied from the Windows server.
The Password used to create the P12 or PFX file (TCXcert.pfx).Note: Enabling the secure option in the Web Console without enabling the fields in the
ctc-conf.xmlfile does not work for if Client Authentication is enabled.
Client Authentication can now be enabled or disabled from the Web Console. The fields for uploading a certificate and its password are displayed on the Web Console only when Client Authentication is enabled and the user accesses the Web Console through HTTPS.
The uploaded certificate is stored in the <install_directory>/etc directory. Uploading a new certificate with same name overwrites the old certificate.
Uploading new certificate with different name will not overwrite older certificate, but delivery only uses the new certificate path in the configuration.
- Restart PCA services by performing a "restart all" or "stop all" followed by "start all".
- Configure the target HBR or transport service for secure communications as well.
Enabling client authentication on the PCA Web Console (Optional)
To enable the secure communication on a PCA server Web Console, perform the steps listed here.
Although this procedure is optional, it is strongly recommended, as all other components will be using Client Authentication.
- Using any editor, update the
runtime.confto enable the web_console_security_crt_enable as follows:/usr/local/ctccap/etc/runtime.conf
Then enable it, as follows:
- Create a username and password for PCA Web Console authentication.
A client browser that doesn't present the certificate needs to authenticate if
- Run the following script and follow the steps to copy your certificates and to generate the
- In an upgrade scenario, compare your current
httpd.conf.defaultand copy the new additions to your
- For a fresh install "start" and for an upgrade "restart httpd".
Disabling secure communications on the PCA server
You can disable secure communication on the PCA server.
To disable secure communication on the PCA server, perform the following steps.
- Set the following fields in the
ctc-conf.xmlfrom true to false.
- Remove the "secure" option from the delivery peer in the PCA Web Console.
- Restart PCA services by doing "restart all" or "stop all" followed by "start all".
Disabling secure communication on a PCA server Web Console
You can disable secure communication on the PCA server Web Console.
To disable secure communication on a PCA server Web Console, perform the following steps.
- Using an editor of your choosing, update the
runtime.confto disable the
and comment it out as follows:
- Run the "restart httpd" command.