Nexus Certificate Manager
Nexus Certificate Manager
Breadcrumbs

Upgrade Certificate Manager

This article describes how to upgrade Smart ID Certificate Manager to the latest version. For all other upgrade paths, contact Nexus.

Prerequisites

Step-by-step instruction

Sequential upgrade process

To upgrade from older versions to newer versions, you must upgrade each version step-by-step. 

  • Use files in the folder Upgrade/Upgrade from CM x.x.x to x.x.x.

Example: To upgrade from 8.11.0 to 8.14.0,

Follow the files in the following folders in sequence and do not start the services until all the upgrade steps are followed

  1. Upgrade from CM 8.11.x to 8.12.0

  2. Upgrade from CM 8.12.x to 8.13.0

  3. Upgrade from CM 8.13.x to 8.14.0

Exception: Upgrade from 8.10.0 and earlier

Support for MariaDB version below 10.5 has been removed in version 8.10.0 (and later) of Certificate Manager.

If you use MariaDB version below 10.5, you must upgrade before you proceed with the steps below. 

Exception: Upgrade from 7.18.x to 8.0.0

Support for the Oracle database version 11g has been removed in version 8.0.0 of Certificate Manager due to EOL.

If you use Oracle 11g, you must upgrade before you proceed with the steps below. 

1. Upgrade Certificate Manager Database

Database upgrade scripts are included in the delivery of Certificate Manager in the folder Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/.

  • It is important to sequentially run every database-specific upgrade script from the starting to the target version.

  • Skip release folders that contain no scripts as there are no databases related updates in version.

To upgrade the CMDB (Certificate Manager Database) run the script in your database client using the user ('lcmadmin') that has permission to change the database, add tables, and create indexes.

Make sure there are no errors after running the script.

Database script example

Database

Script

MSSQL

database/CMDBUpgrade_MSSQL_x_x_x.sql

MySQL

database/CMDBUpgrade_MySQL_x_x_x.sql

Oracle

database/CMDBUpgrade_Oracle_x_x_x.sql

PostgreSQL

database/CMDBUpgrade_PostgreSQL_x_x_x.sql

MariaDB

database/CMDBUpgrade_MariaDB_x_x_x.sql

AzureSQL

database/CMDBUpgrade_AzureSQL_x_x_x.sql

2. Upgrade Certificate Manager Configurations

Do the following steps on the server(s) that runs any of the Nexus CF, Nexus CIS, or Nexus SNMP services. 

  • Follow sequential upgrade process

  • Make sure a backup copy of these folders exists before applying any changes:

    • <cm-server-home>/config

    • <cm-server-home>/lib

    • <cm-server-home>/bin

    • <cm-server-home>/tools

From 7.18.x to 8.0.0

Upgrade steps

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. On the server(s) running the Nexus CF, Nexus CIS, or Nexus SNMP services:

    1. Do the configuration changes in <cm-server-home>/config/ described in the respective files under the <server> folder.

    2. Remove the following files from <cm-server-home>/config:

      • requestformats/httpclient.conf

      • http.conf

  3. The suggested default log levels for CM-SNMP has been reduced from FINEST to INFO. If you use CM-SNMP and want to change to the new default values, change this in the file <cm-server-home>/config/snmplog.properties.

  4. The following deprecated modifiers have been replaced or removed. If you use customized format files, make sure that none of the deprecated modifiers are used.

    1. These deprecated modifiers have been replaced:

      • SubjectKeyIdAdder > SubjectKeyIdentifierModifier

      • ScepUniqueness > RenewalAllowed

      • AltNameModifier > SubjectAltNameModifier

    2. These deprecated modifiers have been removed:

      • CheckCertWithSubject

      • CisFailoverModifier

      • DynamicValidity

      • InputStringBoundChecker

      • MonetaryLimitAttributeModifier

      • PublicKeyHash

      • RelativeValidity

      • ScepUniqueness

      • SubjectIdentifierSs

Updated license file required

