Define a custom encryption rule

  • Release version: Xanadu
  • Updated August 1, 2024
  • 3 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 Define a custom encryption rule

    Custom encryption rules enable you to identify, interpret, and encrypt sensitive information within HTTP requests before they reach your ServiceNow instance. These rules run on the Edge Encryption proxy server and map request fields to table-field names in your instance, ensuring sensitive data is encrypted according to configured policies.

    Show full answer Show less

    When to Use Custom Encryption Rules

    ServiceNow’s Edge Encryption plugin comes with predefined encryption rules that cover many standard use cases, such as editing list fields, updating records, and handling web service or REST API data. Custom encryption rules are necessary when your scripts or applications generate data requiring encryption that is not covered by these defaults. This includes cases like scripted processors, scripted web services, REST APIs, UIs, or AJAX scripts.

    Structure and Execution of Encryption Rules

    • Condition: Defines when the rule applies, based on the request type.
    • Action: Maps and encrypts fields from the request to instance table fields with encryption enabled.
    • Order: Determines the priority of the rule; rules execute from lowest to highest order, with only the first matching rule running.

    The Edge Encryption proxy evaluates rules in priority order and applies the action of the first rule whose condition is true. To avoid unintended processing, encryption rule conditions should be specific. Generic conditions should have higher order values to allow more specific rules to evaluate first.

    Best Practices for Creating Encryption Rules

    • Keep rules focused on specific use cases rather than combining multiple cases; split complex rules into multiple simpler ones.
    • Create separate rules for different tables or record producers to improve validation efficiency.
    • Minimize the number of conditional blocks (e.g., if statements) to reduce processing delays; use array lookups or combined conditions where possible.
    • Be aware that multiple simpler rules require more maintenance but perform better than fewer complex rules.

    Encryption Rule APIs and Limitations

    Encryption rules are written in JavaScript using Edge Encryption APIs, which provide XPath-like expressions to parse JSON and XML request bodies efficiently during streaming. This streaming approach ensures network performance but requires that the entire request be processed in a single pass to avoid errors.

    Note that Glide APIs, script includes, business rules, global variables (e.g., current), allow list manager APIs, and scoped application APIs cannot be used within encryption rules due to their execution context.

    Error Handling and Preparation

    If an encryption rule fails or throws an exception, review the proxy logs for detailed troubleshooting. Before creating a custom rule, carefully inspect the client request format entering the Edge Encryption proxy to accurately define conditions and actions.

    Practical Outcome for ServiceNow Customers

    By defining custom encryption rules, you gain granular control over how sensitive data is encrypted in HTTP requests specific to your custom applications and integrations. This enhances data security while ensuring compliance with encryption policies without impacting standard platform operations. Properly designed rules improve processing efficiency and reduce the risk of misapplied encryption.

    It may be necessary to identify and encrypt sensitive information in HTTP requests on the way to your instance. You can write encryption rules to identify, interpret, and encrypt data in such requests, mapping fields in the request to table-field names on your instance.

    What is an encryption rule

    Encryption rules are scripts executed on the Edge Encryption proxy server to map fields in a request to fields in a table on your ServiceNow instance. An encryption rule tells the Edge Encryption proxy server how to encrypt data in custom payloads.
    Note:
    Encryption rules only support ECMAScript 3 and below.

    When to use custom rules

    A set of encryption rules is included as part of the Edge Encryption plugin. These rules handle many core platform use cases, such as:

    • Editing a field from the list edit form
    • Updating a record from the record form
    • Managing direct web service
    • Processing data from the REST Application Program Interface (API)

    Applications created using standard forms and lists should work without custom encryption rules.

    If you develop scripts that contain data that should be encrypted, create encryption rules to find and map that data to Glide table-field names. For example:

    • Scripted processors
    • Scripted web services
    • Scripted REST APIs, UIs, or Ajax scripts

    Format of an encryption rule

    Rules include three parts:
    • Condition: Identifies the type of request.
    • Action: Maps fields in the request to fields in a table, encrypting values that map to fields with encryption configurations defined.
    • Order: Priority of the rule. The lowest priority rule with a satisfied condition is the only rule that runs. Like business rules, rules run from lowest to highest.

    Except for attachment requests, HTTP requests are evaluated by the Edge Encryption proxy server. The Edge Encryption proxy server evaluates all encryption rule conditions in priority order until either all conditions return false, or one condition returns true. When a condition returns true, the action is executed on the request, and the result is forwarded to the instance. No other conditions are evaluated. As a result, encryption rule conditions should be as specific as possible. A generic rule might evaluate as true for a request meant to be processed by another rule, causing the request to be processed by the wrong action. If a generic condition is unavoidable, the rule should be marked with a high-order value so that more specific rules are evaluated first.

    Guidelines for creating encryption rules

    Creating efficient, optimized encryption rules can reduce processing time for script validation.

    Overall guideline: When rules get long, do your best to minimize the number of blocks and break the rules apart whenever possible. Ideally, custom rules should apply to specific use cases, rather than encompassing several cases, with ifs or switch statements in the action script.

    1. Split rules whenever possible. For example,
      • Create different rules for different tables and ensure that each rule runs only on its respective table.
      • Create different rules for each record producer that you’re targeting, or at least for each subset of record producers. Instead of one rule targeting dozens of sys_ids, you could create several different rules targeting smaller subsets of record producers, or even create one rule per sys_id.
        Note:
        Creating multiple rules requires more maintenance. The trade-off is that multiple, simpler rules can be validated more efficiently than longer, more complex rules.
    2. Minimize the number of blocks. Because the processing engine scans each block while evaluating scripts, a large number of blocks causes delays in validation. For example,
      • Replace all if blocks with an array lookup, and replace all blocks in the array lookup with just one if block.
      • Combine if blocks whenever it’s possible to group them.

    Encryption rule APIs

    Encryption rules are written in JavaScript and utilize Edge Encryption APIs to locate and encrypt sensitive information in the body of a request. The API uses expressions similar to xPath to navigate through both JSON and XML content.

    Edge Encryption APIs process the request off the stream as it is being written to the output stream. Stream parsing enables encryption rules to be network performant. However, fetching and parsing content from the body multiple times could lead to unexpected results. To void this potential problem, requests should be processed by the action in a single pass.

    When creating encryption rules, you can’t use Glide APIs, script includes, business rules, or any global parameters such as current. Because the rules are created for HTTP objects, a global request object is available.

    When creating encryption rules, you can’t use APIs from the allow list manager or scoped applications.

    Error handling

    If an encryption rule condition or action throws an exception, check the proxy log for troubleshooting information.