Masking Gateway Log File Elements

This section provides and overview of masking gateway log file elements and discusses how to:

  • Access the logfilter.properties file.

  • Mask elements not contained in namespaces.

  • Mask elements contained in namespaces.

  • Mask attributes of elements.

  • Mask child element names.

  • Change the global mask message.

  • Create custom mask messages.

  • Disable gateway log masks.

You can mask, or hide, elements that appear in the integration gateway log files, thereby prohibiting sensitive information from displaying in the generated logs.

Note: The system applies gateway log masks and messages to both the integration gateway message log file (MsgLog.html) and the integration gateway error log file (ErrorLog.html).

Global and Custom Mask Messages

By default, all masked elements have a global mask message applied to them, whereby every element you mask is replaced with a standardized message. You can also create custom mask messages for specific elements. You can use a combination of global and custom mask messages.

The default global mask message is *** deleted for security purposes ***. You can change the global mask as you wish to a message that best suits your business needs.

Default Masks

Several gateway log masks are implemented by default. They include, but are not limited to, the following elements:

  • WSSE password.

  • NodePassword.

  • ExternalUserPassword.

  • XML format request with password.

  • PSFT AuthToken.

  • SAML-TokenData.

You can disable any of these masks in the logfilter.properties file.

logfilter.properties File

To mask and unmask gateway log file elements use the logfilter.properties file.

To use the file to specify the element names, attribute names, and element namespaces to mask. You can also use the file to change the global mask message and set up custom mask messages.

Note: After you make any changes to the logfilter.properties file, you must reboot the webserver for the changes to take effect.

Property Types

The following table lists the property types with which you can work in the logfilter.properties file:

Note: The examples provided in this section show property names appended with a number. These numbers are property indexes and are discussed elsewhere in this section.

Property

Description

AttributeName

Set this property equal to an attribute of an element to mask.

ElementName

Set this property equal to an element name to mask.

IsLeaf

Use this property to mask an element and all child tags of the element.

Namesapace

Use the Namespace property in conjunction with the ElementName property to specify the namespace of the element to mask.

Property Indexes

All properties in the logfilter.properties file are appended with an index number. Indexes group related properties and their values. The following example shows an excerpt from the logfilter.properties file and the ElementName.<index_number> naming scheme. 

#IBInfo NodePassword
ElementName.2=NodePassword

#IBInfo ExternalUserPassword
ElementName.3=ExternalUserPassword

#XML format request with Password
ElementName.4=Password

You can use any number as an index number. Index numbers do not have to be used in sequence. Using the previous example, if you were to add a new element name to the file, you would not have to name it ElementName.5. You could use any number not already in use, such as ElementName.72.

Properties can appear in any order in the logfilter.properties file and do not have to appear in sequential index order. As an example, ElementName.72 could appear first in the file, followed by ElementName.3, followed by ElementName.1, followed by ElementName.12, and so on.

Mask Variables

PeopleSoft Integration Broker provides the following mask variables:

Mask Variable

Description

GlobalReplaceWith

By default the system assigns the value of this variable to all asked elements.

The default global mask message is:

***deleted for security purposes***

ReplaceWith

Use this variable to override the global mask value for a specific element and set a custom mask message.

The logfilter.properties file is located in the following path in the PeopleSoft home directory:

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\
WEB-INF\logfilter.properties

Use the ElementName property to mask an element name that is not contained in a namespace.

To mask an element name that is not contained in a namespace, enter the element name to mask in logfilter.properties file in the following format:

ElementName.<index_number>=<Element_to_mask>

Be sure to specify a unique index number.

An example of a mask for an element name is shown in the following example. 

ElementName.1=NodePassword

If you are using the default global mask, the element appears as follows in the gateway log files:

<NodePassword>*** deleted for security purposes ***</NodePassword>

Use the ElementName property and the Namespace property to mask elements contained within namespaces.

To mask an element name contain within a namespace, enter the element name to mask and namespace in which it is contained in the logfilter.properties file in the following format:

ElementName.<index_number>=<Element_to_mask>
Namespace.<index_number>=<Namespace_that_contains_element>

The ElementName and Namespace properties must use the same unique index number.

The following example shows how to enter a mask for the Username element contained in a namespace:

ElementName.9=Username
Namespace.9=http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-secext-1.0.xsd

