Upgrading

Most Keyfactor Command upgrades are brief with a minimum of changes to existing user accounts, groups, CAClosed A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. templates, firewall settings, etc. Most prerequisites have not materially changed from previous versions and the current version can generally be installed using the same hardware and existing instances of the supporting software. The upgrade process is often completed within three to four hours.

Before upgrading, please be sure you have reviewed and addressed the important preparation steps (see Preparing).

Important:  The MicrosoftECCurveUpgradeModule may fail due to a pre-version 10.0 issue in which Certificate Request Contents were truncated to 4k characters when saved to the database. If your upgrade fails when the MicrosoftECCurveUpgradeModule is run, contact Keyfactor Support to obtain assistance with the scripts that will have to be run to fix this issue.
Important:  During the upgrade process Keyfactor Command prevents duplicate templateClosed A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. records from being inserted into the database. Duplicate templates could be found, for example, if there are templates in different forests with the same name. If you receive an error message during upgrade, and the log shows a list of the duplicate templates, contact Keyfactor Support. We will be able to support you through the process of resolving the issue and completing the upgrade.

Before upgrading to a major version, Keyfactor recommends first upgrading to the final incremental version of the previous major version—completing both the software installation and configuration with the configuration wizard—for the optimal upgrade experience. For example, if you are currently on version 10.4 and want to upgrade to version 12.0 or later, you should upgrade first to version 10.5 (the final incremental version of 10.x) before upgrading. Contact your Client Success Manager for more information.

Please see the latest release notes (see Keyfactor Command Release Notes) if you are using any custom scripts that leverage the Keyfactor APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command..

The overall task flow consists of the following steps.

Upgrade Keyfactor Command on Windows Under IIS

Once you’ve confirmed that preparation is complete, you may move forward with the upgrade. You may or may not choose to manually upgrade the database ahead of time. If you have previously encountered upgrade issues or want to test the database upgrade step without risking downtime, this may be a good option for you. You can run the database upgrade tool on a temporary restored copy of the database without interrupting operations to confirm that the database upgrade will succeed and then upgrade the production database immediately before upgrading the server software.

Optional: Separately Upgrade the Database

The command-line Database Upgrade Tool can be used ahead of the Keyfactor Command software installation to bring the database up to the current version. This can be used to test database upgrades and resolve any issues before going forward with a full Keyfactor Command upgrade. For more information, see Using the Database Upgrade Tool.

Upgrade of the Server Software

In most cases the Keyfactor Command server software can be installed over the existing software installation without uninstalling the previous version. Install the software retaining the same installation location (see Installing). In the configuration wizard, populate the fields while referring to your configuration file open in a text editor (see Configuration File). Use the existing IIS application pool(s).

Important:  If you’re using the Keyfactor CA Policy Module on one or more certificate authorities, you may have been advised in the past to implement a workaround to resolve an error similar to the following:
Could not load file or assembly 'CSS.Common, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0ed89d330114ab09' or one of its dependencies. The system cannot find the file specified. at CSS.PKI.X509.X509Utilities..cctor()
2022-07-25 17:06:06.6851 CSS.CMS.CA.Msft.PolicyModule.Policy [Debug] - Certificate request denied or failed by handler CSSManagedTrustedSubject.PolicyHandler: -2146233088
denied by policy module

The workaround involved creating files CertSrv.exe.config and MMC.exe.config in C:\Windows\System32 on any certificate authorityClosed A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. on which you encountered this issue.

With the release of version 11.0 of Keyfactor Command, this workaround needs to be reversed. If the workaround is not reversed, you will encounter errors such as the following on enrollmentClosed Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). attempts:

Unable to enroll for certificate. The certificate request failed with the reason '0x80131902.'
2023-10-24 15:57:07.8547 Keyfactor.CA.Msft.PolicyModule.Policy [Error] - Failure verifying request: Configuration system failed to initialize
Unrecognized configuration section system.web. (C:\Windows\system32\certsrv.exe.config line 35)