CM 8.x requires an updated license file in order to start. License files issued for CM 7.x cannot be used for CM 8.x. Place the updated license file in the directory <cm-server-home>/license/.

From 8.0.x to 8.1.0

Upgrade steps

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. On the server(s) running the Nexus CF, Nexus CIS or Nexus SNMP services:

    1. Do the configuration changes in <cm-server-home>/config/ described in the respective files under the <server> folder. 
      Note the important changes described in the file changes-formats.txt. The file is located here: <Upgrade\Upgrade from CM 8.0.x to 8.1.0\server>. The tool used in changes-formats.txt requires updated lib files. Therefore those instructions should be executed after the new jar files has been replace in the final upgrade instruction.

    2. From Upgrade files CM 8.1.0/server/inputviews, add the following files to <cm-server-home>/inputviews, or replace if any of these files already exist:

      • acme-account-reg-search.conf

      • acme-prereg-search.conf

      • countries.conf

      • device-cert-registration.conf

      • estsecretsearch.conf

From 8.1.x to 8.2.0

Upgrade steps

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. On the server(s) running the Nexus CF, Nexus CIS, or Nexus SNMP services:

    1. Do the configuration changes in <cm-server-home>/config/ described in the respective files under the <server> folder.

From 8.2.x to 8.3.0

Upgrade steps

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. On the server(s) running the Nexus CF, Nexus CIS or Nexus SNMP services:

    1. Do the configuration changes in <cm-server-home>/config/ described in the respective files under the <server> folder.

    2. From <Upgrade files CM 8.3.0/server/inputviews>, add the following file to <cm-server-home>/inputviews:

      • scepdynamicpasswordregsearch.conf

From 8.3.x to 8.4.1

Upgrade steps

8.4.0 was replaced by 8.4.1. For more information, see Release note Certificate Manager 8.4.1. 

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. Do the configuration changes in <cm-server-home>/config/ described in the respective files under the <server> folder.

  3. From Upgrade files CM 8.4.1/server/inputviews, add these files to <cm-server-home>/inputviews:

    1. est-auth-cert.conf

    2. its-station-registration.conf

From 8.4.x to 8.5.0

Upgrade steps

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. Do the configuration changes in <cm-server-home>/config/ described in the respective files under the <server> folder. 
    Depending on which 8.4.x version you are currently on, some of the changes may already have been performed as part of an earlier upgrade.

From 8.5.x to 8.6.1

Upgrade steps

  1. Do the configuration changes in <cm-server-home>/config/ described in the respective files under the <server> folder.

  2. Depending on which 8.5.x version you are currently on, some of the changes may already have been performed as part of an earlier upgrade.

The ability to manually build CRLs and CILs has been moved from the officer role "Use AWB" to its own role in "Manual build of CRL and CIL". As such, if you have officers that should be able to perform manual builds of CXLs, then their officer profiles will need to be updated.

From 8.6.x to 8.7.1

Upgrade steps 8.6.x to 8.7.1

Important! Certificate Manager version 8.7.0 is no longer available on Nexus support portal.

  1. Ensure database is upgraded, when you upgrade CM from 8.6.x to 8.7.1, execute only the database script in the folder "Upgrade from CM 8.6.x to 8.7.0" in the release bundle.

  2. Do the configuration changes in <cm-server-home>/config/ described in the respective files under the <server> folder.

Upgrade steps 8.7.0 to 8.7.1

Important! Certificate Manager version 8.7.0 is no longer available on Nexus support portal.

  1. Ensure database is upgraded by running script only from folder Upgrade\Upgrade from CM 8.7.0 to 8.7.1\database

  2. Do the configuration changes on the server(s) running the Nexus CF, Nexus SNMP and Nexus CIS service in: <cm-server-home>/config/ and <cm-server-home>/inputviews/ described in the respective files under the <server> folder.

  3. From Upgrade files CM 8.7.1/server/inputviews, add the following file to <cm-server-home>/inputviews:

    • kerberos-pkinit-san.conf

From 8.7.x to 8.8.0