If you are using the default global mask, the element appears as follows in the gateway log files:

<Username>*** deleted for security purposes ***</Username>

Use the ElementName property and the AttributeName property to mask an attribute of an element.

To mask an attribute of an element, enter the element name and attribute name in the logfilter.properties file in the following format:

ElementName.<index_number>=<Element_name>
AttributeName.<index_number>=<Attribute_of_element_to_mask>

The ElementName and AttributeName properties must share the same unique index number.

The following example show the default mask for the password from the requesting node of a PeopleSoft 8.1x system:

#8.1x from node password
ElementName.6=from
AttributeName.6=password

An example request before masking is:

<?xml version="1.0"?>
<request version="1.0">
    <from node="PSFT_HR" password="my_password"/>
    <to node="QE_LOCAL"/>

When the mask is applied, the request looks as follows:

<?xml version="1.0"?>
<request version="1.0">
    <from node="PSFT_HR" password="*** Deleted for security purposes ***"/>
    <to node="QE_LOCAL"/>

Use and set the IsLeaf property equal to false to mask an element and all child elements. By default, child tags are not masked.

To mask an element and all child elements, enter the element name and set the IsLeaf property in the logfilter.properties file in the following format:

ElementName.<index_number>=<Element_name_(and_child_elements)_to_mask>
IsLeaf.<index_number>=false

The ElementName and IsLeaf properties must use the same unique index number.

As an example an address element could contain street number, street name, city, state, and zip code tags, as shown in the following example:

<address>
  <streetnumber>4433</streetnumber>
  <street>Oracle Lane</street>
  <city>Pleasanton</city>
  <state>California></state>
  <zipcode>94588</zipcode>
</address>

The following example shows how to mask the address element and all children of the element:

ElementName.11=address
IsLeaf.11=false

If you are using the default global mask, the element appears as follows in the gateway log files:

<address>***deleted for security purposes***</address>

However, if you wanted to mask just one of the child elements such as zip code, you would do so as shown in the following example:

ElementName.11=zipcode

The following example shows how the zip code tag would appear in the gateway logs if using the default global mask:

<address>
  <streetnumber>4433</streetnumber>
  <street>Oracle Lane</street>
  <city>Pleasanton</city>
  <state>California></state>
  <zipcode>***deleted for security purposes***</zipcode>
</address>

The value of the GlobalReplaceWith variable located in the logfilter.properties file determines the default global mask message. The default value is:

GlobalReplaceWith=***deleted for security purposes***

You can change this value as necessary to suit your business needs by setting the GlobalReplaceWith variable equal to another value. For example:

GlobalReplaceWith=####  PeopleSoft Confidential Information  ####

You can override the global mask message on an element-by-element basis by setting the RepalceWith variable equal to a custom mask message.

The format is:

ElementName.<index.number>=<Element_to_mask>
ReplaceWith.<index_number>=<Custom_mask_message>

The index number you set must be the same unique index number used for the element, namespace, and/or attribute entry.

The following code snippet shows an example of overriding the default global mask message with a custom message:

#PSFT AuthToken
ElementName.7=AuthToken
ReplaceWith.7=-->Proprietary Information<--

When the gateway logs are generated the mask for this element will look as follows:

<AuthToken>-->Proprietary Information<--</AuthToken>

The following code example was shown earlier in this section. It has been modified to show how to override the default global mask message with a custom message:

ElementName.9=Username
Namespace.9=http://docs.oasis-open.org/wss/2004/01/
  oasis-200401-wss-wssecurity-secext-1.0.xsd
ReplaceWith.9=**  Data removed per company security policy **

When the gateway logs are generated the mask for this element will appear as follows:

<Username>**  Data removed per company security policy **</Username>

You can disable a mask for any element by commenting out the mask data in the logfilter.properties file.

For example, the following sample mask entry could appear in the logfilter.properties file:

#Sample Mask Entry
ElementName.44=NodeName
Namespace.44=http://my_namespace.xsd
ReplaceWith.44=--->Confidential/Proprietary Information<---

To disable the entry comment out all lines as shown in the following example:

#Sample Mask Entry
#ElementName.44=NodeName
#Namespace.44=http://my_namespace.xsd
#ReplaceWith.44=--->Confidential/Proprietary Information<---