To reverse the workaround, on the affected certificate authority:

  1. Rename C:\Windows\System32\CertSrv.exe.config to an alternate name or remove it from the System32 directory.

  2. Rename C:\Windows\System32\MMC.exe.config to an alternate name or remove it from the System32 directory.

  3. Restart the CA services.

  4. Confirm that certificate enrollment is working as desired and that the policy handler(s) in place are working as desired.

Replace or Re-Update Customized Files

Files such as the nlog.config file or customized files for third-party PAM integration (e.g. web.config customizations for CyberArk) may have slight changes in the latest version as compared to the previous version, so you should not just copy your old, customized versions of those files over the current stock versions of these files. You will need to compare the files and make your customizations in the current versions of the files.

Upgrade Keyfactor Command in Containers under Kubernetes

Once you’ve confirmed that preparation is complete, you may move forward with the upgrade. Upgrading Keyfactor Command in containers under Kubernetes is as simple as uninstalling and reinstalling using the helm chart with your custom values file (see Install Keyfactor Command in Containers Under Kubernetes). For example:

sudo helm uninstall Helm_Deployment_Name --namespace keyfactor-command
sudo helm install Helm_Deployment_Name --namespace keyfactor-command --values values-local.yaml oci://repo.keyfactor.com/charts/command --version 2.0.0
Migrate a Keyfactor Command Installation on Windows under IIS to Containers under Kubernetes

You may wish to work with a Keyfactor representative on a migration from an installation on Windows under IIS to an installation in containers under Kubernetes depending on the complexity of your environment, but if your environment is fairly straight-forward, you should have success without this. The basic process is:

Note:  If you’re both upgrading and migrating, you may either upgrade your database on Windows (using, for example, the Database Upgrade Tool—see Using the Database Upgrade Tool) and then migrate to a container installation under Kubernetes or upgrade and migrate in one step.
Upgrade Additional Components

Review the following additional components that may be affected by your Keyfactor Command upgrade. These may need to be upgraded or migrated as well.

