Upgrading Edge Encryption

  • Release version: Yokohama
  • Updated January 30, 2025
  • 6 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Upgrading Edge Encryption

    Upgrading ServiceNow Edge Encryption involves careful management of both instance and proxy server upgrades to ensure continuous functionality and security. The Yokohama release introduces specific guidelines and requirements to minimize disruption and maintain encryption controls.

    Show full answer Show less

    Instance Upgrades

    During instance upgrades, do not modify any Edge Encryption configurations, rules, tokenization patterns, scheduled jobs, key configurations, denylist IP configurations, or scheduled upgrades. Scheduled jobs running during the upgrade will be interrupted but can be resumed without data loss once the upgrade completes.

    Proxy Server Upgrades

    Proxy servers can be upgraded either via a scheduled upgrade initiated by the instance or manually through command line on Linux or Windows. Scheduled upgrades minimize downtime and automatically preserve critical files such as keys, keystores, and certificates by copying them to a new proxy directory. However, customized files outside the standard configuration are not preserved.

    Important Considerations for Proxy Upgrades

    • Windows upgrades may fail if files in the installation directory are open or if command shells are active in that directory.
    • Third-party libraries like Gemalto must be installed outside the Edge Encryption directory and configured via properties files to prevent loss during upgrades.
    • JAVAHOME must point to an external Java installation (version 1.8u144 or higher for older versions, or Java 17.0.3+ for Yokohama and later).
    • The temporary directory setting (-Djava.io.tmpdir) must be outside the proxy directory with appropriate permissions.

    Scheduled Proxy Upgrades

    Scheduled upgrades check for new proxy versions aligned with the instance version to reduce compatibility issues. Only users with the securityadmin role can schedule these upgrades. The proxy server is offline briefly during the upgrade for restart, and upgrade logs are stored in the original proxy directory for troubleshooting.

    Troubleshooting and Rollback

    If a scheduled proxy upgrade fails, the proxy reverts to the previous version automatically, preserving all data, keys, and configurations. Administrators should review failure reasons and log files before deleting old proxy directories. Repeated failures may require manual upgrade attempts or contacting ServiceNow Support.

    Java Requirements and Encryption

    Java 17.0.3 or later is required for Edge Encryption proxies on the Yokohama release. Java 11 is no longer supported. For AES 256-bit encryption on Java 8u141 or lower, the Java Cryptography Extension (JCE) policy files must be installed prior to upgrading.

    Mixed Proxy-Version Environments

    Running proxies from different patch levels within the same release family is supported but not recommended due to potential inconsistent behavior and security gaps. ServiceNow advises keeping proxy servers updated to the latest supported version aligned with the instance release.

    Practical Actions for ServiceNow Customers

    • Plan instance upgrades carefully, avoiding changes to Edge Encryption settings during the process.
    • Schedule proxy upgrades to align with instance upgrades, ensuring minimal downtime and compatibility.
    • Verify Java environment variables and third-party library locations before upgrading proxies.
    • Monitor proxy build status via the Edge Encryption Configuration interface to identify outdated proxies promptly.
    • Use manual upgrade procedures if scheduled upgrades fail repeatedly.
    • Maintain backup and review upgrade logs in case rollback or troubleshooting is needed.

    Both instance upgrades and proxy server upgrades require special consideration in an Edge Encryption environment.

    Instance upgrades

    Instance upgrades in an Edge Encryption environment require caution to ensure that Edge controls work properly after the instance upgrade.

    During an instance upgrade, you should not add, edit, or delete the following:
    • Edge Encryption configurations
    • Edge Encryption rules
    • Edge Encryption tokenization patterns
    • Edge Encryption scheduled jobs
    • Edge Encryption key configurations
    • Edge Encryption scheduled upgrades
    • Edge Encryption denylist IP configurations

    Any scheduled job running during the instance upgrade will not complete. To complete the interrupted job, rerun the job once the instance is upgraded. When you reschedule the job, the processing that occurred before the instance upgrade is not lost, and the job continues to process only the data that has not yet been processed.

    Proxy server upgrades

    Schedule a proxy upgrade to enable the instance to upgrade the Edge Encryption proxy server, or manually upgrade the proxy server at any time.
    Warning:
    For an upgrade on Windows, you may encounter file lock issues and the upgrade may fail. For the upgrade to succeed, you should not have any files open under the installation directory. Also, there should be no existing shell in the installation directory. In particular, if you start the proxy from the command line (via bin\edgeencryption.bat install/start) while in the installation directory, you should close that shell or move it out of the installation directory afterward. No files under the installation directory should be opened by an editor or by any other application.

    Third party libraries

    Third party libraries, such as Gemalto, are lost during instance and proxy server upgrades if they are kept in the same directory. You can perform the following to prevent the loss of third party libraries during upgrades:
    1. Manually add the following property to edgeencryption.properties:

      edgeencryption.ekm.provider.classname = com.snc.edgeencryption.encryption.CloudEdgeNaeKeyProvider

    2. Add the edgeencryption.thirdparty.vendor.library.path vendor library location property and set it to /path/to/jars.

      For example:

      edgeencryption.thirdparty.vendor.library.path = /app/servicenow/libs

    3. Copy the SafeNet JARs into that path.

    After you install the third party libraries outside of the Edge Encryption installation, they are no longer lost during upgrades.

    Scheduled upgrades

    Important:
    During ServiceNow Instance upgrades, also upgrade your proxy server version to align with your Instance version and reduce the chance of compatibility issues.
    Schedule an upgrade to allow the instance to upgrade the proxy server at the scheduled time. This functionality is available by default after upgrading. A scheduled upgrade includes these events:
    1. The proxy server checks with the instance to see if there is a new version available for upgrade. New versions generally become available when the instance is upgraded.
    2. The administrator receives a notification upon logging in when a new version of the proxy server is available.
    3. The administrator can Schedule an Edge Encryption proxy server upgrade for each proxy server.
      Note:
      Only users with the security_admin role can create an upgrade schedule through the proxy server.
    4. Once the upgrade is scheduled, the proxy server automatically upgrades at the scheduled time. During the upgrade, the proxy server is offline for only a short time.
      Note:
      Because the proxy server restarts during the upgrade, it is offline for a short time. The amount of time is determined by your environment and how long it takes to stop and restart the proxy service.
    5. During the scheduled upgrade, a new proxy directory is created and your configuration files are copied to the new directory. New properties are written to your existing properties file. The following files or directories in your old proxy directory are copied to the new proxy directory.
      • /conf directory
      • /keys directory
      • /keystore directory
      • java/jre/lib/security/cacerts file
      As a result, your keys, keystores, settings, and certificates are preserved.
      Note:
      Only the above files are copied to the new proxy directory. Any other customized files in the proxy server directory are not preserved during a scheduled upgrade. The upgrade log file can be found in the original proxy directory in the following folder: <original-proxy-directory>/tmp/upgrade-wrapper/bin.

    Prerequisites for scheduled upgrades

    Before scheduling an upgrade for an Edge Encryption proxy, ensure the following:
    1. The JAVA_HOME environment variable points to a java installation on the machine that is outside the Edge Encryption proxy’s directory structure.
    2. The JAVA_HOME environment variable points to a java installation that is at version 1.8_u144 or higher.
    3. The -Djava.io.tmpdir parameter in the wrapper.conf file of the Edge Encryption proxy points to a directory that is OUTSIDE the Edge Encryption proxy’s directory structure, and the proxy has read/write/execute permissions on the directory. Optionally, you could comment out the parameter entirely so that Java uses its default tmp location.

    Manual upgrades

    Instead of creating an upgrade schedule, you can manually upgrade each proxy server through the command line. See Manually upgrade an Edge Encryption proxy server running on Linux or Manually upgrade an Edge Encryption proxy server running on Windows.

    Proxy build status

    You can easily identify whether a proxy server is out of date by navigating to Edge Encryption Configuration > Proxies > All. The status of your proxy build is indicated in the Proxy build column by the following colors:

    Green
    Your proxy server is up-to-date.
    Yellow
    Your proxy server is out-of-date and an upgrade is needed.
    Orange
    Upgrade failed. Your proxy server reverts to the old version to ensure that there is no downtime.

    Troubleshoot a failed scheduled proxy upgrade

    When a scheduled proxy upgrade fails, the proxy server reverts to the version you are upgrading from. All original data, keys, and configuration files are preserved. This process may take several minutes. Contact Customer Service and Support to ensure a successful upgrade.

    To determine the reason for the failure, you can check the Failure Reason in the upgrade schedule. In addition, the installation directory for the failed upgrade is maintained so that log files are available for troubleshooting.
    Note:
    Before deleting any extra proxy directories, always confirm which directory is current by reviewing the log files. If the log files have recent activity, the proxy might be connected to your instance.

    If a scheduled proxy upgrade fails repeatedly, you can manually upgrade your proxy server. See Manually upgrade an Edge Encryption proxy server running on Linux and Manually upgrade an Edge Encryption proxy server running on Windows.

    Java minimum requirements

    The host machine installing or running the Edge Encryption proxy server must maintain a supported version of Java. Current supported versions are Java 17.0.3 or later in the 17.x version series.
    Note:
    Java 11 is no longer be supported as of the Yokohama release. Upgrade your environment with the Edge Encryption proxy to Java 17 before you attempt to install Yokohama or later versions of the Edge Encryption proxy.

    If using AES 256-bit encryption with Java 8 update 141 (8u141) or lower, you must install the Java Cryptography Extension (JCE) jurisdiction policy files by copying them into the system Java home directory of each Edge Encryption proxy server host. Add these files to the <Java-home-directory>/jre/lib/security folder before performing a scheduled or manual upgrade. To install the AES 256-bit encryption policy files, see Configure the AES 256-bit encryption key.

    Mixed proxy-version environments

    Although an environment running old versions of the proxy server with up-to-date versions of the proxy server is not recommended, it is supported if all proxy servers are within the same version family as your instance. For example, if you have an instance on the Yokohama release, your environment supports proxy servers from any Yokohama patch or hot fix. However, the following limitations apply.

    • If one proxy server supports functionality that another proxy does not support, you will see inconsistent behavior, depending on which proxy server is used.
    • If a proxy server is out-of-date, it may not include recent security enhancements.

    If a proxy server from a previous release is registered with a newer release of the instance, you will receive regular notifications that the proxy server is out-of-date. To ensure an optimal and secure environment, ServiceNow recommends always upgrading your proxy server to the most recent version of the software supported by your instance.