Upgrade

Server Upgrade

UKCClosedUnbound Key Control - The name of Unbound's key management product. Server Upgrade includes the following steps:

  1. Release-specific Server Pre-upgrade.
  2. Server Upgrade.
  3. Release-specific Server Post-Upgrade.
  4. Restart and Test the EKMClosedEnterprise Key Management - The previous name of the product. Replaced by UKC. service.

As needed, Upgrade Repair.

Note
To upgrade UKCClosedUnbound Key Control - The name of Unbound's key management product. software installed in the user's directory, refer to Upgrade Server in User's Folder.

Server Pre-upgrade

Pre-upgrade for 2.0.2007 or earlier

Starting with the UKCClosedUnbound Key Control - The name of Unbound's key management product. server software release 2.0.1807, the upgrade procedure preserves the following files:

  • RHEL/Centos
    • /opt/ekm/conf/server.xml
    • /opt/ekm /conf/log4j.xml
    • /etc/default/ekm
    • /etc/dylog.conf
  • Windows
    • <install_dir>\tomcat_conf\server.xml
    • <install_dir>\tomcat_conf\log4j.xml

Warning
The following files are overwritten:
- /etc/init.d/ekm
- Catalina/localhost/rewrite.config
If you customized these files, make sure to save them and merge them later with the newly installed files:
-

Server Upgrade

You may validate the authenticity and integrity of the Debian and the RPMClosedFile format for software package distributed by RPM Package Manager package. Refer to Validating Debian and RPM Packages.

Server Post-Upgrade

The post-upgrade steps depend on the release you are upgrading from. The following table guides your steps:

  1. Select the UKCClosedUnbound Key Control - The name of Unbound's key management product. server software release that was installed before the upgrade. Refer to the "Upgrading from Release" column.
  2. Start by performing the step specified in the "Upgrade to Release ..." column.
  3. Continue performing all the following steps.
    1. In each step, examine the "Requirement" setting:
      • Mandatory - must be done
      • As Needed - depends on whether certain non-default system settings were overwritten by the upgrade. You must examine the case specified by the step.
Upgrading from Release Upgrade to Release ... Requirement
2.0.1806 or earlier Post-upgrade to 2.0.1807 As needed
2.0.1807 or earlier Post-upgrade to 2.0.1808 - XML files As needed
Post-upgrade to 2.0.1808 - Keystore Password Encryption Mandatory
2.0.1811 or earlier Post-upgrade to 2.0.1811 Mandatory
2.0.1904 or earlier Post-upgrade to 2.0.1907 Mandatory
2.0.1910 or earlier Post-upgrade to 2.0.2001 As needed
2.0.2004 or earlier Post-upgrade to 2.0.2007 Mandatory

Post-upgrade to 2.0.1807

Upgrade from 2.0.1806 or an earlier release overwrites the following files:

If these files were modified before the upgrade, reapply the changes.

Note
If you are reproducing a custom connector port="<number>" in the Server.xml File, set its keyStorePass and protocol settings as specified in the updated connector port="443".

Post-upgrade to 2.0.1808 - XML files

When upgrading from release 2.0.1807, the following rule applies to the log4j.xml and server.xml files:

  • If a file hasn't been changed (previous default settings) - the file is overwritten with the latest default settings.
  • If a file has been changed - the file is preserved, and the <file>.xml_original is added to the folder to present the latest default settings. In this case, examine the <file>.xml_original file and propagate the new features, if any, to the <file>.xml.
  • If you previously customized the server.xml file, replace its connector port="443" and connector port="8443" xml-elements according to their settings in the server.xml_original.

Post-upgrade to 2.0.1808 - Keystore Password Encryption

The UKCClosedUnbound Key Control - The name of Unbound's key management product. server SSLClosedSecure Sockets Layer - a cryptographic protocol that provides communications security over a computer network. certificate and the UKCClosedUnbound Key Control - The name of Unbound's key management product. CA trust certificate are stored in the password-protected keystore files key.pfx and root_ca.ks in the Certificates Folder. Before the 2.0.1808 release, these passwords were specified in plaintext in the Server.xml File :

In systems that were bootstrapped using the 2.0.1808 or later release, these passwords are encrypted. This fact is indicated by the password value "NotThePassword" while the encrypted password is stored in a binary file. The Connector port settings in these releases specify:

  • key.pfx password - "NotThePassword".
  • root_ca.ks password - "NotThePassword".
  • the SSLClosedSecure Sockets Layer - a cryptographic protocol that provides communications security over a computer network. protocol handler - the custom ObfuscatorProtocol that is aware of the key.pfx password encryption.

    • <Connector port="443" protocol="com.dyadicsec.ekm.syscrypto.ObfuscatorProtocol"
    maxThreads="150" SSLEnabled="true" scheme="https" secure="true"

    clientAuth="want" sslProtocol="TLS" sslEnabledProtocols="TLSv1.2"
    keystoreFile="/etc/ekm/ssl/key.pfx" keystorePass="NotThePassword" keystoreType="pkcs12"
    truststoreFile="/etc/ekm/ssl/root_ca.ks" truststorePass="NotThePassword" truststoreType="jks"/>

