Applies to:
Upgrades to Venafi Trust Protection Platform 18.4.
Summary:
Venafi Trust Protection Platform 18.4 introduces new functionality and several changes to existing functionality. Click here for a complete list of new features.
IMPORTANT! Before upgrading, read through this article carefully. Depending upon the version from which you're upgrading, several enhancements made over the past two years to Trust Protection Platform require that you take important steps, either before or immediately after upgrading.
Pay special attention to the list of features that have been deprecated, and to the list of features scheduled for deprecation.
For detailed upgrade steps, refer to the Readme.rtf document that is packaged with Venafi Trust Protection Platform 18.4 installation files.
Visit Venafi Product Life Cycle for more information about ship dates and when support for each version ends.
More Information:
CRITICAL: Must re-run sample-grants.sql script after upgrading database to 18.4 schema
The new Work Queue framework introduces new database-stored procedures which requires execute permissions to be given to the Windows service account that Venafi uses to communication with the database. If the sample-grants.sql script is not run, no work can be performed by Venafi Platform.
All Adaptable Scripts will be blocked from working until they are re-saved in the web UI
To increase the security of the Venafi Platform, the system now securely stores the last known good hash of the Adaptable PowerShell scripts. This prevents unauthorized edits of the adaptable scripts by Windows Server Administrators from being automatically executed by the Venafi Platform. Therefore, on upgrade, all adaptable scripts (except Adaptable Workflow) will stop processing.
After upgrading to 18.4, but before restarting the Venafi Platform Windows services, you must confirm that the correct (and exact same) version of the script is on all Venafi servers in the cluster. Next, you must re-open (either in WebAdmin or Aperture, depending on the feature) the screen where you specify the Adaptable PowerShell script, and re-save the page. Finally, start the Venafi Platform Windows services.
New updates to Adaptable solutions need to be manually replicated on all servers in the cluster, and will require administrator acknowledgement whenever the associated PowerShell script changes.
Potential longer upgrade time between 18.3 and 18.4
Due to the re-write of the work queue framework, existing queued actions against certificates and keys must be migrated to the new framework. If there is a significant amount of pending actions in the system at the time of upgrade, you may see longer than normal upgrade times. For example, if you have 20,000 queued actions when you upgrade, the upgrade time will take approximately five minutes longer to make the migration.
If upgrading from 18.2 or lower, significant changes made in Trust Protection Platform affect how the database stores vaults and references to objects. These changes require a migration of how data is stored in the database. Depending on the size of your database, and the configuration of AlwaysOn, you can expect the SQL migration scripts to take 10-25 minutes longer than normal for larger deployments.
Unix/Linux Server Agent now setting file permissions on installed certificate keystores
Previous versions of the Venafi Platform and Server Agent did not honor permission configuration of certificate keystores when installed by the Server Agent.
Starting in 18.4, these permission configurations for certificate installation for Unix/Linux agents will be honored, so you should verify that the permissions that you have in place are correct.
_________________________________
Upgrade Process - Do Not Uninstall Previous Version
When upgrading to 18.4, install 18.4 directly on top of your currently supported version of Venafi Trust Protection Platform. While Venafi has always recommended this as a best practice, uninstalling the previous version before installing version 18.4 now results in complications to the upgrade process.
Your end users can now request additional SAN types in Aperture
In previous versions, Aperture only supported DNS SANs to be requested on a certificate. Beginning with 18.3, in addition to DNS SANs, Aperture now supports IP, URI, UPN, and email SAN types. If you don't want your users to be able to request these types of SANs, or if you're concerned that they might be confused by the new options, visit your Certificate Policy settings in Aperture to disable the use of specific SAN types.
SSH "self-service" feature replaces "external key" feature
Beginning in version 18.3, the new Self-Service Keys feature has replaced the External Keys feature. Therefore, after upgrading, you can no longer create external keys. Instead, create self-service keys. This is typically done when you're resolving orphaned keys or when you have a user with a device that is not in the Trust Protection Platform inventory. After upgrading, you'll have the option of migrating each external key to a self-service key (from the Keyset Details page in Aperture).
User Portal now shows the current version of certificates
Your end users can now request and download certificates, including previous versions, directly from the portal. In addition, the user experience has been improved through significant visual enhancements.
NOTE: Because of these enhancements, some of the product terminology has been updated; so if you have customized the terminology or styles in your implementation of the User Portal, you should revisit and update your customization to match these changes. For more information, visit https://support.venafi.com/hc/en-us/articles/228093008.
Amazon integrations updated to leverage new credential type
Prior to the 18.3 release, password credentials were used to configure different Amazon integrations, such as Certificate Authority, Provisioning Driver, and AWS EC2 Instance Monitoring. During the upgrade from 18.2 or lower, these integrations are migrated automatically so that they leverage the new Amazon credential type. However, if you have any WebSDK integrations that automate creating or editing these types of objects in Trust Protection Platform, you'll need to update your WebSDK integration. This is because these integrations now require the use of the Amazon Credential type in order to support ADFS SAML authentication into Amazon Web Services.
Permissions updated for running Server Agent on Linux/Unix
The permissions that the Server Agent installs with have been updated. Specifically, user and group permissions have been updated so that they are set to 0 (where in some places they were previously set to 5). Therefore, if you'd had non-root users interacting with the Server Agent previous to upgrading from 18.2 or lower, then you may need to revisit their sudo permissions after the latest version of the Server Agent is installed.
System must provide iconv functionality for Server Agents running on Linux
In previous versions, Server Agent implemented its own iconv functionality. Beginning with version 18.3, Server Agent now requires that your system libc provides the iconv functionality. You should make sure that iconv is available before upgrading either Trust Protection Platform or Server Agent. Current versions of glibc (The GNU C Library) provide the required functionality. The required files should be installed as part of the glibc package.
Workflow Approval Logs
Beginning with release 18.2, permissions were added and are now required in order to see the approval and rejection logs in WebAdmin. On upgrade, by default only Master Admins will have permission to see the log. If there are approvers or other users that should see these special log views, you will need to give those users and groups view/read permissions.
Workflow approver update interval
In versions 18.1 or earlier of Venafi Platform, if the approvers for a workflow changed for an existing workflow ticket, the ticket would be deleted and recreated so that the updated approver could act on the workflow ticket. In order to improve the scalability and stability of the platform when there many outstanding workflow tickets requiring approval, the interval for updating existing tickets has changed from 1 minute to 4 hours. This means that if the approver changes, it will take Venafi Platform approximately 4 hours to respond to updates regarding who the approvers are for existing workflow tickets.
Referrer and Origin Checking
To enhance the security of the web consoles, both Aperture and WebAdmin have been enhanced to check that the referrer or the origin in the HTTP headers is not null. In addition to not being null, if either has a non-null value the fully qualified domain name must match the fully qualified domain name of the Venafi Platform server hosting the web console. Some corporate proxies are configured to remove or modify the referrer and/or origin from the HTTP header. Some users may install browser plugin/extensions that also remove/modify the referrer/origin. After upgrade, users or organizations in these situations will have problems with the Web UI consoles.
If you are getting a “403 Forbidden” error in either Aperture or WebAdmin, then your organization or specific user likely has a browser plugin or corporate proxy that is stripping out both referrer and origin information from HTTP headers. For information on how to troubleshoot this issue, visit:
https://docs.venafi.com/Docs/current/TopNav/Content/Aperture/tr-aperture-tpp.php
WebSDK Integrations for Disabled and In Error
In order to optimize performance for certain certificate queries, Disabled and In Error were promoted from being attributes within the config_contains tables to permanent columns within the config_objects table. Even though all parts of the product, including WebSDK, were updated to ensure that this was a safe change, it is highly recommended that customers spend more time testing their WebSDK integrations in lower environments before upgrading to production in 18.2.
Master Admins Permissions Changed
Beginning with release 18.2, Master Admins can no longer have their permissions accidentally or intentionally removed at certain portions of the policy tree. This change occurred because of the number of customers unintentionally making changes to the permissions of Master Admin accounts which resulted in a call to a Venafi Support Engineering to reverse the problem. Adding extra permissions to Master Admins causes considerable slow downs for Aperture, WebAdmin, and WhyCustom Reports created by that user. By completely removing the ability to change Master Admins permissions in subsets of the tree, all Master Admins will see an increased performance benefit. It is important to note that when managing permissions, it is still possible to add Master Admins to the permissions control for a specific object and its children, but those permissions assignments will be ignored.
AWS certificate installation/provisioning driver changes it default provisioning behavior
Beginning in release 18.2, the default behavior of the Amazon Web Services certificate installation/provisioning driver when it provisions non-Amazon issued certificates has changed. By default, certificates are now provisioned to the Amazon Certificate Manager (ACM) store instead of the IAM store. Certificates can still be provisioned to the IAM store if the Provision To setting is changed.
Venafi does not generally change default behavior because it creates a “breaking change” but it was appropriate here because it brought the integration into alignment with Amazon’s recommendations:
“ACM is the preferred tool to provision, manage, and deploy your server certificates. With ACM you can request a certificate or deploy an existing ACM or external certificate to AWS resources. Certificates provided by ACM are free and automatically renew. You can use ACM to manage server certificates from the console or programmatically. For more information about using ACM, see the AWS Certificate Manager User Guide.”
“Use IAM as a certificate manager only when you must support HTTPS connections in a region that is not supported by ACM. IAM securely encrypts your private keys and stores the encrypted version in IAM SSL certificate storage. IAM supports deploying server certificates in all regions, but you must obtain your certificate from an external provider for use with AWS. You cannot upload an ACM certificate to IAM. Additionally, you cannot manage your certificates from the IAM Console.”
https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_server-certs.html
Supported/Compatible Browsers Changed
In order to bring parity to what Venafi supports and tests with and what is being used by customers in production, Google’s Chrome browser has been changed from compatible to supported.
Mozilla Firefox has been changed from supported to compatible. Also, in 18.2 we updated the compatible Firefox ESR version to Firefox ESR 60.
Server Agent: Remote Mount Point Scanning
In previous versions of the Server Agent, NFS and CIFS mount points on Windows and *NIX operating systems were always scanned, even when not configured to do so. In Trust Protection Platform 18.2, Server Agent now properly honors the agent certificate discovery work configuration as to whether to scan NFS and CIFS mount points or not. In addition, specific detection has been added for file systems mounted via NTFS junction points and their scanning is controlled via the same expanded option. If you use Server Agent to do certificate discovery, you should review your work definition with regards to the configuration of the scanned systems.
Note: The *NIX portion of this fix was introduced in the 18.1 version of the Server Agent. The Windows portion of the fix was introduced in the 18.2 version of the Server Agent.
18.2 User Agent for macOS and Windows requires Venafi Platform 18.2 or higher
While our general rule is that the Venafi Platform must be the same version or newer than the User Agent, we are specifically calling it out this release because of the overhaul done in this specific version. With the introduction of macOS and non-domain joined windows support, new APIs were introduced that require a Venafi Platform 18.2 or higher server for successful communication. Older versions of User Agent will still function with a Venafi Platform 18.2 server.
Deprecation of Windows Server 2008 R2
With the release of Trust Protection Platform 17.4, support for Windows Server 2008 R2 was removed. Trust Protection Platform 18.1 and 18.2 take advantage of new functionality available in Windows Server 2012 and 2016. Therefore, you can no longer install on Windows Server 2008 R2. Please upgrade or replace your Windows systems with Windows 2012 R2 or Windows 2016 servers before attempting to upgrade to Trust Protection Platform 18.1 or 18.2.
Deprecation of Microsoft SQL 2008 R2
Before upgrading to Trust Protection Platform 18.2, verify that the Microsoft SQL Server hosting the Trust Protection Platform database is running Microsoft SQL Server 2012 SP2, 2014, or 2016 with the latest patches applied.
For more information, see Error: "This Upgrade Is Not Allowed Due To An Incompatible Version Of SQL Server"
Venafi Advanced Key Protect Required for HSM Remote Key Generation
If you have been provisioning certificates with keys remotely generated in a Gemalto SafeNet HSM and want to continue doing so, you must enable Advanced Key Protect after upgrading to Trust Protection Platform 18.2.
Upgrade Process - Windows Services
Beginning with version 18.1 Venafi Platform includes a new and enhanced install and upgrade process. Following an upgrade, the new installer does not start Venafi Windows Services automatically. Instead, use the new Venafi Configuration Console on the Product node to start and stop services.
Upgrade Process - Windows Authentication to SQL Server
In previous versions of Trust Protection Platform, when using Windows Authentication for communicating with the Venafi MSSQL Server, the Windows user who performed the Trust Protection Platform upgrade was also required to have appropriate permissions for database access. However, starting with Trust Protection Platform 18.1, this is no longer true. This is because the newly enhanced installation and upgrade process allows database communication to be proxied through the database credentials specified at installation.
Server Agent: RPM Files are Now Signed
Starting with Server Agent 18.1, Server Agent RPM files are now signed with an RPM V4 signature. In order to properly validate the RPM files before installation or upgrade, import the Venafi RPM signing key before installation/upgrade. Validation of RPM V4 signatures might fail on versions of RHEL that are earlier than 6.0. In addition, if you customize the RPM, the signature will no longer be valid.
Oracle Access Manager/SSO Authentication Refactor
Where Trust Protection Platform is configured to authenticate via custom header attributes, Oracle Access Manager integration has been refactored in 17.4 and renamed Pass-through Authentication. If you are integrating with Oracle Access Manager, Siteminder, or any other Single-Sign-On solution that integrates via custom HTTP headers, you will need to update your configuration before the integration will work on 17.4.
For more information, see: Pass-Through Authentication For SSO Updated In 17.4
DigiCert CA Platform Support
The DigiCert integration driver was updated in 17.3 to support CertCentral. It no longer supports the legacy Enterprise platform. If you are currently using the Enterprise platform, please coordinate with DigiCert to migrate to the new CertCentral platform before upgrading to 18.2.
DataPower Integration Support
The DataPower integration driver was updated in 17.3 to support the new REST interface available on newer versions of DataPower. If you are using older versions that support the legacy SSH Command Line Interface (CLI), consider upgrading so that you can take advantage of new functionality in the integration. Legacy versions using SSH CLI are expected to continue to work, but are no longer actively tested.
Venafi License Report
Beginning with Trust Protection Platform 17.3, the Venafi License Report is automatically sent to Venafi. For more information, see Info: License Report Changes FAQ For 17.3
Update to Groups and Work
Beginning with Trust Protection Platform 17.2, the functionality for managing Server Agents, SSH Discovery/Remediation, User Portal, and Enterprise Mobility Agent changed significantly. If you are not yet familiar with these changes, or if you are planning to upgrade to version 17.2 or later, carefully review 17.2 Updates to Groups and Work to learn about the new functionality, why the changes were made, and specific tasks to consider following the upgrade.
SSH Key Internal Storage Migration
When upgrading from Trust Protection Platform 17.1 (or earlier), all SSH keys in the database are migrated to an updated storage format. When Venafi Control Center (VCC) is executed, it might take more time than normal for the migration to be completed. In Venafi's internal testing, the migration was able to process approximately 5,800 SSH keys every minute. For 100,000 keys, it might take about 20 minutes to run. The actual processing rate could vary depending upon version of SQL Server you're running, latency between Trust Protection Platform and the database server, database disk speed, CPU/RAM of the SQL Server, and other loads on the server that might be running during the same time period. The migration's progress is displayed in VCC.
During upgrade, you might see the following message in Trust Protection Platform logs:
"SSHManager - Erroneous Key Instance - Key at <path> removed from database because it did not have secret store association. You may need to re-discover this key."
This message indicates that your Trust Protection Platform instance was impacted by the following bug (#33848):
If the same private key was discovered on two devices and the first device was subsequently deleted, the private key was then placed into an orphaned state by TPP and became non-operational.
This bug has been addressed so that the issue will not occur again. The migration script returns the database back to a consistent state by removing the affected private key entries. The affected private keys must then be rediscovered. With agentless discovery, this will happen automatically during the next discovery. With agent-based discovery, you will need to flush the agent’s SSH key cache and re-discover keys on corresponding devices.
Symantec MPKI Enrollment Mode
In previous versions, the certificate that was renewed with the Symantec MPKI driver supported a per-certificate enrollment mode option with which you could control whether your renewal request was treated as a new, renewed, or replacement certificate.
As of Trust Protection Platform 17.2, this feature was migrated to settings on the Symantec certificate authority (CA) template in the Web Administration Console. Instead of managing the enrollment logic on a certificate-by-certificate basis, the logic is now automatic and configured for all certificates being enrolled via that CA template.
See Configuring the Symantec Managed PKI for SSL CA template 
Change in Requirements for Database Service Account Permissions
Enhancements made in 16.2 and 17.1 changed the permissions required by the Microsoft SQL Service account used to connect Trust Protection Platform to the database. Refer to the sample grant scripts (sample-grants.sql) in the Database Scripts\MSSQL\Grants folder for sample scripts to learn how to modify the permissions for your database.
Consult with your database administrator (DBA) before changing permissions for the database.
DSA SSH Credentials for SSH Connections
Trust Protection Platform 17.2 and 17.1.2 implemented a new version of Venafi's Maverick library that is used as an SSH client by Trust Protection Platform to communicate with remote systems. If you want to discover DSA keys or use DSA keys for authentication to remote systems, then do the following:
- In the Windows Control Panel, navigate to the Network Connections, Advanced settings. Disable the setting for Federal Information Processing Support (FIPS) compliance for this network.
- On the Trust Protection Platform server running Discovery, add the following registry key: HKLM\Software\Venafi\Platform\EnableSSHDSS (string key), value: 1.
Deprecated functionality:
Click here for the latest KB listing deprecated functionality in the current and past versions of Trust Protection Platform.
https://support.venafi.com/hc/en-us/articles/115001578651
Functionality scheduled for deprecation in future releases:
Click here for the latest KB article on features scheduled for deprecation in future releases of Trust Protection Platform.
https://support.venafi.com/hc/en-us/articles/115001662292
Comments