Upgrade Guidance for CU7 when SHA1 certificates are detected
Article ID: 438162
Updated On:
Products
Issue/Introduction
In some DX UIM environments which have been upgraded from versions prior to hub 23.4.0, and in which tunnels are present, the tunnel certificates use the older SHA1 encryption standard.
Hotfix hub 23.4.7.1 was released which allows the older SHA1 certificates to be used.
This article provides guidance on how to successfully apply this hotfix and upgrade to DX UIM 23.4.7 (CU7) when the older SHA1 certificates are in place.
Environment
DX UIM - Any Version being upgraded to 23.4.7 (CU7)
hub/robot 23.4.6 or prior
Secure Bus not present (hub_secure and robot_secure) -- only standard hubs and robots
Cause
OpenSSL version change in hub 23.4.7 disallows the use of SHA1 certificates
Resolution
The hub 23.4.7.1 hotfix contains a new key/value pair: enable_cert_compatibility = yes
This allows the use of SHA1 certificates and should be placed in the <tunnel> section of hub.cfg:
The exact deployment process depends on the specifics of your environment. Review the scenarios below to determine which one matches your deployment.
Scenario 1: Your Primary Hub is also a Tunnel Server, which has one or more clients connected to it.
In this scenario, you should deploy the CU7 upgrade along with the 23.4.7.1 hotfix in the following order:
- On all hubs with tunnels (servers and clients), add the key/value enable_cert_compatibility = yes in the <tunnel> section of hub.cfg on all hubs with tunnels, but do not upgrade anything yet. This means - any tunnel client and any tunnel server, not just the primary; make this configuration change to all hubs with tunnels ahead of time.
- Deploy the hub 23.4.7.1 hotfix to the tunnel clients only. If desired, you can skip secondary hubs and clients for now, and do them later - but any clients which connect to the primary hub itself must be upgraded to 23.4.7.1 at this point. They will reconnect successfully to the primary hub/tunnel server. If you do want to upgrade all the hubs at once, always do the tunnel clients first before the servers. If you have multiple "tiers" of hubs, where some are acting as both client and server, upgrade the farthest-away or "edge" clients first. Upgrade tunnel servers only after all of the clients have been upgraded, otherwise you risk losing connectivity to the clients.
- Deploy the CU7 upgrade to the primary hub by running the installer. This will upgrade the primary hub to 23.4.7 and the tunnel clients will drop off, as the tunnel server portion of the hub will not start until upgraded to 23.4.7.1.
- After the CU7 upgrade completes, redeploy hub 23.4.7.1 to the primary hub and the "enable_cert_compatibility" key which you already added will take effect, and the tunnel clients will be able to reconnect successfully.
Scenario 2: Your Primary Hub is a Tunnel Client connecting to one or more tunnel servers
In this scenario, use the following order:
- On all hubs with tunnels (servers and clients), add the key/value enable_cert_compatibility = yes in the <tunnel> section of hub.cfg on all hubs with tunnels, but do not upgrade anything yet. This means - any tunnel client and any tunnel server, not just the primary; make this configuration change to all hubs with tunnels ahead of time.
- Deploy the hub 23.4.7.1 hotfix to the "other" tunnel clients first; not the primary hub, but any other clients which connect to the same tunnel servers that the primary connects to. They will reconnect successfully to their respective tunnel servers. If desired, you can skip secondary hubs and clients for now, and do them later - but any servers which the primary hub itself is a client to must be upgraded to 23.4.7.1 and before you do that, you must also upgrade all the other clients which connect to those same tunnel servers.
- After deploying the 23.4.7.1 hotfix to the "other" tunnel clients, deploy it to the tunnel servers. At this point your primary hub/client should still be running a pre-23.4.7 hub, so it should reconnect successfully to those tunnel servers after they are upgraded.
- Deploy the CU7 upgrade to the primary hub by running the installer. This will upgrade the primary hub to 23.4.7 and it will then fail to reconnect to the tunnel server(s) that it is a client to.
- Now deploy hub 23.4.7.1 to the primary hub and the "enable_cert_compatibility" key which you already added will take effect, and it will connect to the tunnel server(s) successfully.
Scenario 3: Your Primary Hub is Both a Tunnel Server and a Client to Other Tunnel Servers
In this scenario, use the following order:
- On all hubs with tunnels (servers and clients), add the key/value enable_cert_compatibility = yes in the <tunnel> section of hub.cfg on all hubs with tunnels, but do not upgrade anything yet. This means - any tunnel client and any tunnel server, not just the primary; make this configuration change to all hubs with tunnels ahead of time.
- Deploy the hub 23.4.7.1 hotfix to "other" tunnel clients first; not the primary hub, but any other clients which connect to the same tunnel servers that the primary connects to. They will reconnect successfully to their respective tunnel servers.
- Also deploy the 23.4.7.1 hotfix to any hub that is a client of the primary hub.
- If desired, you can skip secondary hubs and clients for now, and do them later - but any servers which the primary hub itself is a client to must be upgraded to 23.4.7.1 and before you do that, you must also upgrade all the other clients which connect to those same tunnel servers. Any server that is a client directly to the primary hub should also be upgraded at this time.
- After deploying the 23.4.7.1 hotfix to the "other" tunnel clients, deploy it to the tunnel servers. At this point your primary hub/client should still be running a pre-23.4.7 hub, so it should reconnect successfully to those tunnel servers after they are upgraded.
- Now deploy the 23.4.7.1 hotfix to the tunnel clients that are connecting directly to the primary hub; again, they should successfully reconnect to the primary hub after the deployment.
- Deploy the CU7 upgrade to the primary hub by running the installer. This will upgrade the primary hub to 23.4.7 and it will then fail to reconnect to the tunnel server(s) that it is a client to, and all direct clients will fail to reconnect to it.
- Finally, deploy hub 23.4.7.1 to the primary hub and the "enable_cert_compatibility" key which you already added will take effect, and it will connect to the tunnel server(s) successfully.
Scenario 4: Your Primary Hub Is Not A Tunnel Server or Client, but you have secondary hubs which are, and Name Services entries connecting some of them to the Primary Hub
This is the easiest scenario to deal with, here are the steps: - On all hubs with tunnels (servers and clients), add the key/value enable_cert_compatibility = yes in the <tunnel> section of hub.cfg on all hubs with tunnels, but do not upgrade anything yet. This means - any tunnel client and any tunnel server; make this configuration change to all hubs with tunnels ahead of time.
- Deploy the 23.4.7.1 hotfix to all tunnel clients first; if you are in a "multi-tier" environment with some hubs acting as both server and client, upgrade the "farthest-away" or edge clients first, then work your way in toward the primary hub.
- Once all the tunnel clients are upgraded, upgrade the tunnel servers.
This can be done either before or after the upgrade to CU7 is run on the primary hub, and it will not be necessary to apply the 23.4.7.1 hotfix to the primary hub if there are no tunnels present.
For Secure Hub/Robot Installations:
Customers who are running the Secure Bus (hub_secure and robot_update_secure packags) have two options:
1. Re-Do the certificates with SHA384 encryption;
or
2. wait for CU8 (tentatively due around July 2026.)
Upgrading to CU7 with the SHA1 certificates in place will almost certainly fail, leaving the installation in a broken state which will be difficult to recover from.
The CU8 release will contain fixes for the secure hub and robot builds which can help avoid this scenario.
If you cannot wait for CU8 to upgrade your Secure Hub environment, the certificates can be re-issued ahead of time.
The easiest way to do this is to convert your Secure Bus environment back to a standard hub/robot environment, and then re-run the installer for your current DX UIM Version; choose "Enable Secure Binaries" in the installer and the environment will be converted back to Secure Bus with SHA384 certificates automatically.
Once you have done that, double-check that the certificates in the /hub/certs/ folder are SHA384 and then run the CU7 installer to upgrade.
Additional Information
Feedback