Though an upgrade of a pre-1808 release changed the protocol to "com.dyadicsec.ekm.syscrypto.ObfuscatorProtocol", the passwords remained as they were - in the plaintext. The objective of this step is to encrypt these passwords.

To encrypt the keystore and truststore passwords:

  1. Open Server.xml File and find the Connector port sections.
  2. Make sure that the

    protocol="com.dyadicsec.ekm.syscrypto.ObfuscatorProtocol"
  3. Change the passwords from "123456" to "NotThePassword":

    • keystorePass="NotThePassword"
    • truststorePass="NotThePassword"
  4. Save the changes.
  5. Run scripts:

Post-upgrade to 2.0.1811

In the 2.0.1812 release, the UKCClosedUnbound Key Control - The name of Unbound's key management product. TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network cipher suite has been hardened to exclude the SHA1 option from the eligible ciphers:

  1. Open the Server.xml File for editing.
  2. In Connector records Connector port="443", Connector port="8443", add the following line:

    3. ciphers="HIGH:!SHA1"

For example, using port 443,

<Connector port="443" protocol="com.dyadicsec.ekm.syscrypto.ObfuscatorProtocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true"

clientAuth="want" sslProtocol="TLS" sslEnabledProtocols="TLSv1.2" ciphers="HIGH:!SHA1" keystoreFile="${catalina.home}/../../etc/ekm/ssl/key.pfx" keystorePass="NotThePassword" keystoreType="pkcs12"
truststoreFile="${catalina.home}/../../etc/ekm/ssl/root_ca.ks" truststorePass="NotThePassword" truststoreType="jks"/>

Post-upgrade to 2.0.1907

To assure the integrity of key material metadata provided by EP to a client (such as whether it is exportable), the client may enable its check-integrity setting - refer to The Integrity of the Material Metadata. However, this capability is missing on servers upgraded from 2.0.1904 or an earlier release, resulting in a false alarm when the ucl show <key material> command is executed by a client. To mitigate this alarm and to enable this capability on upgraded servers, execute the ekm_gen_integrity_key script on the EP.

Post-upgrade to 2.0.2001

If you are planning to download signed crypto operations, you must rename crypto files collected by 2.0.1910 and earlier releases. Perform the following steps on both EP and its Partner servers in their Crypto Logs Files folder:

On the Linux and Mac

  1. sudo mkdir /opt/ekm/logs/old-crypto
  2. sudo mv /opt/ekm/logs/dy-ekm-crypto*.log /opt/ekm/logs/old-crypto/

On Windows

  1. Open the C:\Program Files\Dyadic\ekm\tomcat\logs folder.
  2. Make an old-crypto subfolder.
  3. Move dy-ekm-crypto*.log files to old-crypto subfolder.

Post-upgrade to 2.0.2007

In the 2.0.2007 release, the UKCClosedUnbound Key Control - The name of Unbound's key management product. TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network cipher suite has been hardened to exclude the SHA1 and CBC options from the eligible ciphers:

  1. Open the Server.xml File for editing.
  2. In Connector records Connector port="443" and Connector port="8443", replace the ciphers="HIGH:!SHA1" specification to the following (refer to Required SSL Cipher Suites

    3. ciphers="HIGH+AESGCM"

For example, using port 443,

<Connector port="443" protocol="com.dyadicsec.ekm.syscrypto.ObfuscatorProtocol"

maxThreads="150" SSLEnabled="true" scheme="https" secure="true"

clientAuth="want" sslProtocol="TLS" sslEnabledProtocols="TLSv1.2" ciphers="HIGH+AESGCM" keystoreFile="${catalina.home}/../../etc/ekm/ssl/key.pfx" keystorePass="NotThePassword" keystoreType="pkcs12"

truststoreFile="${catalina.home}/../../etc/ekm/ssl/root_ca.ks" truststorePass="NotThePassword" truststoreType="jks"/>

Note
Upgrading to 2.0.2007 overwrites the Catalina/localhost/rewrite.config file that might be customized, for example, to block UI.

Restart and Test

  1. Perform EKMClosedEnterprise Key Management - The previous name of the product. Replaced by UKC. Service Restart (refer to EKM Service Management) on every upgraded server. The first EKMClosedEnterprise Key Management - The previous name of the product. Replaced by UKC. service restart on an upgraded server contributes the following:
  2. To test the upgraded system, use the ucl server test command from the EP1 server (or any other EP server that is registered as the Root partition's client).

    3. Note
    If you run the command while some servers are engaged in the EKMClosedEnterprise Key Management - The previous name of the product. Replaced by UKC. service restart, these servers might appear as "unreachable". Wait and repeat the command.

    If despite the elapsed time a server shows as unreachable:

    1. Restart the server and repeat the ucl server test.
    2. If the problem remains:
      1. Examine Tomcat Logs on the unreachable server.
      2. If it does not reveal a reasonable cause, proceed to repair the upgrade.

Upgrade Repair

Client Upgrade

UKCClosedUnbound Key Control - The name of Unbound's key management product. client upgrade includes the following steps:

Client Pre-upgrade