Important Considerations before upgrading CyberArk Trust Protection Foundation - Self-Hosted
Applies to
Upgrading to Trust Protection Foundation 26.1.
Summary
Trust Protection Foundation 26.1 introduces new functionality and several changes to existing functionality. Click here for a complete list of new 26.1 features for Trust Protection Foundation.
Trust Protection Foundation is the new name for the suite of tools formerly known as Venafi Trust Protection Platform. It includes CyberArk Certificate Manager - Self-Hosted (formerly known as TLS Protect DataCenter), CyberArk SSH Manager for Machines (formerly known as SSH Protect) and CyberArk Code Sign Manager (formerly known as CodeSign Protect).
IMPORTANT! Before upgrading, read through this article. Depending upon the version from which you’re upgrading, several enhancements made over the past two years to Trust Protection Foundation require that you take important steps, either before or immediately after upgrading. This section also includes comments regarding less critical but important changes to note as you upgrade.
Pay special attention to the list of features that have been deprecated, and to the list of features scheduled for deprecation.
For detailed information about this release, refer to the Readme online.
For detailed information on how to upgrade your installation to 26.1, please review the information in the Installation and Upgrade Guide.
Visit Product Life Cycle for more information about ship dates and when support for each version ends.
New in version 26.1
Breaking Change: DigiCert Email Address Validation
Email Subject Alternative Names (SANs) are now required for both Client and S/MIME certificate types.
If you have existing certificate policies or workflows that allow Client certificates to be issued without an email address, those requests, including automated renewals for existing certificates, will fail after upgrading to 26.1. Before upgrading, please take the following steps: - Review your DigiCert CA templates and Client certificate policies. - Ensure all certificate requests for both Client and S/MIME types are configured to require an email address in the SAN. - Update any automated scripts or workflows that request these certificate types to ensure they are passing an email address. - Identify any existing Client certificates currently deployed without an email SAN, as they will need an email address added prior to their next renewal.
See DigiCert Central requirements.
SSH Discovery: Dynamic Home Directory Resolution
Starting in 26.1, Trust Protection Foundation no longer assumes user
home directories are under /home/{USER}. It now looks up
each user’s real home directory—matching OpenSSH’s own logic—using the
system user database (for example /etc/passwd, or directory
services like LDAP/NIS through standard system lookups such as
getent passwd).
Because of this change, authorized keys in non-standard or network-mounted home directories (for example NFS homes) that were previously shown as Idle may now be shown as Authorized.
After you upgrade, you may see a change in these numbers in SSH Keyset Inventory after the first discovery scan.
See Discovering authorized SSH keys using sshd_config.
FTP report delivery is no longer supported
Starting in 26.1, FTP is no longer available as a delivery method for legacy reports or custom reports. This change addresses security concerns, as FTP transmits credentials in cleartext over the network.
Action required: If you have reports configured for FTP delivery, you must reconfigure them to use one of the following secure alternatives:
- Windows Share - Delivers reports to a network share using SMB/CIFS protocol
- SFTP (SSH File Transfer Protocol) - Delivers reports securely over SSH
To update your report delivery settings:
- Navigate to the report configuration in the administrative console
- Locate the delivery settings
- Change the delivery method from FTP to either Windows Share or SFTP
- Update the connection credentials and path as needed
Updated Code Sign Client Versioning and Distribution
To improve your organization’s security posture, the Client
Distribution page and the client’s --update flag now
retrieve the latest client version from a public distribution endpoint,
by default. This ensures your organization always has access to the most
current client, including the latest security fixes and patches. The
CyberArk Code Sign Client now supports both Code Sign Manager -
Self-Hosted and Code Sign Manager - SaaS, and is no longer
bundled with Certificate Manager installation files.
If your organization does not want to use the public distribution endpoint, you can disable it after a complete upgrade or install. Note that disabling this option means your organization will not automatically receive the latest client updates, security fixes, or patches. For details on managing client distribution, see Managing Code Sign Client distribution.
In addition, the Code Sign Client now uses a date-based versioning
format (yy.mm.dd.build). Learn
more
SCIM identity connectors and SAML configuration changes
Trust Protection Foundation 26.1 adds SCIM 2.0 support for modern identity providers. Two changes from this work affect customers upgrading to 26.1.
Automatic SAML configuration move (applies to all SAML customers)
The legacy SAML code path has been removed in 26.1. During upgrade, your existing SAML configuration is automatically moved onto the highest-ranked non-local identity connector. After upgrading, confirm that your SAML-based SSO login still succeeds.
Authenticating SCIM-provisioned users to clients and snap-ins
SCIM-provisioned users may not have a local password in Trust Protection Foundation, so they cannot authenticate to clients that previously required a username and password. SCIM-provisioned users sign in to the following via the OAuth 2.0 Device Authorization Flow:
- MMC snap-ins — OAuth 2.0 sign-in for SCIM-provisioned users. Username/password sign-in continues to work for users who still have local credentials.
- Code Sign Client — pass the
--deviceoption to trigger the OAuth 2.0 Device Authorization Flow. Required for SCIM-provisioned signers. - AuthZHelper — OAuth 2.0 Device Authorization Flow for the same reason.
- WebSDK — SCIM-provisioned users obtain an OAuth grant for WebSDK access via the OAuth 2.0 Device Authorization Flow.
Local accounts remain enabled after upgrade
In previous releases, configuring SAML SSO disabled local account login—SAML was the only way to sign in. Starting in 26.1, Trust Protection Foundation supports multiple SSO methods at the same time, and local accounts remain enabled and available for sign-in alongside any SSO configuration. This applies whether or not you use SCIM. To prevent local accounts from being used to log in, disable each local user account individually.
See Configuring a SCIM connector.
Unassigned certificates now stay licensed once managed
Starting in 26.1, Trust Protection Foundation permanently tracks whether a certificate has ever been managed. The first time a certificate’s management type is set to Monitoring, Enrollment, or Provisioning, the certificate is flagged as having been managed. This flag is set during nightly tasks and is one-way — once set, it is never cleared.
License counting is now based on this flag rather than on the certificate’s current management type. As a result, a certificate that has ever been managed continues to count toward your license even if it is later returned to Unassigned. The web interface prevents you from setting a previously managed certificate back to Unassigned; policy-lock or Web SDK overrides visually show Unassigned, but the certificate remains licensed.
What this means for you: Unassigned is intended as a temporary triage bucket for newly discovered certificates, not as a way to keep certificates alive but unlicensed over the long term. If you previously relied on returning certificates to Unassigned (for example, by locking a policy folder to Unassigned during renewal periods) to reduce your license count, that approach no longer lowers your count after upgrading to 26.1.
New in version 25.3
Breaking Change: MSI installer file names updated
As part of our ongoing rebrand of Venafi products into the CyberArk portfolio, several MSI file names have changed in this release. If you use scripted installations or upgrades, you will need to update your scripts with the new MSI files.
| Old .msi name | New .msi name |
|---|---|
VenafiMmc-XX.X.X.msi
|
RemoteMmc-XX.X.X.msi
|
VenafiTPPInstall-XX.X.X.msi
|
CyberArkTrustProtectionFoundationInstall-XX.X.X.msi
|
VenafiUpdaterInstallerx64.msi
|
UpdaterInstallerx64.msi
|
VenafiWinAdmin-XX.X.X.msi
|
WinAdmin-XX.X.X.msi
|
Note: XX.X.X represents the product
version number.
In this release folder and installation path names remain changed, as do component names, so you can continue to use existing Answer Files.
WebView2 runtime requirement
Starting in version 25.3, Venafi Platform no longer includes the Microsoft Edge WebView2 runtime. You must install WebView2 on all target servers before installing or upgrading to 25.3 or later.
Venafi Platform now uses the system-installed WebView2 runtime instead of bundling fixed embedded libraries. This reduces the installer size and ensures you are always running the latest secure version of the runtime.
If you use deployment images or automated provisioning tools, update them to install the WebView2 Evergreen runtime.
You can download the Microsoft WebView 2 Evergreen Runtime from Microsoft Edge WebView2 - Microsoft Developer.
Additional resources
- Distribute your app and the WebView2 Runtime – Microsoft Docs
- Detect if a WebView2 Runtime is already installed - Microsoft Docs
Breaking change: Reset Code Sign Client after upgrading to version 25.3
If you use the macOS tkdriverconfig Code Sign Client,
you must reset the client after upgrading to version
25.3. Resetting requires the following steps:
- Revoke all existing grants for
tkdriverconfig, - Delete trusted certificates, and
- Re-establish trust and request a new grant.
1. Revoke existing grants
tkdriverconfig reset --all
2. Delete trusted certificates
Delete the user certificate store file at
/Users/<username>/.libhsmtrust.
3. Re-establish trust and request a new grant
tkdriverconfig getgrant
NOTE: If you had previously established trust with Code Sign Manager
servers other than the one used by tkdriverconfig, you’ll
need to re-establish that trust. You can do that using the
gpgconfig trust and pkcs11config trust
commands.
Update filenames for Code Sign Client installers
Code Sign Client installer filenames have changed. Update any automation that relies on the old filenames.
| Old filename | New filename |
|---|---|
venafi-codesigningclients-<version>-linux-aarch64.deb
|
cyberark-code-sign-client-<version>-linux-aarch64.deb
|
venafi-codesigningclients-<version>-linux-aarch64.rpm
|
cyberark-code-sign-client-<version>-linux-aarch64.rpm
|
venafi-codesigningclients-<version>-linux-x86_64.deb
|
cyberark-code-sign-client-<version>-linux-x86_64.deb
|
venafi-codesigningclients-<version>-linux-x86_64.rpm
|
cyberark-code-sign-client-<version>-linux-x86_64.rpm
|
VenafiCodeSigningClients-<version>-x64.msi
|
CyberArkCodeSignClient-<version>-x64.msi
|
VenafiCodeSigningClients-<version>-x86.msi
|
CyberArkCodeSignClient-<version>-x86.msi
|
Venafi CodeSign Protect Clients v<version>-universal.dmg
|
CyberArk Code Sign Client v<version>-universal.dmg
|
SSH Manager for Machines
Users of SSH Manager for Machines, formerly SSH Protect, should consider the following details when upgrading to 25.3 and/or using the new AuthZHelper utility and SSH Authorization Rules features.
- A dedicated Trust Protection Foundation instance is recommended when using the AuthZHelper and SSH Authorization Rules feature. This is due to increased overhead related to SSH Authorization frequency.
- When using the AuthZHelper and SSH Authorization Rules feature, note that Agentless Discovery may incorrectly report authorized keys when AuthZHelper is enabled. This is because AuthZHelper uses its own configuration to specify the locations of authorized keys files, which may differ from the locations that the agent scans. As a result, the agent may not detect authorized keys managed by AuthZHelper, leading to discrepancies in reported key data.
- Because SSHD is configured with AuthorizedKeys set to ‘none’ when using AuthZHelper, the agent does not detect any authorized keys. Instead, AuthZHelper uses its own config.yaml to identify authorized keys, which can cause keys to appear mis-labeled or as public keys.
- AuthZHelper instances use a copy of the Trust Protection Foundation host’s TLS certificate to authenticate. This should be manually added to the AuthZHelper client’s config folder and can be monitored and rotated using Trust Protection Foundation. Alternatively, if Trust Protection Foundation is utilizing a certificate that is trusted by the client’s OS, then the api-cert reference is not needed.
- AuthZHelper is not compatible with EC2 Instance Connect. This is due to both tools making use of the AuthorizedKeysCommand directive.
- AuthZHelper is not compatible with the ‘match’ option in SSHD. If your organization uses this configuration, we recommend consulting with CyberArk’s Professional Services team to review before installing or modifying your sshd_config.
- SSH connection ‘Options’ (see SSH Man > Options) will be passed to AuthZHelper and then to SSH. This follows the SSH code flow in that options are added together as they are encountered (for example from TrustedUserCAKeys, then again from AuthorizedPrincipalsFile). In the event that there are conflicting options, AuthZHelper will DENY the connection with a log entry, “Conflicting options detected.”
- Known issue: If a user has configured their authorized_keys file with conflicting SSH Options (i.e. no-port-forwarding with permit-listen=“[HOST]:PORT”), the default behavior of SSHD is to try and reconcile those options, generally preferring the most restrictive result. However, some combinations are considered invalid by SSHD (i.e. multiple command= options). Any such “invalid” combination will result in a failed login by SSHD. In these cases, SSH Manager will reflect an “observed” rule indicating that the account does have access to the host. This choice was made to show all potential accesses in the ruleset, even if SSHD would ultimately deny those attempts due to the user’s misconfiguration of authorized_keys.
New in version 25.1
Algorithm changes across platform products
Trust Protection Platform 25.1 introduces broad support for over 100 algorithms across product lines. Be aware of the following:
- Upon upgrade you will be asked to determine which algorithms you want to support. The algorithms you select will be available across the product. You can restrict these to a subset for individual policy folders.
- In prior versions, if you wanted to specify an algorithm at the policy level, you could only specify a single algorithm. Starting with 25.1, you can provide a list of allowed algorithms for a given policy. If you want to further restrict this list at a lower policy level, you can, but you can’t select any algorithms disallowed by the higher-level policy.
- The default algorithms list is in priority order. If you have a certificate using an algorithm that is no longer permitted by policy (or by the global available algorithms list), the highest priority algorithm that is allowed by policy will be used for the renewal. Because of this pay attention to the order of algorithms in the allowed algorithms list when you select them as part of your upgrade.
Certificate chain building procedure changes
The logic for building certificate chains between versions 24.3 and 25.1 has been improved. As a result, the chains created during pushing, pulling, or downloading may change after upgrading.
PKI administrators should review the Certificate Chain Preferences tab on each CA Template and ensure the correct chain is selected. If the Automatic option does not provide the desired chain, manual adjustments may be necessary.
For more info, see Understanding CA template chaining.
Update certificate policy for PKIX and WebSDK
In version 25.1 there have been significant changes to the API calls for certificate requests. If you want to use the newly-supported algorithms, you will need to use the new API calls with the appropriate OID. If you are using the old versions of the API calls, there is currently support for backwards compatibility. However, even if you don’t want to support the new algorithms, you will want to develop a migration path because support for the older API methods will eventually be removed.
When using our WebSDK to specify policy of an algorithm, this is now stored differently in config and is viewed as a breaking change in some uncommon use cases. If your integration is using config to write the policy of allowed algorithms, then your WebSDK integration code will need to be updated for upgrades to 25.1 and beyond.
Data value changed to binary format
As part of the upgrade from versions 22.2 through 24.3, the Data value for the ‘Disabled’ attribute was changed from a binary format to a base64 encoded string. In version 25.1, we have reverted this change, and the Data value is now logged in its previous binary format.
EST-specific revocation settings
EST-specific revocation settings have been removed from the EST Work Settings section. EST Server now adheres to revocation settings defined for Trust Protection Platform via WebAdmin.
SSH Protect upgrade considerations
UI updates: The Default Private Key Algorithm and Allowed Private Key Algorithms are now configured for target policies via the “Create Certificate Object in Folder” option in the “SSH Certificate Template(s)” section. Previously, this configuration was managed via the “SSH Certificate Issuance Template” pages.
Tip: To adhere to certificate lifecycle management best practices, review and adjust the “Create Certificate Object in Folder” value within the “SSH Certificate Issuance Templates” section.
Key validation: Discovered keys are validated against the Allowed Algorithms list, which is defined by its corresponding policy.
SSH key and certificate settings: The policy settings Algorithm and Allowed Algorithms now affect both keys and certificates. - Keys: Existing policy settings are migrated to version 25.1. No action is required from customers for key generation. The same algorithm used in 24.3 will be used in 25.1. - Certificates: Template settings have been removed. Settings are now managed by the folder specified in the field Create Certificate Object in Folder. Customers should check the Algorithm and Allowed Algorithms specified in the folder. The same settings apply to keys issued under this folder.
Changes in certificate management
- Certificate settings moved from CA template to policy settings.
- Allowed algorithms for certificates are now controlled by policy settings.
- Future updates will remove key size information entirely.
Experimental post-quantum (PQ) keys invalidated
PQ algorithm support has been updated to the final FIPS 204 (ML-DSA) and 205 (SLH-DSA) standards. These changes made to the Trust Protection Platform will require all experimental PQ keys and certificates to be invalidated. All PQ keys will need to be regenerated after upgrade to 25.1.
- PQ keys used by CodeSign Protect single-user keypair environments will be automatically regenerated whenever a CodeSign Protect client retrieves the object list.
- PQ keys used by Server Certificates or by CodeSign Protect single-user certificate environments will need to be manually renewed via the UI or API.
- CodeSign Protect per-user environments will need to be manually deleted and re-created.
- Enabling “PostQuantum Experimental” in the Windows Registry is no longer necessary. PQ algorithms are now available by default.
- The standard for Composite keys has not been finalized yet, so those keys may need to be invalidated in a future release.
For a list for all supported algorithms, see Algorithm types supported by Trust Protection Platform.
CodeSign Protect statistics
The statistics providing data for the “All signings for the past” dashboard will be migrated during the upgrade process. The data will be incorrect on that dashboard until the following conditions have been met:
- The last Trust Protection Platform server has upgraded to 25.1.
- The statistics rollup that runs at the top of the hour has completed.
New in version 24.3
Breaking
change: Updated parameter names in
POST /vedsdk/codesign/RetrieveArchiveEntries
With the introduction of the CodeSign Protect Archive UI, several
enhancements were made to the
POST /vedsdk/codesign/RetrieveArchiveEntries REST endpoint.
These enhancements include renaming of two parameters:
Statusis nowEventTypeEventIdis nowEventTypeId
Any automations that rely on these parameters will need to be updated after upgrading to 24.3.
New Windows Dependency Requirements
There is a new system requirement for all Windows servers, including those upgrading. Though this is listed in the system requirements in the Server Configuration Requirements section, users who are upgrading from a prior release should be aware that there are two Visual C++ Runtime libraries you need to download and install from Microsoft before you install Venafi Platform.
You need to install both the 32-bit and 64-bit libraries.
By installing these libraries separately from Venafi Platform, Microsoft Update can provide security or other updates to these libraries without requiring an update of Venafi Platform.
Experimental post-quantum (PQ) keys invalidated
Post-quantum (PQ) cryptography standards continue to evolve. Changes made to the Trust Protection Platform experimental post-quantum implementation will require all PQ keys and certificates to be invalidated. All PQ keys will need to be regenerated after upgrade to 24.3.
-
PQ keys used by CodeSign Protect single-user keypair environments will be automatically regenerated whenever a CodeSign Protect client retrieves the object list.
-
PQ keys used by Server Certificates or by CodeSign Protect single-user certificate environments will need to be manually renewed via the UI or API.
-
CodeSign Protect per-user environments will need to be manually deleted and re-created.
Venafi will continue to improve support for PQ algorithms. Additional changes will be made in Trust Protection Platform 25.1 that will require the 24.3-created PQ keys and certificates to be invalidated at 25.1 upgrade.
Database Compatibility Level
With the deprecation of support for Microsoft SQL Server 2012, we also no longer support database compatibility level 110 (SQL Server 2012) or older. When you upgrade your SQL Server databases, be sure your database settings are updated to match the compatibility level of the version you are using.
New in version 24.1
Updated TPP 24.1 upgrade processes
When upgrading to TPP 24.1, you should follow the same decision-making strategies, preparation tasks and upgrade procedures you use for typical TPP server upgrades. See Upgrading Venafi Platform.
However, please note that when upgrading to TPP 24.1, you will see two differences from the typical upgrade process: (1) an enhancement to the TPP 24.1 installation program called PreFlightTool that reports the platform’s readiness to upgrade, and (2) a temporary suspension in operations during the upgrade’s final migration processes. For more information, see Updated TPP 24.1 Upgrade Processes.
Breaking change: Kubernetes Discovery Jobs and TLS Protect for Kubernetes
Venafi is transitioning from the TLS Protect for Kubernetes platform to the TLS Protect for Kubernetes module within the Venafi Control Plane. This update improves machine identity management for your Kubernetes environments.
Important action required: Before the upgrade, verify if your TLS Protect Datacenter instance has existing Kubernetes Discovery jobs. After the update, these jobs will no longer be compatible with the TLS Protect for Kubernetes platform. Delete any Kubernetes Discovery jobs before the upgrade to ensure a smooth transition. Contact your Venafi representative for more details and assistance.
Message Bus
A new requirement in 23.3 and continuing in 24.1 is that a Message Bus/MQTT framework must be available for services to function properly. On Upgrade you will be required to choose between a Self-Hosted (mesh network topography style) that is self managed by Venafi or a Central MQTT Broker (hub-and-spoke network topography style) that your organization provides.
Most customers will choose the self-hosted option, but requires that the configurable/default port of 8883 be accessible between all Venafi servers. If your network team is not able to accommodate this requirement, then it is recommended to investigate your organization providing a central MQTT broker that your organization is responsible for. If you have questions about how to plan for this requirement, please reach out to your Customer Success representative or Account Team.