In many cases the Keyfactor Universal OrchestratorClosed The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with servers and devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can provide certificate management capabilities on a variety of platforms and devices (e.g. Amazon Web Services (AWS) resources, Citrix\NetScaler devices, F5 devices, IIS stores, JKS keystores, PEM stores, and PKCS#12 stores) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux servers or Linux containers. can be installed over the existing installation without uninstalling the previous version. For specific upgrade guidance, see Upgrading the Universal Orchestrator.

Support for the Keyfactor Windows Orchestrator was deprecated in Keyfactor Command release 11.0. All uses of the Keyfactor Windows Orchestrator should be updated to the Keyfactor Universal Orchestrator. The Keyfactor Universal Orchestrator replaces the Keyfactor Windows Orchestrator and runs on both Windows or Linux servers. The following functions that were part of the Keyfactor Windows Orchestrator are supported in the Keyfactor Universal Orchestrator with custom extensions:

  • Interact with F5 devices for certificate management
  • Interact with NetScaler devices for certificate management
  • Interact with Amazon Web Services (AWS) resources for certificate management
  • Interact with Windows certificate stores and IIS

For more information about using custom extensions with the Keyfactor Universal Orchestrator, see Installing Custom-Built Extensions.

Important:  The Keyfactor Universal Orchestrator is only compatible with Keyfactor Command version 9.0 or later. The current version of the Keyfactor Universal Orchestrator is 25.1.1 and requires .NET 8. Check the compatibility matrix to identify which versions of the Keyfactor Universal Orchestrator are compatible with which versions of Keyfactor Command (see Compatibility Matrix).

If you're upgrading from a version of Keyfactor Command prior to 8.0, you will need to update any Windows Orchestrators (a.k.a. Windows Agents) that are used for SSLClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. scanning to support the current scanning architecture. Install and configure the Keyfactor Universal Orchestrator software (see Upgrading the Universal Orchestrator).

Note:  The orchestrator endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. location changed for Keyfactor Command release 6 and may need to be modified in your orchestrator endpoint configuration—from CMSAgents to KeyfactorAgents.
Important:  The most recent versions of the Keyfactor CA Policy Module software need to be upgraded using the below method and PowerShell script and can't be installed over an existing implementation of the Keyfactor CA Policy Module as an upgrade method.

To upgrade a Keyfactor CA Policy Module:

  1. Make a note of all your existing policy module configuration, including which policy handlers are enabled and what configurations are set within each handler. During the upgrade process, you will uninstall the policy module, which will remove your configuration. The upgrade script should successfully restore the configuration as part of the upgrade process, but you will want to have a complete record of the configuration as a backup.
  2. On the Keyfactor CA Policy Module server, open a PowerShell window using the “Run as administrator” option.

  3. In the PowerShell window, change to the directory in which you placed the upgrade script included with the latest version of the Keyfactor CA Policy Module and execute it in archive mode. For example:

    .\Keyfactor-CA-Modules-Upgrade-Script.ps1 -Mode archive -InformationAction Continue -ErrorAction Stop
    Note:  This step is creating a backup of your policy module configuration before you uninstall the old policy module. It will create an output file, Keyfactor-CA-Policy.dat, in the current directory.
    Tip:  Additional options are available in the upgrade script and can be viewed using the -full switch with Get-Help. For example:
    Get-Help .\Keyfactor-CA-Modules-Upgrade-Script.ps1 -full
  4. Unload the existing policy module in the CA MMC, and close the MMC.
  5. Uninstall the existing policy module.

  6. Install the latest version of the Keyfactor CA Policy Module but do not configure it (see Installing the Keyfactor CA Policy Module Handlers in the Keyfactor Command Server Installation Guide). Be sure to install all the same policy handlers that were installed previously.

    Execute the upgrade script included with the latest version of the Keyfactor CA Policy Module again, but this time in restore mode. For example:

    .\Keyfactor-CA-Modules-Upgrade-Script.ps1 -Mode restore -InformationAction Continue -ErrorAction Stop
    Note:  This step takes the backup of your policy module configuration from the first run of the upgrade script and restores the information to the correct locations so that you will not need to re-configure the policy module. Be sure that the output file from the first run of the upgrade script, Keyfactor-CA-Policy.dat, is in the current directory.
  7. Open the CA MMC and load the Keyfactor CA Policy Module (see Installing the Keyfactor CA Policy Module Handlers in the Keyfactor Command Server Installation Guide).
  8. Open the Properties for the policy module and, if you've received a new license, install the new license on the License tab. On the Custom Handlers tab, review all the configuration to confirm that it has been correctly restored by the upgrade script.
Tip:  New versions of the policy module are not necessarily released at the same time as new versions of Keyfactor Command and so the policy module may not need upgrading at the same time as Keyfactor Command.

If you're using an EJBCA gateway and wish to make use of the native support for EJBCA CAs in more recent versions of Keyfactor Command, you will need to follow the EJBCA gateway upgrade process to unlink the EJBCA certificates in your Keyfactor Command database from your EJBCA gateway CA to enable them to be relinked to a native CA configured in Keyfactor Command. For more information, contact Keyfactor support.

In most cases, the Keyfactor gateway software can be installed over the existing software installation without uninstalling the previous version. Review the configuration for your gateway, and then install and configure the software as per the Keyfactor gateway guide for the particular gateway, retaining the same installation location. The gateway configuration wizard has significantly changed in recent releases for many of the gateways, which may require modification to your configuration.

Tip:  New versions of CA gateways are not necessarily released at the same time as new versions of Keyfactor Command and so gateways may not need upgrading at the same time as Keyfactor Command.
Post-Install Configuration and Testing

See Post-Upgrade Steps

The bulk of the time upgrading will be spent verifying that all functions and configurations have correctly carried over and the upgraded instance is performing correctly.