Upgrades to Venafi Trust Protection Platform 18.3.
Venafi Trust Protection Platform 18.3 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.
For detailed upgrade steps, refer to the Readme.rtf document that is packaged with Venafi Trust Protection Platform 18.3 installation files.
Visit Venafi Product Life Cycle for more information about ship dates and when support for each version ends.
Expect longer upgrade time between 18.2 and 18.3
Significant changes made in Trust Protection Platform 18.3 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.
Upgrade Process - Do Not Uninstall Previous Version
When upgrading to 18.3, install 18.3 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.3 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
In Trust Protection Platform 18.3, the new Self-Service Keys feature has replaced the External Keys feature. Therefore, after upgrading to version 18.3, 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 to 18.3, 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 to 18.3, then you may need to revisit their sudo permissions after the 18.3 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 to version 18.3. 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
For 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 previous versions 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:
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
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.”
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 in this release.
Mozilla Firefox has been changed from supported to compatible. Also, in 18.2 we have 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
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 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
Trust Protection Platform 18.2 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.
Server Agent: Ignoring files larger than 10000 bytes
When discovering keystores, the Server Agent versions 17.4 and 18.1 are systematically ignoring files that are larger than 10000 bytes. Any certificates contained in such files are no longer discovered.
This issue will be resolved in a future software update. In the meantime, if you need to discover keystores larger than 10000 bytes, we recommend that you not upgrade the Server Agent to either 17.4, 18.1, or 18.2 until an update has been released.
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.
Oracle Database Server No Longer Supported
WARNING! If your Trust Protection Platform database is currently being hosted on Oracle, do NOT attempt to upgrade to 18.1 or 18.2. You must first migrate your production database from Oracle to Microsoft SQL Server. Contact Venafi Customer Support for assistance with the migration.
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.
Aperture Certificate Status Updated
The Certificate Inventory Status column is divided into two columns: Risks and Status. The Status column contains a single life-cycle stage, such as "Renewing" or "Pending My Approval". The Risks column can contain one or more tags, such as "Unapproved Issuer" and/or "No Local Dual Control". The Certificate Overview Banner has been updated to show "Status" information only (not Risk). If you have custom reports that were reporting on Status and wish for them to continue to report on certificate risk information, update the report to include the new column.
Encrypted Connection to Microsoft SQL
Trust Protection Platform offers the ability to require a secure, encrypted connection to the database. To enable this option, open Venafi Control Center (VCC) on each Trust Protection Platform server, click Change Database Password, select Encrypt all database communications, and click the Verify button. This security feature requires a valid TLS certificate on the Microsoft SQL Server. You may have to install/replace the certificate on your SQL server prior to enabling this functionality on each Trust Protection Platform server.
Trust Protection Platform 16.4 Requires .NET Framework 4.6.1
Before upgrading to Trust Protection Platform 18.3 from 16.4 (or earlier,) make sure the .NET Framework is updated to 4.6.1.
You can download the offline .NET 4.6.1 installer for Windows 2012 R2 at:
NOTE: Windows Server 2016 comes pre-installed with .NET 4.6.2
Privileged Command Set Change for SSH Agentless
Beginning with version 16.4, the list of commands that the SSH discovery and remediation engine runs with sudo privileges changed. Some commands are no longer required in order to run as a privileged user and some new commands are required. Refer to this article for detailed instructions on restricting commands in the sudoers file to only those required for the agentless SSH account.
The following commands are no longer required and can be removed from /etc/sudoers entry:
- sh –c find *
The following new commands need to be present in /etc/sudoers entry:
For more information, see: Restricting Account To Use With Agentless SSH
MD5 to SHA-256 Host Key Conversion
As part of the SSH-based agentless connections that enable certificate provisioning/validation and SSH key discovery/management, Trust Protection Platform provides the ability to manage and configure trust of SSH host keys. Beginning in 17.1, trusted SSH host keys are stored using SHA-256 instead of MD5. Following an upgrade to 17.1 or later, this change may impact host key trust during the first connection on each device object on which you are enforcing host key trust. If you are enforcing host key trust on device objects in Trust Protection Platform for SSH agentless connections, please read the following KB article: MD5 to SHA-256 Host Key Conversion.
Click here for the latest KB listing deprecated functionality in the current and past versions of Trust Protection Platform.
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.