How to update your sovos.com SSL certificate (Java)

This article was updated on October 22, 2024 with new instruction on when to delete the old SSL certificate.

The Sovos Cloud Java Web Services Client allows you to access the SOAP Server for Global Tax Determination (GTD) Cloud. This article explains how to update the certificates for the URLs used to access GTD environments:

  • Production: gtd.sovos.com
  • UAT: gtduat.sovos.com

Before you begin

  • Version 8 or newer of Java is required.
  • Make sure that the Java Web Services Client exists and that the smoke test is working properly.
  • Make sure that JAVA_HOME and PATH environment variables are set with appropriate values in the command prompt in which the keytool command is executed. Use the following syntax to set the variables:
    • Windows
      • set JAVA_HOME='Java Home Path' (e.g. set JAVA_HOME=D:\jdk1.7.0_79)
      • set PATH=%JAVA_HOME%\bin;%PATH%
    • Non-Windows
      • export JAVA_HOME=’Java Home Path’ (e.g. export JAVA_HOME=/home/TaxwareEnterprise/jdk1.7.0_79)
      • export PATH=$JAVA_HOME/bin:$PATH
  • Download the new SSL certificate (serverssl2025sovos.crt) from the Sovos Portal.
  • Make sure you have the keystore password for the current Web Services Client.

Extract the intermediate certificate

  1. Open the certificate. If you are using Windows, you can double-click on the certificate to open it.
  2. Click Certification Path.
  3. Click Go Daddy Secure Certificate Authority - G2, then click View Certificate. This is the intermediate certificate.
  4. Click Details.
  5. Click Copy to File to open the Certificate Export Wizard.
  6. On the Certificate Export Wizard, click Next.
  7. Select Base-64 encoded X.509 (.CER), then click Next.
  8. Click Browse and go to the Certs folder in the adapter directory. Enter SovosIntermediateCert in the File name field and click Save.
  9. Make sure that the file path in the Certificate Export Wizard is correct, then click Next.
  10. Click Finish.

Add the new Server SSL certificate

  1. Back up the existing Web Services Client directories, including sub-folders. This will allow you to roll back in case something happens while updating the certificate.
  2. Place the new Server SSL certificate (serverssl2025sovos.crt) into <Web Services Client>\certs.
  3. Run the keytool command from <Web Services Client> to add the Server SSL certificate for the new environment to serverssl keystore. This command should be executed in a single line:
    • Windows: keytool -import -trustcacerts -alias SOVOS2024 -file certs\serverssl2025sovos.crt -keystore keystores\serverssl.jks
    • Non-Windows: keytool -import -trustcacerts -alias SOVOS2024 -file certs/serverssl2025sovos.crt -keystore keystores/serverssl.jks
  4. When prompted, enter the following information.
    • Enter keystore password: Enter the certificate store password that was entered while creating the certificate signing request using the Certificate Management Utility.
    • Trust this certificate? [no]: Enter yes.

Add the intermediate certificate

  1. Place the new intermediate certificate into <Web Services Client>\certs.
  2. Run the keytool command from <Web Services Client> to add the Server SSL certificate for the new environment to serverssl keystore. This command should be executed in a single line:
    • Windows: keytool -import -trustcacerts -alias SOVOSINT -file certs\SovosIntermediateCert.cer -keystore keystores\serverssl.jks
    • Non-Windows: keytool -import -trustcacerts -alias SOVOSINT -file certs/SovosIntermediateCert.cer -keystore keystores/serverssl.jks
  3. When prompted, enter the following information.
    • Enter keystore password: Enter the certificate store password that was entered while creating the certificate signing request using the Certificate Management Utility.
    • Trust this certificate? [no]: Enter yes.
  4. Run the keytool command from the Web Services Client root directory to check that the new serverssl certificate exists in keystore:
    • Windows: keytool -list -v -keystore keystores\serverssl.jks
    • Non-Windows: keytool -list -v -keystore keystores/serverssl.jks
  5. When prompted, enter the keystore password.
    • If you used the Certificate Management Utility to create a signing request, enter the certificate store password that was entered while creating the certificate signing request.
    • Otherwise, enter the password used for keystore creation.
    The command output should list four certificates:
    • One for the current environment
    • One for the new Sovos environment with the new alias name
    • One for the intermediate certificate
    • A mykey entry
  6. Run the smoke test to make sure you're able to connect to Sovos' servers.

Delete the old SSL certificate and rename the new certificate

Do not delete the old SSL certificate until we update the endpoints on our end on Tuesday, October 29. If you delete the old certificate before the endpoints have been updated, you will be unable to connect to the endpoints.

  1. Run the keytool command from <Web Services Client> to retrieve existing alias names in the current environment:
    • Windows: keytool -list -v -keystore keystores\serverssl.jks
    • Non-Windows: keytool -list -v -keystore keystores/serverssl.jks
  2. Run the keytool command from <Web Services Client> to remove the server SSL certificate from serverssl keystore, replacing <Old Alias> with the alias name you retrieved in the previous step. This command should be executed in a single line:
    • Windows: keytool -delete -v -alias <Old Alias> -keystore keystores\serverssl.jks
    • Non-Windows: keytool -delete -v -alias <Old Alias> -keystore keystores/serverssl.jks
  3. In <Web Services Client>\certs, note the name of the original certificate file (e.g. serverssl.crt).
  4. Delete the original certificate file, then rename the new certificate file to match the old certificate file name. For example, if the original certificate file was named serverssl.crt, delete serverssl.crt and then rename the new certificate file serverssl.crt. <Web Services Client> should now only contain one certificate.
  5. Run the smoke test to make sure you're able to connect to Sovos' servers.

Run the smoke test

Run runsmoketest.sh or runsmoketest.bat in the Web Services Client directory to check if you are connected to the SOAP server. Check the smoke test log file (Soapclient_error.log) to see if there are errors.

The following image is an example of a successful smoke test:

The 2025 certificate is provided by Go Daddy rather than Entrust; this change may cause some issues depending on your firewall setup. If you are unable to connect to Sovos' servers after updating the certificate, make sure that your firewall is not blocking the connection.

Restart adapter services

After you've removed the old alias entry and run a successful smoke test, you must restart your adapter services.

Additional steps for multiple adapters

If you have multiple adapters that use the same keystore files (clones), you can follow these steps to speed up the upgrade process and minimize downtime requirements.

  1. Back up the existing Web Services Client directories, including sub-folders. This will allow you to roll back in case something happens while updating the certificate.
  2. Copy the Certs and Keystores directories from an updated adapter.
  3. Paste the Certs and Keystores directories into the non-updated adapter and overwrite the existing files.
  4. Run a smoke test.
  5. Restart the service. If you have multiple services, to keep your services available during the update process, you can update each adapter service one at a time and restart the service.
  6. Repeat steps 1-5 until complete.