Upgrade steps

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. Do the configuration changes on the server(s) running the Nexus CF, Nexus SNMP and Nexus CIS service in: <cm-server-home>/config/ and <cm-server-home>/inputviews/ described in the respective files under the <server> folder. Depending on which 8.7.x version you are currently on, some of the changes may already have been performed as part of an earlier upgrade.

    1. From Upgrade files CM 8.9.0/server/inputviews, add the following files to <cm-server-home>/inputviews:

      •  v2x-enroll-enabling-registration.conf

      • kerberos-pkinit-san.conf

    2.  From Upgrade files CM 8.9.0/server/config, add the following file to <cm-server-home>/config:

      • rapcacsv2.conf

  3. Only for upgrades coming from earlier that 8.1.x: Run any steps that may have been postponed in earlier steps, such as those required for "copycacerts" when upgrading from CM 7.17.x or those in changes-format.txt when upgrading from CM 8.0.x.

From 8.8.x to 8.9.0

Upgrade steps

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. Do the configuration changes on the server(s) running the Nexus CF, Nexus SNMP, and Nexus CIS service in: <cm-server-home>/config/ described in the respective files under the <server> folder.

From 8.9.x to 8.10.0

Upgrade steps

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. Do the configuration changes on the server(s) running the Nexus CF, Nexus SNMP, and Nexus CIS service in: <cm-server-home>/config/ described in the respective files under the <server> folder.

From 8.10.x to 8.11.0

Upgrade steps

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. On Linux, if you are upgrading from a Certificate Manager version earlier than 8.9.x, remove the Nexus CIS, CF and SNMP services using the cmservices tool:
     <install_root>/bin/cmservices remove cf
     <install_root>/bin/cmservices remove cis
     <install_root>/bin/cmservices remove cmsnmp

  3. Do the configuration changes on the server(s) running the Nexus CF, Nexus SNMP, and Nexus CIS service in: <cm-server-home>/config/ described in the respective files under the <server> folder.

From 8.11.x to 8.12.0

Upgrade steps

  1. Do the configuration changes on the server(s) running the Nexus CF, Nexus SNMP, and Nexus CIS service in: <cm-server-home>/config/ described in the respective files under the <server> folder.

From 8.12.x to 8.13.0

Upgrade steps

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. Do the configuration changes on the server(s) running the Nexus CF, Nexus SNMP, and Nexus CIS service in: <cm-server-home>/config/ described in the respective files under the <server> folder.

From 8.13.x to 8.14.0

Upgrade steps

  1. Ensure Database is upgraded by running script (Upgrade/<Upgrade from CM x.x.x to x.x.x>/database/)

  2. Do the configuration changes on the server(s) running the Nexus CF, Nexus SNMP, and Nexus CIS service in: <cm-server-home>/config/ described in the respective files under the <server> folder.

3. Upgrade Certificate Manager Runtime Components

Final upgrade step

The lib, bin, and tool folders should always be postponed until the last step of the upgrade procedure to enable a successful upgrade to the latest version.

Before you start services, make sure steps 1 to 3 have been performed

3.1 Java Virtual Machine

If upgrading from a CM version earlier than 8.11.x, make sure 64-bit Java SE 21 is installed and properly configured to be used by CF, CIS and SNMP services.

Windows 
open the Registry Editor.
   In "HKEY_LOCAL_MACHINE\\SOFTWARE\\Nexus\\Service Parameters\\CF".
   Edit the variable JREPath so it instead points to Java 21
   home directory.
Linux 
navigate to "<install_root>/bin" and edit the JAVA
   variable in the cf_launch.conf to point to Java 21.

3.2 Runtime Files

Do the configuration changes on the server(s) running the Nexus CF, Nexus SNMP, and Nexus CIS service in: <cm-server-home> 

  • Formats with filenames that start with an underscore (_) are ignored. If you have any required custom format files under <cm-server-home>/config/, example like(_example.conf) please rename so they will be loaded.

  • Remove all jar files in <cm-server-home>/lib folder and copy all jar files under Upgrade files CM 8.14.0/server/lib to <cm-server-home>/lib.

  • Replace all files under <cm-server-home>/tools with the new ones under Upgrade files CM 8.14.0/server/tools.

  • Replace old files under <cm-server-home>/bin with the new ones under Upgrade files CM 8.14.0/server/bin

  • Replace old files under <cm-server-home>/deliverynotes with the new ones under Upgrade files CM 8.14.0/server/deliverynotes

