Configuring Cloudpaging SSL Certificates

Once the certificate and key have been provided, they may need to be converted to .pfx format before they can then be applied to Cloudpaging.

Please refer to Converting SSL Certificates for the conversion steps.

Known Issues

• [#37308] Unable to Apply New Cloudpaging PFX Certificates | #33650 : (freshdesk.com)

• [#37163] Unable to apply .pfx certificate on Cloudpaging Admin server 9.5.4 [AA: #33499] : (freshdesk.com)

This issue is ultimately due to the MAC and encryption algorithms used in the PFX keystore as outlined in the callout warning in our Configuring Tomcat with an SSL/TLS Certificate in PFX/PKCS#12 format article. To confirm this, you can use the following OpenSSL command:

CODE

openssl pkcs12 -info -in "<.PFX file path>" -nomacver -noout -passin pass:<keystore_password>

​The results should show that both the PKCS7 Encrypted data and Shrouded Keybag use pbeWithSHA1And3-KeyTripleDES-CBC in addition to the MAC using sha1 as shown in the "Supported" screenshot below. The iteration should also be 2048 or less, otherwise this may prevent the keystore from being used. 

If the results do not show as above, the customer will need to do one of the following to resolve the issue:

• Try creating and importing the PFX keystore file with the SHA1 MAC and encryption algorithms. OpenSSL can be used to create the PFX keystore file with the proper algorithms as in the command below:

  • openssl pkcs12 -inkey "<path_to_private_key>" -in "<path_to_certificate_chain>" -passout "pass:<password>" -export -out "<path_to_create_keystore>.pfx" -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -macalg sha1

• Upgrade Java 8 to a newer patch version that supports the SHA256 MAC and encryption algorithm, I have had some success using the newer HMACsha256 algorithms with Java 8u372.

Prerequisites

Customers must request and provide valid SSL Certificates.

Applying the SSL certificate

Windows

1. Connect to one Cloudpaging Admin Server

2. Rename the <certificate>.pfx file to cloudpaging.pfx

3. Copy Cloudpaging.pfx to the first Cloudpaging server and place it in C:\Program Files (x86)\Numecent\Application Jukebox Server

4. Backup C:\Program Files (x86)\Numecent\Application Jukebox Server\core\conf\server.xml (copy and rename the file)

5. Open Notepad with Administrative privileges and open the original server.xml

6. Edit the keystoreFile="..." tag (see below), replacing the custom.keystore filename with cloudpaging.pfx

7. Immediately after that entry add keystorePass="ThePassword" keystoreType="PKCS12" (with the correct password)

8. Save server.xml

9. Restart the Cloudpaging service

10. Ensure the certificate is applied and Cloudpaging is functional via https://<server_fqdn>/jukeboxserver

11. Copy C:\Program Files (x86)\Numecent\Application Jukebox Server\core\conf\server.xml to the next Cloudpaging server

12. Restart the Cloudpaging service

13. Ensure the certificate is applied and Cloudpaging is functional via https://<server_fqdn>/jukeboxserver

14. Repeat steps 10-12 for the remaining Cloudpaging servers

Example Windows server.xml

<Connector acceptCount="100" clientAuth="false" disableUploadTimeout="true" enableLookups="false" keystoreFile="C:\Program Files (x86)\Numecent\Application Jukebox Server\cloudpaging.pfx" keystorePass="password" keystoreType="PKCS12" maxHttpHeaderSize="32768" maxThreads="300" minSpareThreads="25" URIEncoding="UTF-8" port="443" SSLProtocol="TLSv1.2" SSLEnabled="true" scheme="https" secure="true"/>

Linux

1. SSH into the server through WinSCP with credentials from 1password

2. Rename the new <certificate>.pfx file to cloudpaging.pfx

3. Copy Cloudpaging.pfx to the first Cloudpaging server and place it in /usr/local/ApplicationJukebox/core/

4. Backup /usr/local/ApplicationJukebox/core/conf/server.xml

5. Open Notepad with Administrative privileges and open the original server.xml

6. Edit the keystoreFile="..." tag (see below), replacing the custom.keystore filename with cloudpaging.pfx

7. Immediately after that entry add keystorePass="ThePassword" keystoreType="PKCS12" (with the correct password)

8. Save server.xml

9. Restart the Cloudpaging service

10. Ensure the certificate is applied and Cloudpaging is functional via https://<server_fqdn>/jukeboxserver

11. Copy /usr/local/ApplicationJukebox/core/conf/server.xml to the next Cloudpaging server

12. Restart the Cloudpaging service

13. Ensure the certificate is applied and Cloudpaging is functional via https://<server_fqdn>/jukeboxserver

14. Repeat steps 10-12 for the remaining Cloudpaging servers

Example Linux Server.xml

<Connector acceptCount="100" clientAuth="false" disableUploadTimeout="true" enableLookups="false" keystoreFile="/usr/local/ApplicationJukebox/core/cloudpaging.pfx" keystorePass="password" keystoreType="PKCS12" maxHttpHeaderSize="32768" maxThreads="300" minSpareThreads="25" URIEncoding="UTF-8" port="443" SSLProtocol="TLSv1.2" SSLEnabled="true" scheme="https" secure="true"/>

Rollback procedure

Windows

1. Revert C:\Program Files (x86)\Numecent\Application Jukebox Server\core\conf\server.xml

2. Restart Cloudpaging server

Linux

1. Revert /usr/local/ApplicationJukebox/core/conf/server.xml

2. Restart Cloudpaging server

Updating the certificate

If Cloudpaging is not using a Cloudpaging.pfx file, then it should be updated to use one.

Providing the customer uses health check load balancing there will be no outage.

Otherwise, the service will be offline whilst the master (live) server is updated (approx. 5 minutes).

To prevent an outage in the absence of health check load balancing, the secondary server should be updated first and verified. Once complete it should be switched in the load balancer to become the master (live) server. If manual switch over is required, it should be scheduled so the load balancer can be updated.

If there is only one server, the service will be:

• At risk from the start of the change for approx. 15 minutes

• Offline for approx. 5 minutes whilst the service restarts

Update Procedure

1. Copy cloudpaging.pfx to cloudpaging.bak

2. Overwrite cloudpaging.pfx

3. Restart the service

4. Check the Portal loads (https://localhost/jukeboxserver)

5. Repeat steps 2-4 on the other servers

Rollback Procedure

1. Copy cloudpaging.bak to cloudpaging.pfx

2. Restart the service

3. Check the Portal loads (https://localhost/jukeboxserver)