3.3 CM Services

If upgrading from a CM version earlier than CM version 8.9.x, the CM service must be reinstalled

<install_root>/bin/cmservices remove cf
<install_root>/bin/cmservices remove cis
<install_root>/bin/cmservices remove cmsnmp
<install_root>/bin/cmservices install cf cmuser cmuser
<install_root>/bin/cmservices install cis cmuser cmuser
<install_root>/bin/cmservices install cmsnmp cmuser cmuser

4. Start CM Services 

sudo service cmsnmp start
sudo service cis start
sudo service cf start

Make sure services started successfully and verify logs.

5. Upgrade Certificate Manager clients

From 7.18.x to 8.0.0

The directory containing user-specific settings has moved. These settings include the list of favorite CM servers, the trust store for the server TLS certificates, selected columns in various GUI elements, and other client-specific settings.

To keep the settings from a previous client installation, move the following directories to the new location:

On Windows:

  • Previously: %USERPROFILE%\CertificateManager

  • New location: %APPDATA%\Nexus\CertificateManager

On Linux:

  • Previously: ~/CertificateManager

  • New location: ~/.config/certificatemanager

Upgrade CM clients

Do the following:

  1. Shut down all the Certificate Manager clients.

  2. Make sure Java SE 21 is installed and set as default Java on the system. Clients can be run on both 32-bit and 64-bit JDKs with the following limitations:

    1. Linux:
      64-bit Java is required in order to use clients with Personal Desktop Client.

    2. Windows:
      After the upgrade, if a javaw.exe binary exists under the C:\Windows\SysWOW64 folder, clients will continue to run on 32-bit Java even if default JDK is 64-bit. Remove this binary (and javaws.exe, java.exe) in order to run the clients on 64-bit Java.

  3. Backup the <cm-client-home>/config folder.

  4. Uninstall the Certificate Manager client components, see Uninstall Certificate Manager server components and clients. 

    1. On Windows use "Programs and Features" to uninstall "Certificate Manager Clients Components".

    2. On Linux, run <cm-client-home>/install/setup.sh -u.

  5. Remove any remaining hotfix jar files in the <cm-client-home>/lib folder.

    1. On Linux, if there is a <cm-client-home>/P11 folder, backup any config file with customizations to Personal Desktop Client and then delete the folder.

  6. Install the new version of the clients, included in the delivery of Certificate Manager.

  7. Apply any customizations to the new configuration files in the <cm-client-home>/config folder.

The officer role "Use AWB" is now used for read-only access to the AWB and no longer has permission to do manual builds of CRLs and CILs. Instead, the role "Manual build of CRL and CIL" is needed to perform manual builds.

The officer profile that was previously used by the officer that performed manual builds must now be modified to include the role "Manual build of CRL and CIL".

6. Upgrade Certificate Manager Protocol Gateway

See Upgrade Protocol Gateway. 

7. Upgrade Certificate Manager SDK

Upgrade Certificate Manager SDK

Exception when upgrading from 7.18.x

When upgrading from 7.18.x to 8.0.0, many deprecated methods have been removed from the CM SDK. See changes-cmsdk.txt in the <Upgrade/Upgrade from CM 7.18.x to 8.0.0/client> folder.

  1. Shut down all applications that are using the CM SDK except for CMWS and PGW.

  2. Backup the library folder of the CM SDK application.

  3. Remove the CM hotfix jar files in the library folder of the CM SDK application folder that adhere to the following patterns:

    • a-*.jar

    • aa*.jar

  4. Replace the jar files in the library folder of the CM SDK application with the supplied files in Upgrade files CM x.x.x/sdk/lib.