WebSphere DataPower SOA Appliances

WebSphere DataPower SOA Appliances Version 3.7.3 Web Application Firewall Developers Guide

WebSphere DataPower SOA Appliances Version 3.7.3 Web Application Firewall Developers Guide

Note Before using this information and the product it supports, read the information in Notices and trademarks on page 163. First Edition (May 2009) This edition applies to version 3, release 7, modification 3 of IBM WebSphere DataPower SOA Appliances and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 2002, 2009. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Preface............... v Who should read this document........ v How this document is organized....... v Publications.............. vi Installation and upgrade documentation.... vi Administration documentation....... vi Development documentation....... vii Reference documentation......... vii Integration documentation........ vii Problem determination documentation.... viii Supplemental documentation....... viii File naming guidelines.......... viii Object naming guidelines.......... ix Typeface conventions........... ix Chapter 1. WebGUI basics....... 1 Objects on the appliance.......... 1 Working with objects........... 1 Accessing the WebGUI........... 1 Welcome screen............. 1 Common WebGUI conventions........ 2 Working with referenced objects....... 2 Working with lists of referenced objects.... 3 Viewing and editing local files during configuration 3 Viewing local files........... 4 Editing local files............ 4 Common WebGUI tasks.......... 4 Applying and saving changes....... 4 Canceling changes........... 4 Resetting objects............ 5 Deleting objects............ 5 Exporting objects............ 5 Viewing object-specific logs........ 5 Viewing object status.......... 6 Cloning services............ 6 Accessing probe captures......... 7 Chapter 2. Securing communication.. 9 Supported cryptographic formats....... 9 Working with keys and certificates....... 9 Creating key-certificate pairs........ 9 Generating keys and certificates...... 10 Exporting keys and certificates....... 11 Importing keys and certificates....... 12 Defining Certificate objects......... 13 Defining Firewall Credentials objects...... 14 Defining Identification Credentials objects.... 15 Defining Key objects........... 16 Defining Profile objects.......... 17 Defining Shared Secret Key objects...... 18 Defining SSL Proxy Profile objects....... 19 Creating a forward (or client) proxy..... 19 Creating a reverse (or server) proxy..... 19 Creating a two-way proxy........ 20 Working with Validation Credentials objects... 21 Creating for non-expiring, non-passwordprotected certificates.......... 21 Creating for select certificates....... 21 Chapter 3. Configuring Web Application Firewall services.......... 25 Scenarios............... 25 Scenario one: College enrollment form.... 25 Scenario two: Benefits management site.... 26 Scenario three: Trading site........ 26 Configuring a Web Application Firewall..... 27 General configuration.......... 27 Timeout/Protocol........... 29 Configuring an Application Security Policy.... 30 General configuration.......... 30 Request Maps............ 30 Response Maps............ 31 Error Maps............. 31 Chapter 4. Managing files....... 33 Directories on the appliance......... 33 Launching the File Management utility..... 35 Displaying directory contents........ 35 Creating a subdirectory.......... 35 Deleting a directory........... 36 Refreshing directory contents........ 36 Uploading files from the workstation...... 36 Working with Java Key Stores........ 37 Required software........... 37 Granting permissions.......... 37 Types of key stores........... 37 Uploading a file from a Java Key Store.... 37 Fetching files.............. 38 Copying files.............. 38 Renaming files............. 39 Moving files.............. 39 Viewing files.............. 40 Editing files.............. 40 Deleting files.............. 40 Chapter 5. Managing the configuration of the appliance........... 41 Creating Include Configuration File objects.... 41 Creating Import Configuration File objects.... 42 Backing up and exporting configuration data... 43 Backing up the entire appliance...... 44 Backing up domains.......... 44 Exporting select objects......... 45 Copying or moving select objects...... 47 Managing configuration checkpoints...... 48 Defining number configuration checkpoints to allow............... 48 Saving configuration checkpoints...... 49 Listing configuration checkpoints...... 49 Rolling back to a configuration checkpoint... 50 Copyright IBM Corp. 2002, 2009 iii

Deleting configuration checkpoints..... 50 Importing configuration data........ 50 Managing changes in configuration data..... 52 Comparing configurations........ 52 Reading the change report........ 53 Reverting changes........... 53 Configuring deployment policies....... 54 Creating a Deployment Policy object..... 54 Using the deployment policy builder..... 55 Specifying the matching statement...... 56 Appendix A. Referenced objects.... 57 AAA Policy.............. 57 Main tab.............. 57 Identity tab............. 60 Authenticate tab............ 62 Map Credentials tab.......... 68 Resource tab............. 69 Map Resource tab........... 70 Authorize tab............. 71 Post Processing tab........... 77 Namespace Mapping tab......... 80 SAML Attributes tab.......... 81 LTPA Attributes tab........... 81 Transaction Priority tab......... 82 Setting namespace mappings (XPath bindings). 82 Defining SAML attributes........ 82 Adding LTPA user attributes....... 83 Using an AAA Info file......... 83 IBM Tivoli Access Manager........ 88 IBM Tivoli Federated Identity Manager.... 90 Working with Kerberos objects....... 92 XACML Policy Decision Point....... 95 Application Security Policy......... 97 Request Maps tab........... 98 Response Maps tab........... 98 Error Maps tab............ 99 Count Monitor............. 99 Error Policy.............. 99 Defining an LDAP Search Parameters object... 100 Load Balancer Group........... 101 Health of member servers........ 101 Setting the health state with a variable.... 102 Configuring Load Balancer Group objects... 102 Matching Rule............. 106 Name-Value Profile........... 108 Validation List tab........... 110 Processing Rule............. 111 Rate Limiter.............. 112 Session Management Policy........ 113 URL Rewrite Policy........... 114 URL Rewrite Rule tab......... 114 User Agent.............. 117 Proxy Policy............. 118 SSL Proxy Profile........... 118 Basic HTTP Authentication........ 119 SOAP Action Policy.......... 120 Public Key Authentication Policy...... 120 Allow Compression Policy........ 121 Restrict to HTTP 1.0 Policy........ 122 Inject Header Policy.......... 122 Chunked Uploads Policy........ 123 FTP Client Policies.......... 124 Web Application Firewall......... 127 Proxy Settings tab........... 129 HTTP Options tab........... 130 Source Addresses tab.......... 131 Web Request Profile........... 132 Profile tab............. 133 Methods & Versions tab......... 134 Processing tab............ 134 Name Value tab........... 135 Cookie tab............. 136 Multipart Form tab.......... 137 Threat Protection tab.......... 138 Web Response Profile........... 139 Profile tab............. 140 Codes & Versions tab.......... 140 Processing tab............ 140 Name Value tab........... 141 Threat Protection tab.......... 142 XML Manager............. 142 Configure XML Manager objects...... 143 Flushing the document cache....... 143 Flushing the stylesheet cache....... 143 z/os NSS Client............ 144 Creating the z/os NSS Client....... 145 Appendix B. Working with variables 147 Service variables............ 148 General service variables........ 148 Multi-Protocol Gateway and Web Service Proxy service variables........... 148 Configuration services service variables... 149 Load balancer service variables...... 150 Legacy MQ-specific service variables.... 150 Multistep variables.......... 151 Transaction variables........... 152 Asynchronous transaction variables..... 152 Error handling transaction variables..... 153 Headers transaction variables....... 154 Persistent connection transaction variables... 154 Routing transaction variables....... 155 URL-based transaction variables...... 155 Web Services Management transaction variables 156 Extension variables........... 156 System variables............ 158 List of available variables......... 159 Appendix C. Getting help and technical assistance........ 161 Searching knowledge bases......... 161 Getting a fix.............. 161 Contacting IBM Support.......... 162 Notices and trademarks....... 163 Trademarks.............. 163 Index............... 165 iv IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Preface IBM WebSphere DataPower SOA Appliances are purpose-built, easy-to-deploy network appliances that simplify, help secure, and accelerate your XML and Web Services deployments while extending your SOA infrastructure. These appliances offer an innovative, pragmatic approach to harness the power of SOA while simultaneously enabling you to leverage the value of your existing application, security, and networking infrastructure investments. Who should read this document This document is intended for developers who manage the configuration of Web Application Firewall services, objects, and associated referenced objects on the DataPower appliance. Developers should have the following knowledge: v Network architecture and concepts v Internet protocols, including HTTP, TCP/IP v Lightweight Directory Access Protocol (LDAP) and directory services v Authentication and authorization v XML and XSLT Developers should also be familiar with SSL protocol, key exchange (public and private), digital signatures, cryptographic algorithms, and certificate authorities. This document assumes that an Administrator has installed and initially configured the appliance as described in the IBM WebSphere DataPower SOA Appliances: 9003: Installation Guide or in the IBM WebSphere DataPower SOA Appliances: Type 9235: Installation Guide, depending on the model type. How this document is organized This document is organized across the following broad concepts: v Chapter 1, WebGUI basics, on page 1 Provides basic informations about using the DataPower graphical interface, which is referred to as the WebGUI, as well as information about performing common tasks in the WebGUI. v Chapter 2, Securing communication, on page 9 Provide information about securing communication to and from the DataPower appliance. The appliance provide these capabilities with a combination of utilities and objects. v Chapter 3, Configuring Web Application Firewall services, on page 25 Provide detailed information about developing Web Application Firewall services on a DataPower appliance. v Chapter 4, Managing files, on page 33 Provides information about managing files on the appliance. v Chapter 5, Managing the configuration of the appliance, on page 41 Provide information about managing the configuration of application domains and importing and exporting configurations. v Appendix A, Referenced objects, on page 57 Copyright IBM Corp. 2002, 2009 v

Provides detailed information about configuring objects that are referenced while developing services on a DataPower appliance. v Appendix B, Working with variables, on page 147 Provides information about using variables in document processing. v Appendix C, Getting help and technical assistance Provides details about contacting IBM Support. Publications The IBM WebSphere DataPower library is organized into the following categories: v Installation and upgrade documentation v Administration documentation v Development documentation on page vii v Reference documentation on page vii v Integration documentation on page vii v Problem determination documentation on page viii v Supplemental documentation on page viii Installation and upgrade documentation v IBM WebSphere DataPower SOA Appliances: 9003: Installation Guide Provides instructions for installing and powering up the Type 7993 (9003) appliance, creating a startup configuration script, and placing the appliance in operation. v IBM WebSphere DataPower SOA Appliances: Type 9235: Installation Guide Provides instructions for installing and powering up the Type 9235 appliance, creating a startup configuration script, and placing the appliance in operation. v IBM WebSphere DataPower SOA Appliances: Type 9235: Hardware Problem Determination and Service Guide Provides information about diagnosing and troubleshooting hardware problems, ordering consumable replacement parts, and replacing parts. v IBM WebSphere DataPower SOA Appliances: Upgrade and Rollback Guide: Generation 2 Firmware Provides instructions for upgrading Generation 2 firmware and for rolling back firmware upgrades. Administration documentation v IBM WebSphere DataPower SOA Appliances: Appliance Overview Provides an introduction and understanding of the IBM Websphere DataPower SOA appliances. v IBM WebSphere DataPower SOA Appliances: Administrators Guide Provides instructions for using the DataPower GUI for managing user access, network access, appliance configuration and system configuration of the appliance. v IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide A user guide for using a Hardware Security Module (HSM) installed in the appliance. vi IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Development documentation v IBM WebSphere DataPower SOA Appliances: XSL Accelerator Developers Guide Provides instructions for using the WebGUI to configure XSL Proxy and XSL Co-Processor services. v IBM WebSphere DataPower SOA Appliances: XML Firewall Developers Guide Provides instructions for using the WebGUI to configure XML Firewall services. v IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide Provides instructions for using the WebGUI to configure Web Application Firewall services. v IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide Provides instructions for using the WebGUI to configure Multiple-Protocol Gateway services. v IBM WebSphere DataPower SOA Appliances: Web Service Proxy Developers Guide Provides instructions for using the WebGUI to configure Web Service Proxy services. v IBM WebSphere DataPower SOA Appliances: B2B Gateway Developers Guide Provides instructions for using the WebGUI to configure B2B Gateway services. v IBM WebSphere DataPower SOA Appliances: Low Latency Messaging Developers Guide Provides instructions for using the WebGUI to configure a DataPower appliance for low latency messaging. Reference documentation v v Product-specific documentation for using commands from the command line. The documentation is specific to each of the following products. Each document provides an alphabetical listing of all commands with syntactical and functional descriptions. IBM WebSphere DataPower XML Accelerator XA35: Command Reference IBM WebSphere DataPower XML Security Gateway XS40: Command Reference IBM WebSphere DataPower XML Integration Appliance XI50: Command Reference IBM WebSphere DataPower B2B Appliance XB60: Command Reference IBM WebSphere DataPower Low Latency Messaging Appliance XM70: Command Reference IBM WebSphere DataPower SOA Appliances: Extension Elements and Functions Catalog Provides programming information about the usage of DataPower XSLT extension elements and extension functions. Integration documentation The following documents are available for managing the integration of related products that can be associated with the DataPower appliance: v Integrating with ITCAM Provides concepts for integrating the DataPower appliance with IBM Tivoli Composite Application Management for SOA. v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender Preface vii

v Provides concepts for integrating the DataPower appliance with WebSphere Transformer Extender. IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ Explains the concepts and common use patterns for connecting DataPower services to WebSphere MQ systems. Problem determination documentation v IBM WebSphere DataPower SOA Appliances: Problem Determination Guide Provides troubleshooting and debugging tools. Supplemental documentation File naming guidelines v Understanding Web Services Policy Provides conceptual information about how the DataPower appliance can use Web Services Policy (WS-Policy). v Understanding WS-Addressing Provides conceptual information about how the DataPower appliance can use WS-Addressing. v Understanding LTPA Provides conceptual information about how the DataPower appliance can use Lightweight Third Party Authentication. v Understanding SPNEGO Provides conceptual information about how the DataPower appliance can use SPNEGO. v Optimizing through Streaming Provides conceptual information about and procedures for optimizing the DataPower appliance through streaming. v Securing the Last Mile Provides conceptual information about and procedures for understanding the DataPower appliance while securing the last mile. v Configuring the DoD PKI Provides conceptual information about and procedures for configuring the DataPower appliance with Department of Defense Public Key Infrastructure. The maximum length for a file name can be approximately 4128 characters. The name of the base file can be up to 128 characters in length. The base file is the part after the name of the DataPower directory. Examples of directories are local:, store:, and temporary:. If the directory (or domain) supports subdirectories, the path to the file can have a length of 4000 characters. When you create a domain, its name is the base file name in several DataPower directories when viewed from the default domain. The following characters are valid in directory and file names: v a through z v A through Z v 0 through 9 v _ (underscore) viii IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

v v - (dash). (period) Object naming guidelines Typeface conventions Note: Names cannot contain two consecutive periods (..). The object name must be unique in the object namespace. The following characters are valid in when specifying the name for an object: v a through z v A through Z v 0 through 9 v _ (underscore) v - (dash) v. (period) Note: Names cannot contain two consecutive periods (..). The following typeface conventions are used in the documentation: bold Identifies commands, programming keywords, and GUI controls. italics Identifies words and phrases used for emphasis and user-supplied variables. monospaced Identifies user-supplied input or computer output. Preface ix

x IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Chapter 1. WebGUI basics Objects on the appliance Working with objects Accessing the WebGUI Welcome screen The WebGUI is the primary interface for managing the appliance itself and for configuring objects. Objects that can be configured on the appliance range from simple to complex. An object is any entity that you configure on the appliance. During configuration, an object can reference another object that can, in turn, reference another object. For example, the configuration of a service references an instance of the XML Manager object that references an instance of the User Agent object. The flexibility in configuration and association of referenced object allow you to meet your business-processing criteria and security requirements. When configuring services on the appliance, the WebGUI provides an object view and a service view. You can use either view to create or edit the service. Service view Working in the service view allows less-than-expert level users to build basic, generic objects. Object view Working in the object view allows expert-level users to build specific, complex and highly detailed objects. To use the WebGUI, the Web Management Interface must be configured. This interface was defined during the initial firmware setup (during appliance installation) or afterward with the web-mgmt command. To access the WebGUI, use the following procedure: 1. Direct your browser to the WebGUI login screen. Use the IP address and port number assigned during the configuration of the Web Management interface. The address uses the HTTPS protocol and has the https://address:port format. 2. In the login fields, specify an account name and password. 3. From the Domain list, select the domain to which to log in. 4. Click Login. After verifying credentials, the WebGUI displays the Control Panel. After successfully logging in, the WebGUI displays its Welcome screen. Visibility of objects in the WebGUI is controlled by a combination of the Role-based management (RBM) object and whether the administrator is in the default domain or an application domain. Copyright IBM Corp. 2002, 2009 1

This screen is separated into the following areas: v The banner shows details about the administrator who logged in to the appliance and contains the following controls: The Domain list that allows the administrator to switch domains. The Save Config button that allows the administrator to persist configuration changes. The Logout button that allows the administrator to end the WebGUI session. v The navigation bar along the left side provides access to related configuration suites and to related management suites. This area contains the following menus: The Control Panel returns the administrator to the Welcome screen. The Status menu provides access to logs and status providers. The Services menu provides access to service configuration objects and objects referenced by service objects. When the administrator selects the item, the WebGUI displays the service view for the object. The Network menu provide access to network configuration objects. These objects are to define the network in which the appliance connects. Many of these objects are available in the default domain. The Administration menu provides access to managing access to the appliance as well as general appliance settings. Many of these objects are available in the default domain. The Objects menu provides access to service configuration objects and objects referenced by service objects. When the administrator selects the item, the WebGUI displays the object view for the object. v The dashboard that is separated into the following areas: The top area contains icons to access top-level objects for the appliance. The middle area contains icons to access monitoring and troubleshooting utilities. The bottom area contains icons to access file management and administration utilities. When you click any icon on the dashboard or select any item from the menu, the WebGUI replaces the dashboard with the details for the selected item. Common WebGUI conventions In addition to the standard interface controls, the WebGUI uses custom controls to help during the configuration of objects. These controls generally pertain to defining referenced objects. Working with referenced objects When using the WebGUI to create and modify objects, the configuration screen might display an input field to select a referenced object. Figure 1 illustrates this type of input field. Figure 1. Input field for referenced objects When the WebGUI displays this type of input field, you can specify the referenced object in the following ways: v Select the name of an existing referenced object from the list. 2 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

v v Use the + button to create a new referenced object. When created, the input field contains the name of the newly created referenced object. Use the... button to modify the referenced object whose name is in the input field. When modified, the input field retains the name of the referenced object. When you click the + button or... button, the WebGUI launches a new window that displays the configuration screen for that type of object. Working with lists of referenced objects When using the WebGUI to create or modify objects, the configuration screen might display an input list to define a group of referenced objects. The input for this configuration item is the list of referenced objects. Figure 2 illustrates this type of input list. Figure 2. Input list for referenced objects When the WebGUI displays this type of list, you can manage referenced objects in the following ways: v v v v Select the name of an existing referenced object from the list. Click Add to add it to the list of referenced objects. Use the + button to create a new referenced object. When created, the input field contains the name of the new referenced object. Click Add to add it to the list of referenced objects. Use the... button to modify the referenced object whose name is in the input field. When modified, the input field retains the name of the referenced object. Click Add to add it to the list of referenced objects. Select the name of a referenced object from the list (either the input field or the list of referenced objects). Click Delete to remove it from the list of referenced objects. When you click the + button or... button, the WebGUI launches a new window that displays the configuration screen for that type of object. Viewing and editing local files during configuration As you use the WebGUI to select a local file during configuration, the configuration screen might display the View and Edit buttons beside the selection lists. Working with files in this way has the following advantages: v Ensure that the file is the one that you want v Ability to edit the file to address errors found while defining a configuration v Use a single session instead of opening another session to manage files through the File Management utility You cannot view or edit remote files. Chapter 1. WebGUI basics 3

Viewing local files To view a local file, use the following procedure: 1. Select the file from the lists. 2. Click View to open the file editor in view mode. 3. Review the file. 4. Click Cancel. Editing local files The edited file overwrites the original file. Common WebGUI tasks To edit a local file, use the following procedure: 1. Select the file from the lists. 2. Click Edit to open the file editor in edit mode. 3. Edit the file as required. 4. Click Submit to save changes. 5. Click Close. The majority of objects provide the following common tasks. Not all of these tasks are available to all objects. v Applying and saving configuration changes v Canceling changes before saving to the running configuration v Resetting changes to an object v Deleting an object v Exporting the configuration of an object v Viewing object-specific logs v Viewing object status v Cloning a service v Accessing probe captures Applying and saving changes As you use the WebGUI to manage object and service configurations, click Apply to save these changes to the running configuration. Changes that are made to the running configuration take effect immediately, but are not persisted to the startup configuration. During an appliance restart these changes are lost. To retain applied changes across an appliance restart, click Save Config. The changes are saved to the startup configuration. The startup or persistent configuration is persisted across an appliance restart. By default, the appliance reads the startup configuration from the auto-config.cfg file. Canceling changes As you use the WebGUI to manage objects, click Cancel to not save the current changes to the running configuration. If you click Cancel, you return to object catalog and lose all changes. 4 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Resetting objects Independent of whether the settings are saved to the configuration, you can reset an object to its default configuration. Use the following procedure to revert changes to a specific object: 1. Display the catalog for the object. The catalog lists the available instances of this object. 2. Click the name of the object for which to reset to display the configuration screen. 3. Click Undo. 4. Follow the prompts. Deleting objects You might want to delete objects that are no longer needed. If no other object depends on the object to be deleted, you can delete it at any time. Because a DataPower service is a top-level object, you can delete it at any time. Conversely, you cannot delete an object that is active and that is in use by a higher-level object. Use the following procedure to delete an object: 1. Display the catalog for the object. The catalog lists the available instances of this object. 2. Click the name of the object to delete to display the configuration screen. 3. Click Delete. 4. Follow the prompts. Deleting an object deletes that object only. Deleting an object does not delete any referenced object. Exporting objects Use the following procedure to export an object: 1. Display the catalog for the object. The catalog lists the available instances of this object. 2. Click the name of the object to export to display the configuration screen. 3. Click Export. 4. Follow the prompts. Viewing object-specific logs Instead of filtering the log for the default log or a configured log target, you can view log messages that are specific to an object. Viewing log files from the catalog To view object-specific logs from the catalog, use the following procedure: 1. Display the catalog for the object. The catalog lists the available instances of this object. 2. Click the magnifying glass icon. Viewing log files from the configuration screen To view object-specific logs from the configuration screen, click View Logs. Chapter 1. WebGUI basics 5

Viewing object status You can view the status of an object and all its referenced objects to help determine why a configuration object is in a down state. When you view the object status, the WebGUI opens a new window. This window provides the ability to show or hide unused properties. v v To show the unused properties, click Show. If the display lists unused properties, click Hide to hide these properties. Hiding unused properties is the default behavior. When viewing the object status, the window provides the following information: v The name of the instance and its type with a control to collapse (hide) or expand (show) referenced objects v Its configuration state: New, Modified, orsaved v It operational state: up or down v Its administrative state: enabled or disabled v Details about the detected error, if applicable v A link (magnifying glass icon) to view the logs for this object Use the following procedure to view the status for an object: 1. Display the catalog for the object. The catalog lists the available instances of this object. 2. Click the name of the object to view to display the configuration screen. 3. Click View Status. Cloning services You might want to create a service that is similar to an existing service. For example, you need two equivalent services, but each service communicates with a different remote server. In these cases, you can create a clone of an existing service and edit the clone. The cloning process can expedite the creation of a similar service. Use the following procedure to clone a server: 1. Display the catalog for the service. The catalog lists the available instances of this service. 2. Click the name of the service to clone to display the configuration screen. 3. Click Clone. 4. When the screen refreshes, specify the name of the clone. 5. Specify the Ethernet interface that the service monitors for incoming client requests in the Device Address field. Use the default address (0.0.0.0) to specify all interfaces. 6. Specify the Ethernet port that the service monitors for incoming client requests in the Device Port field. 7. As necessary, edit the other properties. 8. Click Apply to save the object to the running configuration. 9. Optionally, click Save Config to save the object to the startup configuration. 6 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Accessing probe captures After enabling the probe, defining the triggers, and sending transactions that match the conditions defined by the triggers, you can view the captured transactions. Use the following procedure to access probe captures: 1. Display the catalog for the service object. The catalog lists the available instances of this object. 2. Click the name of the service for which to view the probe captures to display the configuration screen. 3. Click Show Probe. 4. Click the magnifying glass icon to view details about that captured transactions. For complete details about using the probe, refer to the IBM WebSphere DataPower SOA Appliances: Problem Determination Guide. Chapter 1. WebGUI basics 7

8 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Chapter 2. Securing communication This chapter provide information about securing communication to and from the DataPower appliance. The appliance provide these capabilities with a combination of utilities and objects. Supported cryptographic formats Private key objects support the following formats: v DER v PEM v PKCS #8 v PKCS #12 Certificate objects support the following formats: v DER v PEM v PKCS #7 v PKCS #12 Neither key objects nor certificate objects directly support JKS or KDB formats. Working with keys and certificates The DataPower appliance provides actions that allow you to work with keys and certificates. With the provided cryptographic tools, you can perform the following actions: v Create key-certificate pairs v Generate keys and certificates v Export keys and certificates v Import keys and certificates Unless you are using an appliance with HSM hardware, you cannot export or import keys. For details about using an HSM-enabled appliance, refer to the IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide. Creating key-certificate pairs When you generate a key, you get a key file and a Certificate Signing Request (CSR) file. The CSR file from the initial key generation is not a signed certificate. Send the CSR to a Certificate Authority (CA), such as VeriSign. The CA signs the CSR and returns it to you, which effectively creates the certificate. Load this certificate on the box. In other words, use the following procedure to create the key-certificate pair: 1. Use the Crypto Tool to create the key and CSR 2. Store the private key on the box and create a Key object that references it. 3. Send the CSR to VeriSign. Do not store it on the box (except in the temporary: directory). Copyright IBM Corp. 2002, 2009 9

4. VeriSign returns the signed certificate. 5. Store the signed certificate on the box and create a Certificate object that references it. 6. Optionally, create an Identification Credentials object that references the key and certificate objects. When you create the Identification Credentials object, the key-certificate pair is validated to ensure that pair is ready for use. Generating keys and certificates You can generate a private cryptographic key and optionally a self-signed certificate from the Crypto Tools page. The Certificate Signing Request (CSR) needed by a certificate authority (CA) is created by default. If the file is stored in the cert: directory, it cannot be deleted or edited. If a file is stored in the local: directory or in the temporary: directory, it can be deleted and edited. To generate a key, use the following procedure: 1. Select Administration Miscellaneous Crypto Tools to display the Generate Key page. 2. Define the LDAP entry. a. Use the LDAP (reverse) Order of RDNs toggle to indicate whether to create the LDAP entry in reverse RDN order. on Creates the entry in reverse RDN order. off (Default) Create the entry in forward RDN order. b. Optionally specify a country name in the Country Name (C) field. c. Optionally specify a state or province name in the State or Province (ST) field. d. Optionally specify a locality name in the Locality (L) field. e. Optionally specify the name of an organization in the Organization (O) field. f. Optionally specify the name of an organizational unit in the Organizational Unit (OU) field. g. Optionally specify the names of additional organizational units in the Organizational Unit 2 (OU), Organizational Unit 3 (OU), and Organizational Unit 4 (OU) fields. h. Specify a common name in the Common Name (CN) field. 3. Select a key length from the RSA Key Length list. This defaults to 1024. 4. Specify the name of the key file to generate in the File Name field. The value takes the directory:///name form. Leave blank to allow the action to create the name. 5. Specify the number of days that the key is valid in the Validity Period field. 6. Specify a password to access the key file in the Password field. The password must be at least 6 characters in length. 7. Specify a password alias to access the key file in the Password Alias field. 8. Use the Export Private Key toggle to indicate whether the action writes the key file to the temporary: directory. on Writes the key file to the temporary: directory. off (Default) Does not write the key file to the temporary: directory. 10 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

9. Use the Generate Self-Signed Certificate toggle to indicate whether the action creates a self-signed certificate that matches the key. on (Default) Creates a self-signed certificate. off Does not create a self-signed certificate. 10. Use the Export Self-Signed Certificate toggle to indicate whether the action writes the self-signed certificate to the temporary: directory. on (Default) Writes the self-signed certificate to the temporary: directory. off Does not write the self-signed certificate to the temporary: directory. 11. Use the Generate Key and Certificate Objects toggle to indicate whether the action automatically creates the objects from the generated files. on (Default) Creates the objects from the generated files. off Does not create the objects from the generated files. 12. Specify the name for the Key and Certificate objects in the Object Name field. Leave blank to allow the action to generate the names from from the input information (based on the Common Name (CN) or File Name property). 13. Specify the name of an existing Key object in the Using Existing Key Object field. If supplied and valid, the action generates a new certificate and a new Certificate Signing Request (CSR) that is based on the key in the identified Key object. In this case, the appliance does not generate a new key. 14. Click Generate Key to generate a private key and, if requested, a self-signed certificate. A CSR is created automatically. 15. Follow the prompts. The CSR can be submitted to a certificate authority (CA) to receive a certificate that is based on this private key. This action creates the following files and objects: v v v v v Creates the private key file in the cert: directory; for example, cert:///sample-privkey.pem Creates the CSR in the temporary: directory; for example, temporary:/// sample.csr If Generate Self-Signed Certificate is enabled, creates a self-signed certificate in the cert: directory; for example, cert:///sample-sscert.pem If Export Self-Signed Certificate is enabled, creates a copy of the self-signed certificate in the temporary: directory; for example, temporary:///samplesscert.pem If Generate Key and Certificate Objects is enabled, creates a Key object and a Certificate object If the action creates a self-signed certificate, you can use this certificate-key pair for the following purposes: v Establish Identification Credentials v Encrypt or decrypt XML documents Exporting keys and certificates Use the Export Crypto Objects tab of the Crypto Tools screen to export key and certificate objects. Note: If the appliance has HSM hardware, you can export Key objects. For details, refer to IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide. Chapter 2. Securing communication 11

1. Select Administration Miscellaneous Crypto Tools to display the Crypto Tools screen. 2. Click the Export Crypto Object tab. 3. Provide the following information: Object Type Select the type of object to export. Any appliance can export certificates. Devices with HSM hardware can export private keys. Object Name Type the exact name of the object. To view a list of all such objects, select Objects Crypto Objects Cryptographic Certificate (or Key). Output File Name Specify the name of a export package to contain the exported objects. Do not specify a local directory or file extension. The appliance writes the file to the temporary: directory. Encryption Mechanism Select Key-Wrapping-Key. Note: Available when the appliance has HSM hardware to specify the encryption mechanism to export private keys. 4. Click Export Crypto Object to create the export package with the selected object. Use the File Management utility to access the file. Importing keys and certificates Use the Import Crypto Objects tab of the Crypto Tools screen to import key and certificate objects. Objects that are exported from one DataPower appliance can be imported to another appliance. Importing objects, rather than uploading files, eliminates the need to create objects from files. Note: If the appliance has HSM hardware, you can import Key objects. For details, refer to IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide. 1. Select Administration Miscellaneous Crypto Tools to display the Crypto Tools screen. 2. Click the Import Crypto Object tab. 3. Provide the following information: Object Type Select the type of object to import. Any appliance can import certificates. Devices with HSM hardware can import private keys. Object Name Specify the name of the object to create on import. This name must be a unique in the object namespace. Input File Name Use the controls to select the export package. If the file does not reside on the DataPower appliance, click Upload or Fetch to transfer the file. 12 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Defining Certificate objects Password Optionally specify a password for accessing the file. Any entity or agent needing to access the file must supply this password. Password Alias The password can optionally be given an alias, providing a level of indirection and thus additional security. If an alias is established, use the alias instead of the actual password. 4. Click Import Crypto Object. An object with the specified name is created. Otherwise, an error is returned. A Certificate object that provides an added layer of security by supplying a indirect reference (or alias) to a certificate file. The alias provided by the Certificate object is later used in the creation of a Firewall Credentials, an Identification Credentials, or a Validation Credentials. To create and configure a Certificate, use the following procedure: 1. Select Objects Crypto Crypto Certificate. 2. Click Add. 3. Provide the following inputs: Name Specify the name of the object. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. File Name Access a list of files, contained in the cert: or pubcert: file repository, and select the file that contains the certificate referenced by this Certificate object. You can click Upload or Fetch to transfer the file. You can also click Details to display information about the selected certificate file. Password Depending of business security policies, provide one of the following: v If local security policies provide for password-protected keys, specify the password (or a password alias). v If local polices do not support password protection, leave blank. v If key files are protected by a plaintext password, specify the password. Note: Plaintext passwords appear as such in the configuration script. v If key files are protected by an aliased password, specify the alias. The CLI provides a password-map command that uses a locally-generated key to 3DES encrypt a password used to access a private key file. The command maps the encrypted password to a password alias in a password map file. The password map and the locally-generated key are saved to separate files on the appliance. Plaintext passwords are not stored in memory or saved on the appliance. Chapter 2. Securing communication 13

Password Alias Use the toggle to specify if the text entered in the Password field is a plaintext password or a password alias. on Identifies the text as a password alias for an encrypted password. off (Default) Identifies the text as a plaintext password. Ignore Expiration Dates Use these toggle to allow the creation of a certificate prior to its activation date (the NotBefore value in the certificate) or after its expiration date (the NotAfter value in the certificate). off (Default) Prevents the creation of certificates outside of their internal expiration values. on Creates the certificate and places it in the up state. Although the certificate is in the up state, objects that reference the certificate use the internal expiration values. In other words, the certificate itself is in the up state, but Validation Credentials, Firewall Credentials, or Identification Credentials that references the certificate adhere to the internal expiration values. In other words, the certificate itself is in the up state, but Validation Credentials, Firewall Credentials, or Identification Credentials that references the certificate adhere to the internal expiration values. If the certificate is used for a certificate chain validation from a Validation Credentials and the certificate is not valid, validation fails. Similarly, if the certificate is used from an Identification Credentials, the DataPower appliance sends the certificate to the SSL peer for an SSL connection, but the peer can reject the certificate as not valid. 4. Click Apply to save the object to the running configuration and return to the object catalog. 5. Optionally, click Save Config to save the object to the startup configuration. Defining Firewall Credentials objects A Firewall Credentials consists of a list of Key objects and Certificate objects. A Firewall Credentials provides a list of Key objects and Certificate objects. Certificates and keys not referenced in the Firewall Credentials are unavailable. If no Firewall Credentials exist, all keys and certificates stored locally are available. To create a Firewall Credentials, use the following procedure: 1. Select Objects Crypto Crypto Firewall Credentials to display the Crypto Firewall Credentials catalog. 2. Click Add to display the Crypto Firewall Credentials Configuration screen. 3. Provide the following inputs: Name Specify the name of the object. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Private Key Use the list to add Key objects to the Firewall Credentials. Refer to Defining Key objects on page 16 for more information. 14 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Shared Secret Key Use the list to add Shared Secret Key objects to the Firewall Credentials. Refer to Defining Shared Secret Key objects on page 18 for more information. Certificates Use the list to add Certificate objects to the Firewall Credentials. Refer to Defining Certificate objects on page 13 for more information. 4. Click Apply to save the object to the running configuration. 5. Optionally, click Save Config to save the object to the startup configuration. Defining Identification Credentials objects An Identification Credentials consists of a Key object and a Certificate object. An Identification Credentials identifies the matched public key cryptography public and private keys used by an object for SSL authentication. An Identification Credentials can be used in document encryption, document decryption, and digital signature operations. To create an Identification Credentials, use the following procedure: 1. Select Objects Crypto Crypto Identification Credentials to display the Crypto Identification Credentials catalog. 2. Click Add to display the Crypto Identification Credentials Configuration screen. 3. Provide the following inputs: Name Specify the name of the object. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Crypto Key Access a list of all Key objects, and select the Key object for this Identification Credentials. Refer to Defining Key objects on page 16 for more information. Certificate Access a list of all Certificate objects, and select the Certificate object for this Identification Credentials. Refer to Defining Certificate objects on page 13 for more information. Intermediate CA Certificate Intermediate CA certificates might be required when the CA that is signing this certificate is not widely-recognized. If the intermediate CA certificate is also signed by a less recognized CA, an additional intermediate CA certificate might be required for that CA. You can specify as many intermediate certificates as are required. If necessary, use the list of available Certificate objects to establish a verifiable trust-chain. A trust-chain consists of one or more Certification Authority (CA) certificates and provides a linked path from the certificate that is in the Identification Credentials to a CA that is trusted by a remote appliance. The trust chain enables the appliance to authenticate the certificate. 4. Click Apply to save the object to the running configuration. 5. Optionally, click Save Config to save the object to the startup configuration. Chapter 2. Securing communication 15

Defining Key objects A key is an object that provides an added layer of security by supplying a indirect reference (or alias) to a file that contains a private key. The alias provided by the Key object is later used in the creation of a Firewall Credentials object or an Identification Credentials object. To create and configure a Key object, use the following procedure: 1. Select Objects Crypto Crypto Key to display the Crypto Key catalog. 2. Click Add to display the Crypto Key Configuration screen. 3. Provide the following inputs: Name Specify the name of the object. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. File Name Access a list of files (contained in the cert: file repository) and select the file that contains the private key aliased by this Key object. You can click Upload or Fetch to transfer the file. Note: Keys can be retrieved from a Java Key Store residing on the local workstation. Click Java Key Store on the Upload field. Refer to IBM WebSphere DataPower SOA Appliances: Appliance Overview for more information. Password Depending on business security policies, provide one of the following: v v v If local security policies provide for password-protected keys, specify the password (or a password alias). If local polices do not support password protection, leave blank. If key files are protected by a plaintext password, specify the password. Note: Plaintext passwords appear as such in the configuration script. v If key files are protected by an aliased password, specify the alias. The CLI provides a password-map command that uses a locally-generated key to 3DES encrypt a password used to access a private key file. The command maps the encrypted password to a password alias in a password map file. The password map and the locally-generated key are saved to separate files on the appliance. Plaintext passwords are not stored in memory or saved on the appliance. Password Alias Use the toggle to specify if the text entered in the Password field is a plaintext password or a password alias. on Identifies the text as a password alias for an encrypted password. off (Default) Identifies the text as a plaintext password. 4. Click Apply to save the object to the running configuration. 5. Optionally, click Save Config to save the object to the startup configuration. 16 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Defining Profile objects A Profile object identifies a collection of SSL resources that support SSL connections with remote peer appliances. To create and configure a Profile object, use the following procedure: 1. Select Objects Crypto Crypto Profile to display the catalog. 2. Click Add to display the configuration screen. 3. Provide the following inputs: Name Specify the name of the object. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Identification Credentials Select the Identification Credentials to assign to this Profile object, or retain the default value, none, when no Identification Credentials is needed. The Identification Credentials provides the PKI certificate-key pair that will be used to authenticate the appliance during the SSL handshake. Refer to Defining Identification Credentials objects on page 15 for more information. Validation Credentials Select the Validation Credentials for this Profile object, or retain the default value, none, when no Validation Credentials is needed. Refer to Working with Validation Credentials objects on page 21 for more information. Ciphers Use the field to identify the symmetric key-encryption algorithms for this Profile object. Common cipher values are as follows: ALL Includes all cipher suites, except the enull ciphers. DEFAULT Includes all cipher suites, except for the following ciphers and cipher suites: v enull ciphers v Cipher suites that use DH authentication v Cipher suites that contain the RC4, RSA, and SSL version 2 ciphers HIGH Includes all high encryption cipher suites. These ciphers support a key length in excess of 128 bits. MEDIUM Includes all medium encryption cipher suites. These ciphers support a key length of 128 bits. LOW Includes all low encryption cipher suites. These ciphers support a key length of 56 or 64 bits, but exclude EXPORT cipher suites. EXPORT Includes all cipher suites that support a key length of 40 or 56 bits and are eligible for export outside of the United States. Chapter 2. Securing communication 17

For a detailed list of ciphers, refer to the profile command in the product-specific version of the Command Reference. Options Use the check boxes to disable support for SSL versions and variants. By default, SSL Version 2, SSL Version 3, and Transaction Level Security (TLS) Version 1 are enabled. v To disable SSL Versions 2, click Disable-SSLv2. v To disable SSL Version 3, click Disable-SSLv3. v To disable TLS Version 1, click Disable-TLSv1. Send Client CA List Use the toggle to enable the transmission of a Client CA List during the SSL handshake. Note: Transmission of a Client CA List is meaningful only when this Profile object supports a reverse (or server) proxy and when this Profile object has an assigned Validation Credentials. on Enables transmission of a Client CA List. off (Default) Disables transmission of a Client CA List. A Client CA List consists of a listing of the CA certificates in the Validation Credentials for this Profile object. A Client CA List can be sent by an SSL server as part of the request for a client certificate. The Client CA list provides the client with a list of approved CAs whose signatures are acceptable for authentication purposes. Note: SSL servers are not required by the protocol to send a Client CA List. Generally, SSL servers do not send a Client CA list. Some implementations or local policies, however, might mandate the use of Client CA lists. 4. Click Apply to save the object to the running configuration. 5. Optionally, click Save Config to save the object to the startup configuration. Defining Shared Secret Key objects A Shared Secret Key objects provides an added layer of security by supplying an indirect reference (or alias) to a shared secret key. A shared secret key is used by mutual agreement between a sender and receiver for encryption, decryption, and digital signature purposes. To create and configure a Shared Secret Key, use the following procedure: 1. Select Objects Crypto Crypto Shared Secret Key to display the Crypto Shared Secret Key catalog. 2. Click Add to display the Crypto Shared Secret Key Configuration screen. 3. Provide the following inputs: Name Specify the name of the object. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. 18 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

File Name Access a list of files (contained in the cert: file repository) and select the file that contains the shared secret key aliased by this Shared Secret Key. You can click Upload or Fetch to transfer the file. 4. Click Apply to save the object to the running configuration. 5. Optionally, click Save Config to save the object to the startup configuration. Defining SSL Proxy Profile objects An SSL Proxy Profile defines a level of SSL service when operating as an SSL proxy. The SSL proxy has the following modes: forward The SSL proxy acts as an SSL client (or acts in the forward direction). In client proxy mode, SSL is used over the appliance-to-server connection. reverse The SSL proxy acts as an SSL server (or acts in the reverse direction). In server proxy mode, SSL is used over the appliance-to-client connection. two-way The SSL proxy acts as both an SSL client and SSL server (or acts in both directions). In two-way mode, SSL is used over the appliance-to-server connection and the appliance-to-client-connection. Creating a forward (or client) proxy To create a forward SSL Proxy Profile, use the following procedure: 1. Select Objects Crypto SSL Proxy Profile to display the SSL Proxy Profile catalog. 2. Click Add to display the SSL Proxy Profile Configuration screen. 3. Specify the name of the object in the Name field. 4. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. 5. Select Forward from the SSL Direction list. 6. Select the profile that defines SSL service to the backend server from the Forward (Client) Crypto Profile list. 7. Use the Client-side Session Caching toggle to enable or disable client side caching. 8. Click Apply to save the object to the running configuration. 9. Optionally, click Save Config to save the object to the startup configuration. Creating a reverse (or server) proxy To create a reverse SSL Proxy Profile, use the following procedure: 1. Select Objects Crypto SSL Proxy Profile to display the SSL Proxy Profile catalog. 2. Click Add to display the SSL Proxy Profile Configuration screen. 3. Specify the name of the object in the Name field. 4. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. 5. Select Reverse from the SSL Direction list. Chapter 2. Securing communication 19

6. Select the profile that defines SSL service to frontend clients from the Reverse (Server) Crypto Profile list. 7. Use the Server-side Session Caching toggle to enable or disable server side caching. 8. Specify the time that session-specific state data is maintained in the server cache in the Server-side Session Cache Timeout field. 9. Specify the maximum size of the server-side cache in the Server-side Session Cache Size field. 10. Use the Client Authentication is optional toggle to control when SSL client authentication is optional. on Client authentication is not required. When there is no client certificate, the request does not fail. off (Default) Requires client authentication only when the server cryptographic profile has an assigned Validation Credentials. 11. Use the Always Request Client Authentication toggle to control when to request SSL client authentication. on Always requests client authentication. off (Default) Requests client authentication only when the server cryptographic profile has an assigned Validation Credentials. 12. Click Apply to save the object to the running configuration. 13. Optionally, click Save Config to save the object to the startup configuration. Creating a two-way proxy To create an SSL Proxy Profile, use the following procedure: 1. Select Objects Crypto SSL Proxy Profile to display the SSL Proxy Profile catalog. 2. Click Add to display the SSL Proxy Profile Configuration screen. 3. Specify the name of the object in the Name field. 4. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. 5. Select Two Way from the SSL Direction list. 6. Select the profile that defines SSL service to the backend server from the Forward (Client) Crypto Profile list. 7. Select the profile that defines SSL service to frontend clients from the Reverse (Server) Crypto Profile list. 8. Use the Server-side Session Caching toggle to enable or disable server side caching. 9. Specify the time that session-specific state data is maintained in the server cache in the Server-side Session Cache Timeout field. 10. Specify the maximum size of the server-side cache in the Server-side Session Cache Size field. 11. Use the Client-side Session Caching toggle to enable or disable client side caching. 12. Use the Client Authentication is optional toggle to control when SSL client authentication is optional. on Client authentication is not required. When there is no client certificate, the request does not fail. 20 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

off (Default) Requires client authentication only when the server cryptographic profile has an assigned Validation Credentials. 13. Use the Always Request Client Authentication toggle to control when to request SSL client authentication. on Always requests client authentication. off (Default) Requests client authentication only when the server cryptographic profile has an assigned Validation Credentials. 14. Click Apply to save the object to the running configuration. 15. Optionally, click Save Config to save the object to the startup configuration. Working with Validation Credentials objects A Validation Credentials consists of a list of certificate objects. Validation Credentials are used to validate the authenticity of received certificates and digital signatures. You can create Validation Credentials with the following types of credentials: v All non-expiring, non-password-protected credentials v Select credentials Independent of which type of Validation Credentials, the creation starts at the same location. To create any Validation Credential, select Objects Crypto Crypto Validation Credentials. Creating for non-expiring, non-password-protected certificates You can create a Validation Credential includes all valid, non-expired, non-password-protected certificates in the pubcert: file repository. The following procedure silently creates a Certificate object for each valid certificate file in the pubcert: file repository To create this type of Validation Credentials, use the following procedure: 1. Select Objects Crypto Crypto Validation Credentials. 2. Click Create Validation Credential from pubcert: to display a confirmation screen. 3. Click Confirm to create the Validation Credentials, with the appliance-supplied name of pubcert. 4. After the WebGUI reports successful completion, click Close. To refresh the Crypto Validation Credentials catalog, select Objects Crypto Crypto Validation Credentials. Click Refresh List. To save the Validation Credentials to the startup configuration, click Save Config. Creating for select certificates To prepare a Validation Credentials that contains selected certificate objects from the pubcert: file repository, use the following procedure: 1. Select Objects Crypto Crypto Validation Credentials. 2. Click Add. 3. Provide the following inputs: Name Specify the name of the object. Chapter 2. Securing communication 21

Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Certificates Use the list to add select Certificate objects to the Validation Credentials. Certificate Validation Mode Select one of the following modes: Match exact certificate or immediate issuer (Default) The behavior is that the Validation Credentials contains either the exact peer certificate to match or the certificate of the immediate issuer, which could be an intermediate CA or a root CA. This mode is useful when you want to match the peer certificate exactly, but that certificate is not a self-signed (root) certificate. Full certificate chain checking (PKIX) The complete certificate chain is checked from subject to root when using this Validation Credentials for certificate validation. Validation succeeds only if the chain ends with a root certificate in the Validation Credentials. Non-root certificates in the Validation Credentials will be used as untrusted intermediate certificates. Additional untrusted intermediate certificates will be obtained dynamically from the context at hand (SSL handshake messages, PKCS#7 tokens, PKIPath tokens, and so forth). Use CRLs Determines whether each Certificate Revocation List (CRL) is checked during the processing of the certificate chain. on (Default) Checks the CRLs. off Does not check CRLs. Require CRLs When CRLs are checked during processing of the certificate chain, determines whether the processing should fail when no CRL is available. on Processing fails. off (Default) Processing succeeds. CRL Distribution Points Handling Determines how to handle Certificate Revocation List (CRL) checking of X.509 CRL Distribution Points extensions during processing of the certificate chain and controls how to handle certificates in the Validation Credentials. Ignore Ignores extensions. Require Checks, but does not retrieve, extensions. Initial Certificate Policy Set When the mode is PKIX, defines the certificate chain validation input that RFC 3280 calls the user-initial-policy-set. This set of OIDs specifies the only allowable values of Certificate Policies at the end of chain processing. 22 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

If you define an initial certificate policy set, you will want to enable the Require Explicit Certificate Policy field. Otherwise, these certificate policy sets will be used only when there are Policy Constraints extensions in the certificate chain. The default contains the OID for anypolicy. Require Explicit Certificate Policy When the mode is PKIX, controls whether the validation chain (algorithm) can end with an empty policy tree (that RFC 3280 calls the initial-explicit-policy ). on The algorithm must end with a non-empty policy tree. off The algorithm can end with an empty policy tree unless Policy Constraints extensions in the chain require an explicit policy. 4. Click Apply to save the object to the running configuration and return to the object catalog. 5. Optionally, click Save Config to save the object to the startup configuration. Chapter 2. Securing communication 23

24 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Chapter 3. Configuring Web Application Firewall services Scenarios This chapter documents the creation or editing of a Web Application Firewall service using the Advanced Web Application Firewall Configuration screen. A Web Applications Firewall provides security, proxy, threat mediation, and content processing services for a Web-based application (such as enrollment, benefits management, ticket sales, or a trading system). The Web Applications Firewall is designed to handle traffic that is primarily URL-encoded HTTP POST operations (or HTTP GET with or without Query Strings) and not primarily Web services SOAP-based XML payloads (although XML traffic can be handled). The Web Application Firewall offers: v Destination Service Proxy v SSL Termination v Authentication and Authorization Service v Rate Limiting v Session Start and Timeout Enforcement v URL-Encoded Name-Value Input Processing v HTTP Protocol Filtering v Threat Protection, such as SQL Injection v Cookie Handling, including Sign and Encrypt v Error Handling v XML and Non-XML Content Processing This section provides scenarios using the Web Application Firewall service. For each scenario, there is a requirement statement followed by the recommended configuration to meet those requirements. Scenario one: College enrollment form Requirements A community college offers the opportunity to sign up for evening classes. The server that hosts this application is connected to sensitive College administrative systems and thus the college does not want HTTP traffic to flow directly to the host. The college IT administrators would also like to restrict the size and depth of inbound posts, to protect against malicious intent. The entire transaction must be SSL-encrypted but the host does not have the necessary cycles to manage the encryption. Solution Web Application Firewall Configuration: v Proxies Destination Address (real host address not exposed) v Applies SSL Server Proxy Profile v Default Threat Protections v Default Multi-Part Form Protections v Error Handling Policy redirects to friendly page Copyright IBM Corp. 2002, 2009 25

Scenario two: Benefits management site Requirements A large corporation offers complete online management of employee benefits. The information is sensitive so the transaction must be SSL encrypted and any login must time out after a certain amount of idle time. Users must supply a user name and password to access the site. As some forms are multi-page, a session cookie is required and this cookie must be encrypted for security reasons. Certain partner sites are allowed to POST entire forms as XML data. Users are redirected to an error handling page when errors occur. Solution Web Application Firewall Configuration: v Proxies Destination Address (real host address not exposed) v Applies SSL Server Proxy Profile v AAA Basic Authentication verifies user name and password with LDAP v Default Threat Protections v Default Multi-Part Form Protections v Well Formed XML enforced v v v v v Error Handling Policy redirects to friendly page; XML submits get XML response Cookie Required Cookie Encrypted Start Page Filtering Session Management Timeout Scenario three: Trading site Requirements An online business offers a trading site, in which customers are trading nearly anything for anything. Customers need to be able to search for desired objects, upload descriptions of items for trade, and securely close the deal. In some cases, an offered item might draw more than one bidder (or trade offer). Users must supply a user name and password to access the site. Because of the speed of transactions, a single signon system is needed and cookies are used. Due to the competitive nature of the business, connections must be rate limited, preventing a single entity from flooding the site. The site offers third party participation, so every post must be vetted for size and correctness. In addition, responses from the central trading systems must also be limited in size and vetted for correctness. SQL Injection Attack protection is required. Solution Web Application Firewall Configuration: v Proxies Destination Address (real host address not exposed) v Applies SSL Server Proxy Profile v AAA basic authentication verifies user name and password with LDAP v Custom threat protections and protection from SQL injection v Custom Multi-Part Form Protections v Requests Rate Limited v Requests Vetted for Correct Name-Value Pairs 26 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

v v v v v Error Handling Policy redirects to friendly page Cookie Required Start Page Filtering Session Management Timeout Responses Vetted for Correct Name-Value Pairs Configuring a Web Application Firewall General configuration Select Services Web Application Firewall New Web Application Firewall to display the Web Application Firewall Configuration screen. Provide the following inputs. Name Specify a unique name for this object. The name must be unique throughout the appliance. Summary Brief summary for user annotation. This is optional. Remote Host Address The host name or IP address of the backend server. To use a load balancer, specify the name of the Load Balancer Group. If the appliance should employ an SSL connection to the backend server, configure an SSL Proxy Profile that in turn uses a Crypto Profile configured for client (or forward) connections. Remote IP Port The TCP port number of the backend server. XML Manager An XML Manager manages the compilation and caching of XSL style sheets, the caching of XML documents, and provides configuration constraints on the size and parsing depth of XML documents. You can enable streaming XML operation by configuring an XML Manager to use a Streaming Compile Option Policy. An XML Manager can optionally employ a User Agent. The User Agent settings, in turn, can affect the behavior of the gateway when communicating with backend servers or with clients when sending back responses. More than one firewall can use the same XML Manager. Select an existing XML Manager to assign the Manager to this firewall. Click the + button to create a new XML Manager that is assigned to this firewall. A default Manager is used if you do not create one. SSL Proxy Profile Select an existing SSL Proxy Profile to assign the SSL Proxy Profile to this handler. When selected, communication with clients, the backend server, or both will use SSL in accordance with the configured Crypto Profile. v To implement SSL communication with requesting clients, use an SSL Proxy Profile that uses a Crypto Profile configured as a Server (reverse) profile. Under Source Addresses, set the Use SSL check box for at least one source address. Chapter 3. Configuring Web Application Firewall services 27

v To implement SSL communication with the backend server, use an SSL Proxy Profile that uses a Crypto Profile configured as a Client (forward) profile. v To implement SSL communication with both requesting clients and the backend server, use an SSL Proxy Profile that uses a Crypto Profile configured for two-way SSL. Refer to Defining SSL Proxy Profile objects on page 19 for more information. Default Error Handling Policy If any part of the Application Security Policy selected below is violated, the service will handle the violation, or error, in accordance with the rules set forth in the selected Error Policy. This is the default policy that will handle the response sent to the client. If no Policy is selected (the list remains at (none)), all failures of Policy will generate an error by default. An Application Security Policy can also establish an Error Policy; the Error Policy established by the Application Security Policy overrides this default selection. Refer to Error Policy on page 99 for more information. Security Policy A Security Policy is required to create the service. To establish the security policy enforced by this firewall, select an Application Security Policy. Refer to Configuring an Application Security Policy on page 30 for more information. Either the Request security policy or the Response security policy that is established by the select Application Security Policy can be turned off using the Request Security or Response Security toggle on the Timeout/Protocol tab. Source Addresses Source addresses determine the IP addresses and TCP ports to assign to the service. Remote clients connect to these addresses. At least one source address must be configured. To add a source address, provide the following information. IP Port Specify the IP address, host name, or host alias on which the service listens. The default is 0.0.0.0. This value indicates that the service is active on all addresses. Specify the TCP port on which the service listens. Use an integer in the range of 1 through 65535. There is no default value. SSL Indicates whether the service acts as an SSL server for requesting clients. v Select the check box to enable. v Ensure that the check box is not selected to disable. When enabled, the Crypto Profile of the selected SSL Proxy Profile handles these requests. Click Add. The new Source Address appears in the listing of all configured source addresses. 28 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

To create the new Web Application Firewall service using the standard defaults for the configuration options available on the Timeout/Protocol tab, click Commit. You can optionally set additional configuration parameters on the Timeout/Protocol tab. Timeout/Protocol These configuration options control time outs and HTTP protocol-specific options. The defaults are set to handle the majority of scenarios. Provide the following inputs: Front Side Timeout Controls the amount of time a front side client connection can be idle before being abandoned in a transaction. Back Side Timeout Controls the amount of time a back side client connection can be idle before being abandoned in a transaction. Front Persistent Timeout Specifies the maximum number of seconds (in the range 0 through 86400, with a default of 180) that a gateway maintains an idle persistent TCP connection on the front side. Back Persistent Timeout Specifies the maximum number of seconds (in the range 0 through 86400, with a default of 180) that a gateway maintains an idle persistent TCP connection on the back side. HTTP Response Version Select the HTTP version (1.0 or 1.1) to be used on client responses. Incoming version 1.0 requests will always be replied to with 1.0 compatible responses regardless of this setting. Use 1.1 to support chunked responses. HTTP Version to Server Select the HTTP version (1.0 or 1.1) to use on the server-side connection. Certain HTTP 1.1 features, such as chunked uploads, require the selection of 1.1. The backend server must also support HTTP 1.1 for the connection to be established and maintained using the 1.1 version of the protocol. Stream Output to Back Select the desired streaming behavior. Buffer Messages Buffers submitted messages until all processing is verified as complete. After verification, forward the message to the appropriate backend. Stream Messages Begins to send the message to the backend before all processing is complete. This behavior potentially increases processing speed. Select this option when the selected XML Manager has streaming enabled or when streaming of attachments is enabled. Stream Output to Front Select the desired streaming behavior. Buffer Messages Buffers submitted messages until all processing is verified as complete. After verification, forward the message to the appropriate requesting client. Chapter 3. Configuring Web Application Firewall services 29

Stream Messages Begins to send the message to the requesting client all processing is complete. This behavior potentially increases processing speed. Select this option when the selected XML Manager has streaming enabled or when streaming of attachments is enabled. Normalize URI When enabled (on), the URI is rewritten to make the URI RFC-compliant. Certain characters will be escaped; additionally, characters that are escaped that do not need to be are unescaped. This makes checking for attack sequences more reliable. Request Security If disabled (off), no request side security policies is enforced and all requests are allowed through. This setting overrides the previously selected Application Security Policy. Response Security If disabled (off), no response side security policies is enforced and all responses are allowed through. This setting overrides the previously selected Application Security Policy. Configuring an Application Security Policy An Application Security Policy establishes the rules that are used to enforce security for a Web Application Firewall service. This policy employs Request Map, Response Map, and Error Map objects. Each of these map objects, in turn, matches a Web Request Profile, Web Response Profile, or Error Policy object, respectively, to client-requests that are based on a set of matching criteria. The selected profile object then provides the detailed security configuration. General configuration Provide the following input: Name Specify a name for this Policy. This is the name that appears in all Policy listings. Request Maps Request Maps select Web Request Profiles to execute on client requests based on a set of matching criteria. If the client request meets the matching criteria, the corresponding Web Request Profile executes. Note: You must create at least one Request Map to complete the Policy creation. Click the Request Maps tab to establish Web Request matching maps. Provide the following inputs: Match Select an existing Matching Rule. Refer to Matching Rule on page 106 for more information. Rule Select an existing Web Request Profile. Refer to Web Request Profile on page 132 for more information. Click Add Request Map to save the map. The new map is displayed in the catalog. 30 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Click Commit to complete configuration of the Policy. Note: The order of Request Maps is important. The maps are checked from the top to the bottom of the list; the first matching expression that returns true will execute. Use the Reorder button to establish the desired ordering of maps. Response Maps Response Maps select Web Request Profiles to execute on server responses based on a set of matching criteria. If the server response meets the matching criteria, the corresponding Web Request Profile executes. Note: You must create at least one Response Map to complete the Policy creation. Click the Response Maps tab to establish Web Response matching maps. Provide the following inputs: Match Select an existing Matching Rule. Refer to Matching Rule on page 106 for more information. Rule Select an existing Web Response Profile. Refer to Web Response Profile on page 139 for more information. Click Add Response Map to save the map. The new map is displayed in the catalog. Click Commit to complete configuration of the Policy. Note: The order of Response Maps is important. The maps are checked from the top to the bottom of the list; the first matching expression that returns true will execute. Use the Reorder button to establish the desired ordering of maps. Error Maps Error Maps select a Processing Rule to execute on errors based on a set of matching criteria. If the error meets the matching criteria, the corresponding Processing Rule executes. Click the Error Maps tab to establish Error Policy matching maps. Provide the following inputs: Match Select an existing Matching Rule. Refer to Matching Rule on page 106 for more information. Rule Select an existing Processing Rule. Refer to Processing Rule on page 111 for more information. Click Add Error Map to save the map. The new map is displayed in the catalog. Click Commit to complete configuration of the Policy. Chapter 3. Configuring Web Application Firewall services 31

32 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Chapter 4. Managing files Directories on the appliance The appliance contains no hard drive for file storage. As a result, the storage space for files and other artifacts is limited. The file system contains many examples and critical configuration files. These directories and their contents are as follows: audit: This directory contains the audit logs. Each appliance contains only one audit: directory. This directory cannot be the destination of a copy. This directory is available from the command line in the default domain only. To view the audit log from the WebGUI, select Status View Logs Audit Log. cert: This encrypted directory contains private key and certificate files that services use in the domain. You can add, delete, and view files, but you cannot modify these files while in the domain. Each application domain contains one cert: directory. This directory is not shared across domains. chkpoints: This directory contains the configuration checkpoint files for the appliance. Each application domain contains one chkpoints: directory. This directory is not shared across domains. config: dpcert: This directory contains the configuration files for the appliance. Each application domain contains one config: directory. This directory is not shared across domains. This encrypted directory contains files that the appliance itself uses. This directory is available from the command line in the default domain only. export: This directory contains the exported configurations that are created with the Export Configuration utility. Each application domain contains one export: directory. This directory is not shared across domains. image: This directory contains the firmware images (primary and secondary) for the appliance. This directory is where firmware images are stored typically during an upload or fetch operation. Each appliance contains only one image: directory. This directory is available in the default domain only. local: This directory contains miscellaneous files that are used by the services within the domain, such as XSL, XSD, and WSDL files. Each application domain contains one local: directory. This directory can be made visible to other domains. When viewed from other domains, the directory name changes from local: to the name of the application domain. logstore: This directory contains log files that are stored for future reference. Typically, the logging targets use the logtemp: directory for active logs. You can move log files to the logstore: directory. Each application domain contains one logstore: directory. This directory is not shared across domains. Copyright IBM Corp. 2002, 2009 33

logtemp: This directory is the default location of log files, such as the appliance-wide default log. This directory can hold only 13 MB. This directory cannot be the destination of a copy. Each application domain contains one logtemp: directory. This directory is not shared across domains. pubcert: This encrypted directory contains the security certificates that are used commonly by Web browsers. These certificates are used to establish security credentials. Each appliance contains only one pubcert: directory. This directory is shared across domains. sharedcert: This encrypted directory contains security certificates that are shared with partners. Each appliance contains only one sharedcert: directory. This directory is shared across domains. However, you must be in default domain to create or upload keys and certificates. store: This directory contains example style sheets, default style sheets, and schemas that are used by the local appliance. Do not modify the files in this directory. Each appliance contains only one store: directory. By default, this directory is visible to all domains. You can make changes to the contents of this directory from the default domain only. The store: directory has the following subdirectories: meta This encrypted subdirectory contains files that are used by the appliance itself. msgcat This subdirectory contains the message catalogs. policies This subdirectory contains the following subdirectories. The contents of these subdirectories affect Web services policy. custom This subdirectory contains custom style sheets. mappings This subdirectory contains mapping style sheets. templates This subdirectory contains XML files. profiles This subdirectory contains style sheets that are used by DataPower services. schemas This subdirectory contains schemas that are used by DataPower services. dp This encrypted subdirectory contains files that are used by the appliance itself. This subdirectory is available from the command line only. 34 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

pubcerts This encrypted subdirectory contains files that are used by the appliance itself. This subdirectory is available from the command line only. tasktemplates: This directory contains the XSL files that define the display of specialized WebGUI screens. Each appliance contains only one tasktemplates: directory. This directory is visible to the default domain only. temporary: This directory is used as temporary disk space by processing rules. Each application domain contains one temporary: directory. This directory is not shared across domains. Launching the File Management utility Displaying directory contents Creating a subdirectory To manage files, launch the File Management utility with one of the following methods: v v Select the File Management icon from the Files and Administration section of the Control Panel. Select Administration Main File Management. Either method displays the File Management screen. The initial screen shows the top level directories. To display (expand) the contents of a directory, perform the following procedure: 1. Launch the File Management utility. Refer to Launching the File Management utility for details. 2. Select the directory to display its contents. To hide (collapse) the content-view of a directory, select that directory again. Subdirectories can only be creates under the local: directory or one of its subdirectories. Follow these steps to create a subdirectory under the local: directory or one of its subdirectories: 1. Launch the File Management utility. Refer to Launching the File Management utility for details. 2. From the Action column, click Actions aligned with the directory for the subdirectory to be created. 3. Click Create Subdirectory. The File Management screen displays. 4. Enter the name of the new subdirectory in the directory Name field. 5. Click Confirm Create. The File Management screen refreshes. 6. Click Continue. The File Management screen displays the top-level directories only. Chapter 4. Managing files 35

Deleting a directory Directories can only be deleted in the local: directory or one of its subdirectories. Follow these steps to delete a directory under the local: directory or one of its subdirectories: 1. Launch the File Management utility. Refer to Launching the File Management utility on page 35 for details. 2. From the Action column, click Actions aligned with the directory to be deleted. 3. Click Delete Directory. The File Management screen displays. 4. Click Confirm Delete. The File Management screen refreshes. 5. Click Continue. The File Management screen displays the top-level directories only. Refreshing directory contents To refresh contents, click the Refresh Page icon. The WebGUI redraws the File Management screen. The screen displays the top-level directories only. Uploading files from the workstation Use the following procedure to upload a file from your workstation to the appliance: 1. Launch the File Management utility. Refer to Launching the File Management utility on page 35 for details. 2. Navigate to the directory into which you want to upload the file. 3. Click Actions in that row to open the Directory Actions menu. 4. Click Upload Files to display the File Upload screen. 5. Specify the path-qualified name of the workstation file in the File to upload field, or click Browse to locate the file on the workstation. 6. Specify the file name in the Save as field. Note: If you used browsing to select the file or if you navigated to this field using the tab key, the field contains the file name. 7. To add another file to be uploaded: a. Click Add. b. Repeat steps 5 and 6. 8. If one of the files already exists in the selected directory and you want to overwrite this file, check the Overwrite Existing Files check box. If you do not select this check box and the file already exists, the file is not uploaded. 9. Click Upload. 10. When the appliance reports success (or an error is the file already existed), click Continue to return to the File Management screen. The target directory now contains the uploaded files. To verify, use the procedure described in Displaying directory contents on page 35. 36 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Working with Java Key Stores A Java Key Store (JKS) is a Sun-proprietary format file that contains private keys and certificates. The java.security package and sub-packages access the data in the JKS to carry out their cryptographic operations. Required software JKS support requires the following software on the WebGUI workstation: v v v Version 1.4.2 of the Java runtime environment (j2re1.4.2) SDK (j2sdk1.4.2) Internet Explorer Note: You must have the JRE or Java SDK /bin path name in the Windows PATH environment variable on the WebGUI workstation. The Java Key Store file cannot reside on any of the local directories. It must be uploaded from a workstation. Granting permissions In addition, the user must have the grant permission for the upload in the.java.policy file on the workstation that contains the Java Key Store files. The following example.java.policy file should be defined on the workstation computer before starting the upload: grant { permission java.io.filepermission "<<ALL FILES>>","read"; permission java.util.propertypermission "*", "read"; permission java.lang.runtimepermission "accessclassinpackage.sun.*"; }; You can grant read-only permission to the JKS file. Types of key stores Sun offers two common methods to support key store creation: v v Sun Java 2.1.4.2 runtime environment or SDK use a program called keytool to create and manage a JKS-type file store with no provider name. SunJCE (Java Crypto Extension) generates a JCEKS-type (Java Crypto Extension Key Store) file store with the provider name SunJCE. You must know the key store type to successfully upload files from a JKS. Uploading a file from a Java Key Store Use the following procedure to upload a file from a Java Key Store (JKS) to the appliance: 1. Launch the File Management utility. Refer to Launching the File Management utility on page 35 for details. 2. Navigate to the directory into which you want to upload the file. 3. Click Actions in that row to open the Directory Actions menu. 4. Click Upload Files to display the File Upload screen. 5. Click the Java Key Store radio button to display the JKS Upload screen. Note: When you click the Java Key Store radio button, the Java Console of the browser opens and shows whether the Java Key Store Access Chapter 4. Managing files 37

Applet is running. If the applet cannot be accessed, you cannot upload JKS files. Ensure that your browser is enabled to use the Java 1.4.2 applet. 6. Specify the full path to the target JKS in the Java key store field or click Browse. 7. Specify JKS or JCEKS (the JKS type) in the Key store type field. 8. If the type is JCEKS, specify SunJCE (the provider name) in the Key store provider field. Otherwise, leave blank. 9. Specify the JKS password in the Key store password field. 10. Identify the files to upload with the Key to upload list. Use the Refresh button, if necessary. 11. Specify the key-specific password in the Key password field. 12. Specify the file name in the Save as field. 13. If the file already exists in the selected directory and you want to overwrite this file, check the Overwrite Existing Files check box. If you do not select this check box and the file already exists, the file is not uploaded. 14. Click Upload. 15. When the appliance reports success, click Continue to return to the File Management screen. The target directory now contains the uploaded key or certificate. To verify that the file exists, use the procedure described in Displaying directory contents on page 35. If the upload fails, look at the Java Console of the browser to determine whether an exception was thrown. Fetching files Use the following procedure to retrieve a file from a remote URL (fetch) and store that file in a specified directory on the appliance: 1. Launch the File Management utility. Refer to Launching the File Management utility on page 35 for details. 2. Navigate to the directory into which you want to upload the file. 3. Click Actions in that row to open the Directory Actions menu. 4. Click Fetch Files to display the Fetch File screen. 5. Specify the location of the file in the Source URL field. 6. Specify the file name in the Save as field. 7. If the file already exists in the selected directory and you want to overwrite this file, check the Overwrite Existing Files check box. If you do not select this check box and the file already exists, the file is not uploaded. 8. Click Fetch. 9. When the appliance reports success, click Continue to return to the File Management screen. The target directory now contains the retrieved file. To verify, use the procedure described in Displaying directory contents on page 35. Copying files Use the following procedure to copy a file from one directory to another: 38 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Renaming files Moving files 1. Launch the File Management utility. Refer to Launching the File Management utility on page 35 for details. 2. Navigate to the directory that contains the files to be copied. 3. Select files by clicking the box adjacent to the file name. 4. Scroll to the top or bottom of the screen and click Copy to display the File Copy screen. 5. From the New Directory Name list, select the target directory. 6. Specify the name for the file, if different, in the New File Name field. 7. If one of the selected files already exists in its associated target directory and you want to overwrite this file, check the Overwrite Existing Files check box. If you do not select this check box and the file already exists, the file is not copied. 8. Click Confirm Copy to copy the files to the target directories. 9. When the appliance reports success, click Continue to return to the File Management screen. The target directories now contain the copied files. To verify that the files exist, use the procedure described in Displaying directory contents on page 35. Use the following procedure to rename a file: 1. Launch the File Management utility. Refer to Launching the File Management utility on page 35 for details. 2. Navigate to the directory that contains the files to be copied. 3. Select files by clicking the box adjacent to the file name. 4. Click Rename to display the File Rename screen. 5. Specify the name of the file in the New File Name field. 6. If one of the selected files already exists in the target directory and you want to overwrite this file, check the Overwrite Existing Files check box. If you do not select this check box and the file already exists, the file is not copied. 7. Click Confirm Rename. 8. When the appliance reports success, click Continue to return to the File Management screen. The target directories now contain the renamed files. To verify that the files exist, use the procedure described in Displaying directory contents on page 35. Use the following procedure to move a file from one directory to another: 1. Launch the File Management utility. Refer to Launching the File Management utility on page 35 for details. 2. Navigate to the directory that contains the files to be moved. 3. Select files by clicking the box adjacent to the file name. 4. Click Move to display the Move File screen. 5. From the New Directory list, select the target directory. 6. If one of the selected files already exists in its directory and you want to overwrite this file, select the Overwrite Existing Files check box. If you do not select this check box and the file already exists, the file is not moved. Chapter 4. Managing files 39

7. Click Confirm Move. 8. When the appliance reports success, click Continue to return to the File Management screen. The target directories now contain the moved files. To verify that the files exist, use the procedure described in Displaying directory contents on page 35. Viewing files Use the following procedure to view a text file: 1. Launch the File Management utility. Refer to Launching the File Management utility on page 35 for details. 2. Navigate to the directory that contains the file. 3. Click the file to open a browser that contains the file. When finished viewing the file, close the browser. Editing files Use the following procedure to edit a text file: 1. Launch the File Management utility. Refer to Launching the File Management utility on page 35 for details. 2. Navigate to the directory that contains the files to be edited. 3. Select the file to be edited by clicking Edit in the row that is associated with that file. The WebGUI displays a file preview. 4. Click Edit to change to Edit Mode. 5. Edit the file as required. 6. Click Submit to complete the edit process. 7. When the appliance reports success, click Close to return to the File Management screen. Deleting files Use the following procedure to delete a file: 1. Launch the File Management utility. Refer to Launching the File Management utility on page 35 for details. 2. Navigate to the directory that contains the files to be deleted. 3. Select files by clicking the box adjacent to the file name. 4. Scroll to the top or bottom of the screen and click Delete to display the Delete File screen. 5. Click Confirm Delete to delete the files. 6. When the appliance reports success, click Continue to return to the File Management screen. The selected files were deleted. To verify that the files no longer exist, use the procedure described in Displaying directory contents on page 35. 40 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Chapter 5. Managing the configuration of the appliance This chapter provide information about managing the configuration of application domains and importing and exporting configurations. Creating Include Configuration File objects Include Configuration File objects allow you to include configuration information from an external configuration file in the local configuration information. This external file can be stored on a centralized configuration server or another DataPower appliance. The information in the Include Configuration File object is appended to the local configuration information when the configuration of the DataPower appliance is reloaded (such as during appliance reboot, firmware reload, or domain restart). An Include Configuration File object can include configuration information only. On the other hand, an Import Configuration File object is a configuration package that can include both configuration information and supporting files. To append configuration information from an external file to the local configuration information, perform the following procedure: 1. Select Objects Configuration Management Include Configuration File to display the catalog. 2. Click the name of an existing Include Configuration File object to edit it, or click Add to create a new one. The Include Configuration File configuration screen is displayed. 3. Specify the name of the object in the Name field. 4. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. 5. Specify a descriptive object-specific summary in the Comment field. 6. Specify the URL of the configuration file in the URL of Configuration File field. For example, specify https://config.server.com/datapower/ firewalls.cfg. 7. Use the Execute on Startup toggle to indicate whether to import the configuration package at startup. on (Default) Imports the configuration package at startup. The configuration is marked external and cannot be saved to the startup configuration. This behavior is equivalent to always importing the configuration. off Imports the configuration package when manually triggered. The configuration is not marked external and can be saved to the startup configuration. This behavior is equivalent to importing the configuration one time. 8. When retrieving the configuration file, select when to retrieve the configuration file with the Interface Detection toggle. on Retrieves the configuration file after the local interface is up. off (Default) Retrieves the configuration file at appliance reload without waiting for the local interface to be up. Copyright IBM Corp. 2002, 2009 41

9. Click Apply to save the object to the running configuration. 10. Optionally, click Save Config to save the object to the startup configuration. Note: Unless you click Save Config, the included configuration file will not take affect when the appliance is started. Creating Import Configuration File objects Import Configuration File objects allow you to import a configuration package from an external configuration file into the local configuration information. The external file can be stored on a centralized configuration server or another DataPower appliance. The configuration data and files in the configuration file is added to the local configuration information when the configuration of the DataPower appliance is reloaded (such as during appliance reboot, firmware reload, or domain restart). The default configuration of an Import Configuration File object does not provide warnings about conflicts with existing files and objects. An Import Configuration File object is a configuration package that can include both configuration information and supporting files. On the other hand, an Include Configuration File object can include configuration information only. To import a configuration package from an external file to the local configuration information, perform the following procedure: 1. Select Objects Configuration Management Import Configuration File to display the catalog. 2. Click the name of an existing configuration package to edit it, or click Add to create a new one. The Import Configuration File configuration screen is displayed. 3. Specify the name of the object in the Name field. 4. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. 5. Specify a descriptive object-specific summary in the Comment field. 6. Specify the URL of the configuration package in the URL of Configuration Package field. For example, specify https://config.server.com/datapower/ firewalls.zip. Note: You cannot use the SCP or SFTP protocol to retrieve a configuration package. All other URL protocols are available; for example, HTTP, HTTPS, or FTP. 7. Select the package format from the Format of Configuration Package list. ZIP (Default) Indicates that the configuration package is in ZIP format. If the format is ZIP, the bundle is unzipped automatically. XML Indicates that the configuration package in XML format. 8. Use the Overwrite Files toggle to control the overwrite behavior. on (Default) Overwrites files of the same name. off Does not import the file if a file of the same name exists. 9. Use the Overwrite Objects toggle to control the overwrite behavior. on (Default) Overwrites objects of the same name. off Does not import the objects if an objects of the same name exists. 42 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

10. (Optional) Select a deployment policy that preprocesses the configuration package from the Deployment Policy list. For more information, refer to Configuring deployment policies on page 54. 11. Use the Local IP Rewrite toggle to indicate whether to rewrite local IP addresses on import. on (Default) Rewrites IP addresses to match the local configuration when imported. For example, a service in the configuration package that binds to eth1 is rewritten to bind to eth1 when imported. off Retains the original IP address in the configuration package. 12. Use the Import on Startup toggle to indicate whether to import the configuration package at startup. on (Default) Imports the configuration package at startup. The configuration is marked external and cannot be saved to the startup configuration. This behavior is equivalent to always importing the configuration. off Imports the configuration package when manually triggered. The configuration is not marked external and can be saved to the startup configuration. This behavior is equivalent to importing the configuration one time. 13. Click Apply to save the object to the running configuration. 14. Optionally, click Save Config to save the object to the startup configuration. Backing up and exporting configuration data The backup and export utility copies specified configuration data from the appliance to a file in the export: directory. You can optionally download the file to your workstation. Note: Exported configuration data should not be imported to an appliance with an earlier release level. Between releases, configuration data for properties can change. If you attempt to import configuration data from an appliance of a later release level into an appliance of an earlier release level, the operation might report success, but the configuration data might not be the same. Therefore, use this utility to exchange configuration data among appliances of the same release level. You can use this utility to perform the following operations: v Create a backup of the entire appliance v Create a backup of one or more application domains v Export select objects from the current domain v Copy or move select objects between domains Note: The following objects are never exported: v User account objects v Certificate objects v Key objects (HSM appliances only) The following files are never exported: v Log files v Firmware files Chapter 5. Managing the configuration of the appliance 43

To ensure that all other objects and files are exported, use the admin account. For any other user, only objects and files that are accessible to that user are included in the export package. To start a back up or export operation, select Administration Configuration Export Configuration to display the initial Export Configuration screen. This screen provides the following export options: v Create a backup of the entire system v Create a backup of one or more application domains v Export configuration and files from the current domain v Copy or move configuration and files between domains Backing up the entire appliance Use the following procedure to back up (export) all configuration data for the appliance. 1. Select Administration Configuration Export Configuration to display the Initial Export Configuration screen. 2. Select Create a backup of the entire system and click Next to display the File Name screen. a. Specify a descriptive object-specific summary in the Comment field. b. Optionally create or select the name of a Deployment Policy to accept, filter, or modify a configuration during import. c. The Export File Name defaults to export (.zip). If a file of this name exists in the export: directory, it is overwritten. d. Click Next. The configuration of the entire appliance is backed up. When the backup completes, the file is in the export: directory. You can optionally download the export file to your workstation. Note: The Import Configuration utility requires that the export file resides on your workstation. 3. Optionally click Download to download the file to your workstation. 4. Click Done to close this window and return to the Control Panel. The export file can be accessed from the export: directory. If downloaded, the export file is on your workstation. Backing up domains Best practice is to periodically back up all domains individually. To back up configuration information for one or more application domains, follow this procedure: 1. Select Administration Configuration Export Configuration to display the Initial Export Configuration screen. 2. Select Create a backup of one or more application domains and click Next to display the selection screen. 3. Provide the following inputs: a. Specify a descriptive object-specific summary in the Comment field. b. Optionally create or select the name of a Deployment Policy to accept, filter, or modify a configuration during import. 44 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

c. The Export File Name defaults to export (.zip). If a file of this name exists in the export: directory, it is overwritten. d. Select the check boxes adjacent to each domain to export. e. Click Next When the backup completes, the file is in the export: directory. You can optionally download the export file to your workstation. Note: The Import Configuration utility requires that the export file resides on your workstation. 4. Optionally click Download to download the file to your workstation. 5. Click Done to close this window and return to the Control Panel. The export file can be accessed from the export: directory. If downloaded, the export file is on your workstation. Exporting select objects The Export Configuration utility remains available from the initial Export Configuration screen. To export select objects and files, use the following procedure: 1. Select Administration Configuration Export Configuration to display the Initial Export Configuration screen. 2. Select Export configuration and files from the current domain and click Next to display the Export Configuration screen. 3. Provide the following inputs: a. Specify a descriptive object-specific summary in the Comment field. b. Optionally create or select the name of a Deployment Policy to accept, filter, or modify a configuration during import. c. The Export File Name defaults to export (.xml or.zip depending on the selected export format). If a file of this name exists in the export: directory, it is overwritten. d. Use the To radio buttons to specify the export format. XML Config Exports configuration data as XML files. Include Configuration files are referenced in the XML document only, they are not included. ZIP Bundle Exports configuration data in compressed ZIP format. Include Configuration files are in the bundle. e. Use the Configuration radio button to specify the data to export. Currently running configuration Exports the configuration data from the running configuration, not the startup configuration. Last persisted configuration Exports the configuration data from the startup configuration, not the current running configuration. f. Use the Referenced Objects radio buttons to specify the scope of the data to export. Include only the selected base objects Exports only the configuration data for the selected objects. Chapter 5. Managing the configuration of the appliance 45

Include all objects required by selected base objects Exports configuration data for the selected objects and all objects that are required by the selected objects. For example, if exporting an XSL Proxy, the export includes configuration data for the XSL Proxy, the assigned XML manager, and all associated matching rules, processing policies, processing rules, cryptographic certificates, credentials, and keys. g. Use the Export Files radio buttons to specify the scope of the data to export. Export no files No files are included in the export. If, for example, the selected objects use files, such as a style sheet, those files are not included. This option is useful when the configuration data itself is all that is needed. Export files referenced by exported objects In addition to the selected objects (and possibly referenced objects), exports public files that are associated with the selected objects. Note: The export does not include private files. These files are in the cert: and sharedcert: directories. Export all local files Exports public files that are associated with the selected objects and all files that are in the following directories: v config: v local: v pubcert: v store: v tasktemplates: h. From the Objects list, select the type or class of configuration data to export. After selecting an entry, all instances of that type or class are listed in the left-hand box. 1) Select the objects from the left-hand list. To select multiple objects, select objects in combination with the Shift and Control keys. 2) Click > to move the selected object to the Selected Base Objects list. i. Adjust the Selected Base Objects list, if necessary. 1) Select objects in the right-hand list. To select multiple objects, select objects in combination with the Shift and Control keys. 2) Click < to remove the selected objects or click <<to remove all objects from the Selected Base Objects list. j. Click Show Contents at any time to display all contents marked for inclusion in the export. k. Click Next. When the backup completes, the file is in the export: directory. You can optionally download the export file to your workstation. Note: The Import Configuration utility requires that the export file resides on your workstation. 4. Optionally click Download to download the file to your workstation. 5. Click Done to close this window and return to the Control Panel. 46 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

The export file can be accessed from the export: directory. If downloaded, the export file is on your workstation. Copying or moving select objects The copy or move utility is available from the initial Export Configuration screen. To copy or move selected objects and files, use the following procedure: 1. Select Administration Configuration Export Configuration to display the Initial Export Configuration screen. 2. Select Copy or move configuration and files between domains and click Next to display the Export Configuration screen. a. Optionally create or select the name of a Deployment Policy to accept, filter, or modify a configuration during import. b. Use the Delete After Export toggle to indicate whether the operation is a copy operation or a move operation. on Indicates a move operation. off Indicates a copy operation. c. Use the Configuration radio button to specify the data to export. Currently running configuration Exports the configuration data from the running configuration, not the startup configuration. Last persisted configuration Exports the configuration data from the startup configuration, not the current running configuration. d. Use the Referenced Objects radio buttons to specify the scope of the data to export. Include only the selected base objects Exports only the configuration data for the selected objects. Include all objects required by selected base objects Exports configuration data for the selected objects and all objects that are required by the selected objects. For example, if exporting an XSL Proxy, the export includes configuration data for the XSL Proxy, the assigned XML manager, and all associated matching rules, processing policies, processing rules, cryptographic certificates, credentials, and keys. e. Use the Export Files radio buttons to specify the scope of the data to export. Export no files No files are included in the export. If, for example, the selected objects use files, such as a style sheet, those files are not included. This option is useful when the configuration data itself is all that is needed. Export files referenced by exported objects In addition to the selected objects (and possibly referenced objects), exports public files that are associated with the selected objects. Note: The export does not include private files. These files are in the cert: and sharedcert: directories. Chapter 5. Managing the configuration of the appliance 47

Export all local files Exports public files associated with the selected objects and all files contained in the following directories: v config: v image: v pubcert: v store: v tasktemplates: f. From the Objects list, select the type or class of configuration data to export. After selecting an entry, all instances of that type or class are listed in the left-hand box. 1) Select the objects from the left-hand list. To select multiple objects, select objects in combination with the Shift and Control keys. 2) Click the > button to move the selected objects to the Selected Base Objects list. g. Adjust the Selected Base Objects list, if necessary. 1) Select objects in the right-hand list. To select multiple objects, select objects in combination with the Shift and Control keys. 2) Click < to remove the selected objects or click <<to remove all objects from the Selected Base Objects list. 3. Click Show Contents at any time to display all contents marked for inclusion in the export. 4. Click Next to display the Import File window. a. From the Domain list, select the domain where the configuration data is to imported. b. Click Import to initiate file transfer. 5. Respond to WebGUI prompts. 6. Click Done to close the Import File screen. Managing configuration checkpoints A configuration checkpoint contains configuration data from a specific point in time. The configuration checkpoint might be equivalent to the persistent configuration, might be equivalent to the running configuration, or might be different from the persisted configuration or running configuration. Within each application domain, the administrator who is associated with the admin account defines the number of configuration checkpoints to allow. You can save up to the allowed number of configuration checkpoints. When saved, a ZIP formatted file for the configuration checkpoint is written the chkpoints: directory for that application domain. Defining number configuration checkpoints to allow The administrator who is associated with the admin account can define the number of checkpoint configurations to allow for each application domain. To define the number of checkpoint to allow for an existing domain, use the following procedure: 1. Select Administration Configuration Application Domain to display the Application Domain catalog. 48 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

2. Select the specific application domain to open the domain-specific configuration screen. 3. Select the Configuration tab. 4. Specify the number of checkpoint configuration to allow in the Configuration Checkpoint Limit field. Use an integer in the range of 1 through 5. The default is 3. 5. Click Apply to save the object to the running configuration. 6. Optionally, click Save Config to save the object to the startup configuration. Saving configuration checkpoints Do not click Save Config to save a configuration checkpoint. This button does not allow you the option of saving a configuration checkpoint. To save a configuration checkpoint, use the following procedure: 1. Select Administration Configuration Configuration Checkpoints. 2. Specify the name of the configuration checkpoint in the Checkpoint Name field. 3. Click Save Checkpoint. 4. Respond to WebGUI prompts. A ZIP-formatted configuration file of the specified name is written to the chkpoints: directory. You cannot overwrite a configuration checkpoint. You must first delete the original configuration checkpoint before saving a new configuration checkpoint of the same name. For details, refer to Deleting configuration checkpoints on page 50. Listing configuration checkpoints You can view the list of saved configuration checkpoint in one of the following ways: v v From the Configuration Checkpoints screen From the File Management screen Listing from the Configuration Checkpoints screen To view from the Configuration Checkpoints screen, select Administration Configuration Configuration Checkpoints. This screen displays the list of saved configuration checkpoints at the time by name and timestamp. This section of the screen provides the following actions: Rollback Loads the configuration that is defined in the configuration checkpoint. Remove Deletes the checkpoint configuration from the chkpoints: directory. Compare Launches the Compare Configuration utility. For details, refer to Comparing configurations on page 52. Listing from the File Management utility To view from the File Management utility, use the following procedure: 1. Select the File Management icon from the Control Panel. 2. Expand the chkpoints: directory. Chapter 5. Managing the configuration of the appliance 49

Rolling back to a configuration checkpoint To load the configuration that is defined in the configuration checkpoint, use the following procedure: 1. Select Administration Configuration Configuration Checkpoints. This screen displays the list of saved configuration checkpoints at the time by name and timestamp. 2. Click Rollback. 3. Respond to WebGUI prompts. Deleting configuration checkpoints You can delete configuration checkpoint in one of the following ways: v v From the Configuration Checkpoints screen From the File Management screen Importing configuration data Deleting from the Configuration Checkpoints screen To delete from the Configuration Checkpoints screen, use the following procedure: 1. Select Administration Configuration Configuration Checkpoints. This screen displays the list of saved configuration checkpoints at the time by name and timestamp. 2. Click Remove. 3. Respond to WebGUI prompts. Deleting from the File Management screen To delete from the File Management screen, use the following procedure: 1. Select the File Management icon from the Control Panel. 2. Expand the chkpoints: directory. 3. Select the check box beside the configuration checkpoint file. 4. Click Delete. 5. Respond to WebGUI prompts. The import utility copies specified configuration data from your workstation to the DataPower appliance. Note: Exported configuration data should not be imported to an appliance with an earlier release level. Between releases, configuration data for properties can change. If you attempt to import configuration data from an appliance of a later release level into an appliance of an earlier release level, the operation might report success, but the configuration data might not be the same. Therefore, use this utility to exchange configuration data among appliances of the same release level. While importing a configuration, you can: v Set the local address bindings of services contained in the export package to match the equivalent interfaces of the local device with the Rewrite Local Service Addresses toggle (optional). v Add, modify or delete values in the configuration package being imported whose values match the defined match statement in a Deployment policy with the Use Deployment Policy list (optional). 50 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Best practice when the goal is to add, modify or delete values in a configuration package is to use a Deployment policy while importing the configuration package. Use the following procedure to import configuration data. 1. Select Administration Configuration Import Configuration to display the Import Configuration window. a. Use the From radio buttons to specify the import format. XML Config Imports configuration data as XML files. ZIP Bundle Imports configuration data in compressed ZIP format. b. Retain the selection of the File radio button. c. Click Browse to select the file to import. d. Retain the selection of (none) for the Use Deployment Policy list. For more information, refer to the Configuring deployment policies on page 54. e. Use the Rewrite Local Service Addresses toggle to control whether to substitute IP addresses: on (Default) Allows local IP addresses to be rewritten. off Does not allow local IP addresses to be rewritten. 2. Click Next to display the Select Application Domains for Import window. If there are no objects in the configuration you are importing, skip to step 6c on page 52. When importing from any domain other than default, the imported configuration applies only to the current domain. The WebGUI might display an error message when importing data that was exported from the default domain. 3. Select the desired domains. To select all domains, click All. To deselect selected domains, click None. If a selected domain does not exist on the appliance, as indicated, it will be created. 4. Click Next to display the Import Object Selection List window. 5. Select the objects to import. Note: Click Save Config to save the configuration for each domain that contains imported objects or files. To effectively complete an appliance import (restore), use the admin account. The appliance to be restored must also first be re-initialized through the command line. 6. Click Next to display the Import Summary window, which details the contents of the target file. In some cases, the summary might indicate differences in file versions. Note: Warnings can appear on this screen that alert you to a range of possible conflicts that the imported configuration might cause. Depending on the warning, you might want to create a new application domain, or you might want to choose not to overwrite objects or files. a. Select each item to overwrite. To select all item, click All. To deselect selected items, click None. Only selected items are imported. b. Click Import to initiate file transfer. Chapter 5. Managing the configuration of the appliance 51

At the completion of the import process, the WebGUI displays the Object Import Results window, which details the results. c. Click Done to close this window. If more than one domain is being imported, the Import Summary window is displayed for the next domain to import. Managing changes in configuration data You to create a report that lists the differences between two configurations. Generally, the two configurations that are being compared are the persisted configuration and the running configuration. However, you can compare either configuration to a saved version of the configuration. These saved versions of the configuration can be an exported configuration (XML format or ZIP format), a backup configuration (ZIP format only), or a configuration checkpoint. When you compare configurations, the report provides a list of objects that changed between the two configurations and the changes that were made to these objects. The report list how the configuration changed: v An object was added v An object was deleted v An object was modified Comparing configurations To compare configurations, use the following procedure: 1. Select Administration Configuration Compare Configuration to display the Configuration Comparison screen. 2. From the From list, select which configuration to be the first configuration source; and from the To list, select which configuration to be the second configuration source. The source for each of the configurations can be one of the following: Persisted Configuration The last saved configuration on the appliance. This is the default in the From list. Running Configuration The configuration that is currently running on the appliance. This is the default in the To list. Domain Configuration The last saved or currently running domain configuration on the appliance. XML Configuration The XML file that was created during an export operation. This file has an.xcfg extension. Export ZIP Bundle A ZIP file that was created during an export operation. This file has a.zip extension. Backup ZIP Bundle A ZIP file that was created during backup operation. This file has a.zip extension. 52 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Checkpoint A ZIP file that was created through a save checkpoint operation. This file has a.zip extension and is in the chkpoint: directory. 3. When the source (From or To) isxml Configuration, Export ZIP Bundle, or Backup ZIP Bundle, specify or browse for and select the configuration file. Also, create or select a deployment Policy that can be used to accept, filter, or modify a configuration. 4. When the source (From or To) ischeckpoint, select the checkpoint from the Checkpoint list. 5. From the View list, select whether the report lists only changed objects between the configurations or all objects in the configurations. The default is changed objects only. 6. Click Run Comparison to generate the report. The results are displayed below the horizontal rule. Reading the change report After running a comparison, the results are displayed below the horizontal rule. Review the report to determine whether these changes should be saved to the startup configuration, reverted to their original settings, saved to a configuration checkpoint, or a combination of these operations. Each item in the report contains the following data: Type The object type Name The name of the object Property The name of the property From The value of the property as defined in the From source To The value of the property as defined in the To source Change The type of change between the From source and the To source. The change is one of the following values: v modified v added v deleted Beside each item is a check box. Reverting changes After running a comparison and reviewing the results, you can revert select changes or all changes between the two configurations. You can revert changes at the property level only. To revert changes to select properties for an object, use the object-specific configuration screens. To revert changes, use the following procedures: 1. Determine which objects to revert: v To revert select objects, select the check box beside those objects. v To revert all objects, click Select All. 2. Click Undo Selected. Chapter 5. Managing the configuration of the appliance 53

The results are displayed on a new screen. If a selected object is a referenced object, it cannot be deleted until after the deletion of its parent object. You might need to run the comparison multiple times to delete referenced objects. For example, you cannot delete certificates that are referenced by a validation credentials list until after the deletion of the validation credentials list itself. Configuring deployment policies Deployment policies use fine-grained matching statements and clause types to control the inclusion of configuration data from imported configuration packages. Depending on the clause type, the deployment policy can perform the follow types configuration management against the imported configuration package: v v v Use an accepted configuration to include resources in the package that match specified criteria. Use a filtered configuration to delete resources in the package that match specified criteria. Use a modified configuration to modify resources in the package that match the specified criteria. Modified configurations support the following actions: Add Adds the property with the identified value during the import. Changed Substitutes the value for the identified property during the import. Deleted Deletes the property during the import. The processing sequence is as follows: 1. Process the accepted configuration, the whitelist, to always include resources that match. 2. Process the filtered configuration, the blacklist, to always delete resources that match. 3. Process the modified configuration to change the resources based on the defined action type. Creating a Deployment Policy object A deployment policy is a sequence of accepted, filtered, and modified configurations that respectively include, delete, or change configuration data in the configuration package during the import. When specifying the matching statement, you can use the builder or manually specify the statement. v v For details about using the builder to define the statement, refer to Using the deployment policy builder on page 55. For details about manually specifying the statement, refer to Specifying the matching statement on page 56. Note: You cannot modify the administrative state of Deployment Policy objects. To create a Deployment Policy object, use the following procedure: 1. Select Objects Configuration Management Deployment Policy to display the catalog. 2. Click Add to display the configuration screen. 54 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

3. Specify the name of the object in the Name field. 4. Specify a descriptive object-specific summary in the Comment field. 5. Define accept clauses. a. Specify the matching statement in the Accepted Configuration field, or click Build. b. Click Add. Repeat this step to define another accept clause. 6. Define filter clauses. a. Specify the matching statement in the Filtered Configuration field, or click Build. b. Click Add. Repeat this step to define another filter clause. 7. Define modify clauses on the Modified Configuration tab. a. Click Add to display the Modified Configuration property window. b. Specify the matching statement for the modify clause in the Configuration Match field, or click Build. c. Select the type of configuration modification from the Modification Type list. Add Configuration Adds a configuration setting. Delete Configuration Deletes a configuration setting. Change Configuration Changes a configuration setting. d. If adding a configuration, specify the name of the property to add in the Configuration Property field. e. If adding or changing a configuration, specify the value of the property to add or modify in the Configuration Value field. f. Click Save to return to the configuration screen. Repeat this step to define another modify clause. 8. Click Apply to save the object to the running configuration. 9. Optionally, click Save Config to save the object to the startup configuration. Using the deployment policy builder Deployment policies include a builder to help create matching statements in the following format: address/domain/resource[?name=resource-name &Property=property-name&Value=property-value] To access the builder, click Build. This button is associated with the following properties: v Accepted Configuration on the Main tab v Filtered Configuration on the Main tab v Configuration Match in the properties Window that the WebGUI displays after clicking Add on the Modified Configuration tab To create a matching statement with the builder, use the following procedure: 1. Click Build to open the builder. Chapter 5. Managing the configuration of the appliance 55

2. Specify the IP address or host alias in the Device Address field. The value * matches all IP addresses. 3. Select the name of the application domain from the Application Domain list. The selection (none) matches all domains. 4. Select the resource type from the Resource Type list. The select (all resources) matches all resource types. 5. Optionally specify a name match for a resource in the Name Match (PCRE) field. This property limits the matching statement to resources of the specified name. Use a PCRE to select groups of resource instances. For example, foo* would match all resources with names that start with foo. 6. Optionally specify the name of the configuration property in the Configuration Property field. This property limits the matching statement to resources of the specified property. 7. Optionally specify the value for the configuration property in the Configuration Value Match (PCRE) field. This property limits the matching statement to resources of the specified value. Use a PCRE Match Expression to select groups of configuration property values. 8. Click Save. The statement is added to the list of matching statements. Specifying the matching statement Instead of using the builder, you can manually specify the matching statement. Matching statements have the following format: address/domain/resource[?name=resource-name &Property=property-name&Value=property-value] address Specifies the IP address or host alias. The value * matches all IP addresses. domain Specifies the name of the application domain. The value * matches all domains. resource Specifies the resource type. The value * matches all resource types. Name=resource-name Optionally specifies a name match for a resource. This property limits the matching statement to resources of the specified name. Use a PCRE to select groups of resource instances. For example, foo* would match all resources with names that start with foo. Property=property-name Optionally specifies the name of the configuration property. This property limits the matching statement to resources of the specified property. Value=property-value Optionally specifies the value for the configuration property. This property limits the matching statement to resources of the specified property. PCRE documentation is available at the following Web site: http://www.pcre.org 56 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Appendix A. Referenced objects AAA Policy 1. Select Objects XML Processing AAA policy to display the AAA Policy catalog. 2. Click Add to display the AAA Policy Configuration (Main) screen. Use this screen to provide policy-wide, global configuration data. 3. Click the Identify tab to define how to extract the identity. 4. Click the Authenticate tab to define how to authenticate the identity. 5. Click the Map Credentials tab to how to map the credential. 6. Click the Resource tab to define how to extract the resource. 7. Click the Map Resource tab to define how to map the resource. 8. Click the Authorize tab to define how to authorize the credential. 9. Optionally click the Post Processing tab to define post processing activities. 10. Optionally click the Namespace Mapping tab to define how to map namespaces. 11. Optionally click the SAML Attributes tab to define SAML attributes. 12. Optionally click the LTPA User Attributes tab to define LTPA user attributes. 13. Optionally click the Transaction Priority tab to define the priority of transactions. 14. Click Apply to save the object to the running configuration. 15. Optionally, click Save Config to save the object to the startup configuration. Main tab Name Specify the name of the object. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Authorized counter Optionally select a message-count monitor. This object monitors and controls incoming messages authorized by this AAA Policy. This counter should Measure type XPath to allow the AAA Policy to increment the counter on successful authorization. Refer to Count Monitor on page 99 for more information. Rejected counter Optionally select a message-count monitor This object monitors and controls incoming messages rejected by this AAA Policy. This counter should Measure type XPath to allow the AAA Policy to increment the counter on rejected authorization. Click Rejected Counter Tool to configure a counter for this purpose. Refer to Count Monitor on page 99 for more information. SAML Signature Validation Credentials Optionally (and only if SAML-based identity extraction, authentication, Copyright IBM Corp. 2002, 2009 57

and authorization is used by this AAA policy), select the Crypto Validation Credentials used to validate digitally-signed SAML assertions from the Credentials list. Refer to Working with Validation Credentials objects on page 21 for more information. SAML Message Signing Key Optionally if SAML-based identity extraction, authentication, or authorization is used by this AAA Policy, select a crypto key used to sign SAML assertions. Refer to Defining Key objects on page 16 for more information. SAML Message Signing Certificate Optionally if SAML-based identity extraction, authentication, or authorization is used by this AAA Policy, select the matching crypto certificate that is the public certificate associated with the private key designated by the SAML message signing key. Refer to Defining Certificate objects on page 13 for more information. SAML Signing Message Digest Algorithm Select the hash algorithm for SAML signing message. The default is sha1. SAML Message Signing Algorithm Select the algorithm to sign SAML messages. RSA and DSA are supported by older releases. rsa is same as rsa-sha1, and dsa is same as dsa-sha1. The default is rsa. LDAP Suffix Optional if LDAP authentication or authorization is used by this AAA policy. Specify an LDAP base DN. LDAP-based authentication implementations require an X.500 DN (for example, cn=alice,dc=datapower,dc=com) and a password. When configuring LDAP for authentication, it is typical to create a base DN (such as dc=datapower,dc=com) and then create one entry under this base for each user. To make LDAP authentication more usable, the AAA policy provides the LDAP suffix. Set the LDAP suffix to the base name under which user entries are found. If the LDAP suffix is not an empty string, the AAA Policy builds an X.509-compliant DN by prepending cn= to the surname and appending a comma followed by the value of the LDAP suffix. Hence, an LDAP suffix of dc=datapower,dc=com, the user name Alice is mapped to the DN cn=alice,dc=datapower,dc=com. Log Allowed By default, the AAA policy generates log messages at the indicated level for every access allowed. Set to off to change this behavior. Log Allowed Level When Log Allowed set to on, change the default level. Log messages generated for each access allowed by this AAA policy will be set at the level selected. Log Rejected By default, the AAA policy generates log messages at the indicated level for every access rejected. Set to off to change this behavior. Log Rejected Level When Log Rejected set to on, change the level. Log messages generated for each access rejected by this AAA policy will be set at the level selected. 58 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Note: Log targets capture messages at or above the level configured for the target. The higher the level, the more likely one or more log targets will catch the message. To be sure log targets capture these AAA messages, coordinate these levels. WS-Trust Encryption Recipient Certificate When generating a WS-Trust token for a secret key (such as a WS-SecureConversation token), select the key to encrypt the initial secret. SAML Artifact Mapping File This file contains a map of SAML artifact source identifiers to artifact retrieval endpoints. This property is required only when artifacts will be retrieved from multiple endpoints and the source identifiers for these endpoints are encoded in the artifact itself (per the SAML specification). If there is only one artifact retrieval URL, it can be specified by the SAML artifact responder URL in the authentication phase. Ping Identity Compatibility Select whether to enable (on) or disable (off) Ping Identity compatibility. Enable Ping Identity compatibility when using SAML for authentication or authorization. SAML 2.0 Metadata File This file contains information about the various SAML Authorities that might be used for SAML 2.0 authentication and authorization. From the list, select a file, and click Upload to upload a file. The file must conform to the SAML 2.0 metadata schema (xmlns:md="urn:oasis:names:tc:saml:2.0:metadata"). DoS Flooding-Attack Valve Specifies the number of times to perform the same XML processing per user request. Use a value in the range of 1 through 1000. The default is 3. This property limits the number of times to perform the same XML processing per user request. XML processing includes encryption, decryption, message signing, and signature validation. At this time, the AAA Policy supports this property in the following cases: v Identity extraction when the method is Subject DN from Certificate in the Message s signature v Authentication when the method is Validate the Signer Certificate for a Digitally Signed Message When used with the value of 1, the AAA Policy extracts the first signature and its first reference from the security header and ignores all other signatures or signing references. If the security header contains more signatures or a single signature contains more signing references, these signatures and signing references are ignored. During signature verification, the processing fails if the needed signature is not part of extracted identity. For example if dos-valve is 2 and the needed information to verify the signature was the third signing reference, the verification would fail. However if the information was the second signing reference, the verification would succeed. LDAP Version Select the LDAP protocol version (2, the default version, or 3) used when accessing the authorization server. Appendix A. Referenced objects 59

Enforce Actor/Role for WS-Sec Message Most of the times a WS-Security message has a S11:actor or S12:role attribute for its wsse:security header, we can enforce those attributes when AAA tries to use wsse:security header, for example, there should be only one wsse:security element having same actor/role, and AAA should only process the wsse:security header for the designated Actor/Role Identifier. This setting takes effect for all AAA processing except post processing. The default is on. WS-Sec Actor/Role Identifier When enforcing WS-Security Actor/Role, specify the identifier. Continue with defining the identity extraction method. Identity tab The initial processing performed by an AAA Policy consists of extracting information from an incoming message and its protocol envelope(s) about the claimed identity of the service requester. Use the Identity panel to specify the method or methods used by the AAA Policy to extract the identity claimed by the service requester. Click the Identity tab to display the AAA Policy Configuration (Identity) screen. Use the check boxes to enable (on) or disable (off) one or more identification methods. HTTP s Authentication header The claimed identity of the requester is extracted from the HTTP Authorization header (name and password). If selected, the WebGUI prompts for the following property: HTTP s Basic Authentication Realm The name of the HTTP Basic Authentication Realm as described by RFC 2617, HTTP Authentication: Basic and Digest Access Authentication. A browser might display this name to help determine which credentials to supply. UserName element from WS-Security header The claimed identity of the requester is extracted from the WS-Security UserName element (name and password) contained in a SOAP header. BinarySecurityToken element from WS-Security header The claimed identity of the requester is extracted from the WS-Security BinarySecurityToken element (using the token s string value as the claimed identity) contained in a SOAP header. WS-SecureConversation Identifier The claimed identity of the requester is extracted from a WS-SecureConversation Identifier. WS-Trust Base or Supporting Token The claimed identity of the requester is extracted from a WS-Trust Base or Supporting token. Kerberos AP-REQ from WS-Security header The claimed identity of the requester is extracted from a Kerberos AP-REQ contained in the WS-Security header. 60 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Kerberos AP-REQ from SPNEGO token The claimed identity of the requester is extracted from a Kerberos AP-REQ contained in the SPNEGO token. Subject DN of the SSL Client Certificate from the Connection Peer The claimed identity of the requester is extracted from the SSL client certificate presented during the SSL handshake. If this is checked, the Validation Credentials for Signing Certificate appears. Name from SAML attribute assertion The claimed identity of the requester is extracted from a SAML assertion that contains a SAML attribute statement. The name contained in the Subject element of the attribute statement is used as the claimed identity. Name from SAML authentication assertion The claimed identity of the requester is extracted from a SAML assertion that contains a SAML authentication statement. The name contained in the Subject element of the authentication statement is used as the claimed identity. SAML artifact The claimed identity of the requester is extracted from a SAML artifact. Client IP address The client s IP address is used for identity extraction. Subject DN from the certificate in the message s signature The claimed identity of the requester is extracted from a certificate used to validate a digitally-signed message verify the signature validity, if the signature is valid, use the Subject DN extracted from the certificate associated with the signature as the claimed identity. If this is checked, the Validation Credentials for Signing Certificate field is displayed. If selected, the WebGUI prompts for the following property: Validation Credentials for Signing Certificate Select the Validation Credentials List used to validate the presented certificate. Refer to Defining Identification Credentials objects on page 15 for more information. Token extracted from the message The claimed identity of the requester is extracted using an XPath expression. If this is checked, the XPath Expression field is displayed. If selected, the WebGUI prompts for the following property: XPath expression Provide the operative XPath expression. The XPath expression is applied to the entire message. If you require name spaces in the XPath expression, refer to Namespace Mapping tab on page 80 for procedural and configuration details. Token extracted as Cookie value The claimed identity of the requester is extracted from a Cookie value. If selected, the WebGUI prompts for the following property: Cookie name Specify the cookie name. LTPA Token The claimed identity of the requester is extracted from an LTPA (Lightweight Third Party Authentication) token value. LTPA tokens, which are opaque Appendix A. Referenced objects 61

signed and encrypted strings, are carried via HTTP, specifically in the Set-Cookie response and Cookie request headers. Refer to Understanding LTPA for more information. Custom template The claimed identity of the requester is extracted by a custom or proprietary identification resource (for example, a style sheet). If selected, the WebGUI prompts for the following property: Custom URL Specify the local or remote URL of the identification resource. Click Apply to commit AAA Policy properties. Optionally, click Save Config to save the object to the startup configuration. Authenticate tab After extracting the claimed identity of the service requester, an AAA Policy authenticates the claimed identity. The authentication process can use internal or external resources. Use the Authenticate panel to designate the authentication method. 1. Click the Authenticate tab to display the AAA Policy Configuration (Authenticate) screen. 2. From the Method list, select an authentication method. Accept a SAML Assertion with a Valid Signature The requester is authenticated by a SAML assertion with a valid signature. Accept an LTPA token The requester is authenticated by an encrypted LTPA token. If selected, the WebGUI prompts for the following property values: LTPA Token Versions Specifies the LTPA formats supported for authentication purposes. Use the check boxes to specify the LTPA versions that are supported for authentication. Select at least one version, or all LTPA-based authentication will fail. Because the LTPA token must be decrypted before authentication, the following properties identify the needed cryptographic resources. LTPA Key File Provide the name of the file that contains the cipher keys to be used for encryption and decryption. LTPA Key File Password and Confirm LTPA Key File Password Provides the cleartext password to the LTPA key file. Refer to Understanding LTPA for more information. Bind to Specified LDAP Server (Default) The requester is authenticated by an LDAP server. If selected, the WebGUI prompts for the following properties: Host Specify the IP address or domain name of the LDAP authentication server. 62 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Port Specify the LDAP authentication server port number. If not supplied, defaults to the canonical port number. LDAP Prefix Optionally specify an LDAP Prefix name. This string is prepended to the identity extracted before submission to the LDAP server. The default is cn=. This property is relevant when the Search for DN is off. LDAP Suffix Optionally specify an LDAP Suffix name. This suffix string is appended to the identity extracted before submission to the LDAP server. For example, o=datapower.com. This property is relevant when the Search for DN is off. LDAP Load Balancer Group Optionally select a Load Balancer Group. If you select a group, LDAP queries will be load balanced in accordance with the settings in the group. Load balancing allows for failover. Refer to Load Balancer Group on page 101 for more information. When specified, this property overrides the settings for the Host and Port properties. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server. Retain the default value to use a non-ssl connection. LDAP Bind DN Specify the Distinguished Name for the LDAP bind operation. LDAP Bind Password and Confirm LDAP Bind Password Specify and confirm the password for the LDAP bind operation. LDAP Search Attribute Specify the name of the LDAP attribute that contains the cleartext password. The default is userpassword. This property is meaningful only when the identity extraction method is Password-carrying UsernameToken Element from WS-Security Header and the <Username> element in the header has the Type attribute set to PasswordDigest. In this case, the LDAP server returns the text in the specified LDAP attribute for the user in the UsernameToken. If the hashed value of the returned text does not match the value in the <Password> element, authentication fails. Search for DN Indicate whether to perform an LDAP search retrieve the DN of the user. on off Enables an LDAP search for the user s group. The login name of the user along with the LDAP Search Parameters will be used as part of an LDAP search to retrieve the user s DN. (Default) Disables an LDAP search for the user s group. The login name of the user along with the LDAP prefix and the LDAP suffix will be used to construct the user s DN. Appendix A. Referenced objects 63

v If on, the WebGUI displays the following field. LDAP Search Parameters Select the LDAP Search Parameters from the list. Refer to Defining an LDAP Search Parameters object on page 100 for detail. v If off, the WebGUI removes the following fields: LDAP Prefix LDAP Suffix Contact a SAML Server for a SAML Authentication Statement The requester is authenticated by issuing a SAML Authentication Query to the appropriate server. If selected, the WebGUI prompts for the following properties: SAML Authentication Query Server Specify the URL of the SAML Authentication Query Server that can authenticate the requesting entity and supply a SAML Authentication Assertion. SAML Version Select the SAML version used for authentication. Versions 1.0, 1.1 and 2.0 are supported. The version selected affects the format of the messages sent to SAML authorities. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server. Retain the default value to use a non-ssl connection. Contact a WS-Trust Server for a WS-Trust Token The requester is authenticated by a WS-Trust token obtained from a WS-Trust server. If selected, the WebGUI prompts for the following properties: WS-Trust Token Server Specify the URL of the WS-Trust server that can authenticate the requesting entity and supply a WS-Trust token. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server. Retain the default value to use a non-ssl connection. The following properties are relevant for attaching WS-Policy, not for AAA authentication. Require Client Entropy Indicates whether to require client entropy as key material in the WS-Trust request. on Requires client entropy. The DataPower appliance sends an entropy element to the WS-Trust server as part of the security token request exchange. Use the WS-Trust Encryption Certificate property to determine how to include the key material in the request. off (Default) Does not require client entropy. When required, specify the size of the client entropy in bytes in the Client Entropy Size field. The size refers to the length of the 64 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

client entropy before Base64 encoding. Use an integer in the range of 8 through 128. The default is 32. Require Server Entropy Indicates whether to require server entropy in the WS-Trust response. on Requires server entropy. The WS-Trust server must return an entropy element to the DataPower appliance as part of the security token request exchange. off (Default) Does not require server entropy. When required, specify the minimum allowable size of the received entropy material in bytes in the Server Entropy Size field. The size refers to the length of the client entropy before Base64 encoding. Use an integer in the range of 8 through 128. The default is 32. Require RequestSecurityTokenCollection Indicates whether to generate a WS-Trust RequestSecurityToken or a WS-Trust RequestSecurityTokenCollection as part of the security token request exchange. on Generates a WS-Trust RequestSecurityTokenCollection. off (Default) Generates a WS-Trust RequestSecurityToken. Require AppliesTo SOAP Header Indicates whether to generate a WS-Addressing AppliesTo header as part of the security token request exchange. on Generates a WS-Addressing AppliesTo header. off (Default) Does not generate a WS-Addressing AppliesTo header. When required, specify the value for the AppliesTo header in the AppliesTo Header field. WS-Trust Encryption Certificate Optionally select a Crypto Certificate to encrypt WS-Trust elements in the request. If selected, he public key of the certificate encrypts the client entropy key material for the recipient. If blank, the WS-Trust BinarySecret element contains the entropy material. In this case, use an SSL Proxy Profile to secure the message exchange with the WS-Trust server. Contact ClearTrust Server The requester is authenticated via a ClearTrust server. If selected, the WebGUI prompts for the following properties: ClearTrust Server URL Provide a local or remote URL that locates the authentication resource. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server. Retain the default value to use a non-ssl connection. Contact Netegrity SiteMinder The requester is authenticated by a Netegrity server. If selected, the WebGUI prompts for the following properties: Appendix A. Referenced objects 65

Host Specify the IP address or domain name of the Netegrity authentication server. Port Specify the Netegrity authentication server port number. Netegrity Base URI Specify the appropriate URI string. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server. Retain the default value to use a non-ssl connection. Contact NSS for SAF Authentication The requester is authenticated by the SAF. If selected, the WebGUI prompts for the following property: z/os NSS Client Configuration Select the z/os NSS Client object that specifies the details for connecting to the NSS server. Refer to z/os NSS Client on page 144 for more information. Contact Tivoli Access Manager The requester is authenticated by a Tivoli Access Manager. A Tivoli Access Manager object must exist and be in an enabled state for this method to succeed. Refer to IBM Tivoli Access Manager on page 88 for more information. Custom Template The requester is authenticated by a custom/proprietary resource (for example, a style sheet). If selected, the WebGUI prompts for the following property: Custom URL Provide a local or remote URL that locates the authentication resource. Pass Identity Token to the Authorize Step The requester is not authenticated by this AAA policy, the request is passed to the authorization server for disposition. Retrieve SAML Assertions Corresponding to a SAML Browser Artifact The requester is authenticated by a SAML artifact. If selected, the WebGUI prompts for the following properties: SAML Artifact Responder Specify the URL of the SAML Artifact Responder that can authenticate the requesting entity using the artifact supplied. SAML Version Select the SAML version used for authentication. Versions 1.0, 1.1 and 2.0 are supported. The version selected affects the format of the messages sent to SAML authorities. SAML 2 Issuer Specify a value that appears in the SAML <samlp:issuer> element after the SAML Artifact has been authenticated. This element is included in the information delivered to the Authorize phase. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server. Retain the default value to use a non-ssl connection. 66 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Use an Established WS-SecureConversation Security Context The requester is authenticated by a WS-SecureConversation token contained in the request. User certificate from BinarySecurityToken The requester is authenticated by a certificate that is included with a BinarySecurityToken. If selected, the WebGUI prompts for the following property: X.509 BinarySecurityToken Validation Credentials Select the Validation Credentials to validate the X.509 certificate in the BinarySecurityToken. Refer to Working with Validation Credentials objects on page 21 for more information. Use DataPower AAA Info File The requester is authenticated by an XML file. If selected, the WebGUI prompts for the following properties: AAA Info File URL Specify the location of the XML file used for authentication purposes. To identify a local resource, use the form store:///authfile.xml. To examine a sample AAA Info file, open store:///authfile.xml. Use specified RADIUS Server The requester is authenticated by a RADIUS server. Validate a Kerberos AP-REQ for the Correct Server Principal The requester is authenticated via a Kerberos AP-REQ contained in the WS-Security header. If selected, the WebGUI prompts for the following properties: Kerberos principal name Provide the name part of the server identity. This value is the server name that is contained in the sname field of the unencrypted portion of the Kerberos ticket. Kerberos keytab Select the Kerberos Keytab File object. This field is required. Validate the Signer Certificate for a Digitally Signed Message The signature requires validation. If selected, the WebGUI prompts for the following properties: Signature Validation Credentials Use a Validation Credentials List. XPath Expression Use the specified XPath expression. Validate the SSL Certificate from the Connection Peer The requester is authenticated via its client SSL credentials. If selected, the WebGUI prompts for the following property: SSL Client Validation Credentials Select the Validation Credentials List used to validate offered client certificates. Refer to Working with Validation Credentials objects on page 21 for more information. The following inputs are displayed for all methods. Appendix A. Referenced objects 67

Cache authentication results Select the caching strategy. By default, authentication information from remote resources is cached for a period of three seconds. On authentication failure, authentication information is removed from the cache. Absolute (Default) Caches all authentication data with an explicit TTL (time-to-live), specified by the Cache Lifetime property. Disabled Disables caching of authentication data Maximum Compares the explicit TTL with the received TTL (if any). Use the data-specific TTL if it is less than the explicit TTL. Otherwise, use the explicit value. Minimum Compares the explicit TTL specified by the Cache Lifetime property with the received TTL (if any). Use the data-specific TTL if it is greater than the explicit TTL. Otherwise, use the explicit value. Cache Lifetime Specify the explicit TTL in seconds. This defaults to 3. 3. Click Apply to commit AAA Policy properties. 4. Optionally, click Save Config to save the object to the startup configuration. Map Credentials tab After receiving authentication credentials, an AAA Policy can optionally map these credentials. It might be necessary to map credentials presented by an authentication method to a format congruent with a different authorization method; for example, mapping an authenticated account name/password to an LDAP group. To perform such credentials mapping, an AAA Policy uses custom XML or XPath resources, which you identify during policy definition. If credentials mapping is necessary, use the Map Credentials panel to designate the mapping method and resource. 1. Click the MapCredentials tab to display the AAA Policy Configuration (Map Credentials) screen. 2. From the Method list, select a credentials mapping method. Custom The authentication credentials are mapped by a custom/proprietary resource (for example, a style sheet). If selected, the WebGUI prompts for the following property: Custom URL Provide a local or remote URL that locates the mapping resource. None Authentication credentials are not mapped. Credentials from Tivoli Federated Identity Manager The authentication credentials are mapped by Tivoli Federated Identity Manager (TFIM). If selected, the WebGUI prompts for the following property: 68 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

TFIM Configuration Select an existing TFIM object. Refer to IBM Tivoli Federated Identity Manager on page 90 for more information. Credentials from WS-SecureConversation Token The authentication credentials are mapped via a WS-SecureConversation exchange. AAA Info File The authentication credentials are mapped using an XML file as the mapping resource. If selected, the WebGUI prompts for the following property: AAA Info File URL Specify the location of the XML file used for authentication purposes. To identify a local resource, use the form store:///authfile.xml. Open store://authfile.xml to examine a sample AAA Info file. Apply XPath Expression The authentication credentials are mapped using an XPath expression as the mapping resource. If selected, the WebGUI prompts for the following property: XPath Expression Specify the operative XPath expression. 3. Click Apply to commit AAA Policy properties. 4. Optionally, click Save Config to save the object to the startup configuration. Resource tab After authenticating a client, an AAA policy identifies the specific resource being requested by that client. Use the Resource panel to designate the methods used to identify the resource requested by an authenticated client. 1. Click the Resource tab to display the AAA Policy Configuration (Resource) screen. 2. Use the check boxes to enable (on) or disable (off) one or more resource identification methods. URL sent to back end The identity of the requested resource is extracted from the (possibly rewritten) URL sent to the server. The URL can be rewritten by a URL Rewrite Policy attached to the service or by another processing action before the AAA Policy. URL sent by client The identity of the requested resource is extracted from the original URL sent by the client. This URL has not been rewritten. URI of toplevel element in the message The identity of the requested resource is extracted from the namespace of the top level application element Local name of request element The identity of the requested resource is extracted from the simple name of the top level application element Appendix A. Referenced objects 69

HTTP operation (GET/POST) The identity of the requested resource is extracted from the HTTP method of the client request XPath expression The identity of the requested resource is extracted from the client request by an XPath expression. If selected, the WebGUI prompts for the following property: XPath Expression Specify the operative XPath expression. 3. Click Apply to commit AAA Policy properties. 4. Optionally, click Save Config to save the object to the startup configuration. Map Resource tab After identifying the requested resource, it might be necessary to map extracted resource identities to a form compatible with the authorization method. If resource identity mapping is necessary, use the Map Resource panel to designate the mapping method. 1. Click the Map Resource tab to display the AAA Policy Configuration (Map Resource) screen. 2. From the Method list, select a resource mapping method. Custom The identified resource is mapped by a custom/proprietary resource (for example, a style sheet). If selected, the WebGUI prompts for the following property: Custom URL Provide a local or remote URL that locates the mapping resource. None Identified resources are not mapped. AAA Info File The identified resource is mapped using an XML file as the mapping resource. If selected, the WebGUI prompts for the following property: AAA Info File URL Specify the location of the XML file used for authentication purposes. To identify a local resource, use the form store:///authfile.xml. To examine a sample AAA info file, open store:///authfile.xml. Apply XPath Expression The identified resource is mapped using an XPath expression as the mapping resource. If selected, the WebGUI prompts for the following property: XPath Expression Specify the operative XPath expression. 3. Click Apply to commit AAA Policy properties. 4. Optionally, click Save Config to save the object to the startup configuration. 70 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Authorize tab After authenticating a service requester and extracting the identity of the requested resource, an AAA Policy next authorizes the client, that is, determines if the authenticated service requester is allowed access to the requested resource. The authorization process can use internal or external resources. Use the Authorize panel to designate the authorization method. 1. Click Authorize to display the AAA Policy Configuration (Authorize) screen. 2. From the Method list, select an authentication method. Allow Any Authenticated Client Any authenticated used is authorized. Contact ClearTrust Server The requester is authorized via a ClearTrust server. If selected, the WebGUI prompts for the following properties: ClearTrust Server URL Specify a local or remote URL that locates the authorization resource. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authorization server. Retain the default value to use a non-ssl connection. Custom Template The requester is authorized by a custom/proprietary resource (for example, a style sheet). If selected, the WebGUI prompts for the following property: Custom URL Specify a local or remote URL that locates the authorization resource. Check for Membership in an LDAP Group The requester is authorized by an LDAP server. If selected, the WebGUI prompts for the following properties: Host Specify the IP address or domain name of the LDAP authentication server. Port Specify the LDAP authentication server port number. If not specified, defaults to the canonical port number. Group DN Specify the Distinguished Name of the LDAP group. LDAP Load Balancer Group Optionally select a Load Balancer Group. If a group is selected, LDAP queries will be load balanced in accordance with the settings in the group. Load balancing allows for failover when using LDAP for authorization. LDAP Bind DN Specify the Distinguished Name for the LDAP Bind. LDAP Bind Password and Confirm Bind Password Specify and confirm the password for the LDAP Bind. Appendix A. Referenced objects 71

LDAP Group Attribute Specify a GroupAttribute string. The authorizing identity must be presented as the value that corresponds to the attribute. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authorization server. Retain the default value to use a non-ssl connection. LDAP Search Scope Select the depth of the LDAP search. Base Specifies that the search matches only the input itself One Level Specifies that the search matches the search input and any object that is one-level below Subtree (Default) Specifies that the search matches the input and any descendents LDAP Search Filter Optionally enable the specification of an LDAP search filter which allows tailored LDAP searches. LDAP filter syntax is defined in RFC 2254, The String Representation of LDAP Search Filters. Contact Netegrity SiteMinder The requester is authorized by a Netegrity server. If selected, the WebGUI prompts for the following properties: Host Specify the IP address or domain name of the Netegrity authorization server. Port Specify the Netegrity authorization server port number. Netegrity Base URI Specify the appropriate URI string. Netegrity Operation Name Extension The Netegrity Base URI is combined with the Host, Port, and Netegrity Operation Name Extension configuration items to form the URL for attempting Netegrity authentication. The URL is of the following form: http://host:port/netegritybaseuri/operationnetegrityopnameextension where NetegrityOpNameExtension is directly appended to the operation name. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authorization server. Retain the default value to use a non-ssl connection. Contact NSS for SAF Authorization The requester is authorized by the SAF. If selected, the WebGUI prompts for the following properties: 72 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

z/os NSS Client Configuration Select the z/os NSS Client object that specifies the details for connecting to the NSS server. Refer to z/os NSS Client on page 144 for more information. Default Action Select the default action to specify the access level to the resource. The default is r (Read). The value specified by this property can be programmatically overridden by setting the var://context/aaa/az-zosnss-operation variable to one of the valid values. a (Alter) c (Control) r (Read) u (Update) Always Allow All messages are forwarded to the backend server. Generate a SAML Attribute Query The requester is authorized by a SAML attribute query/response exchange between the DataPower appliance and a SAML server. If selected, the WebGUI prompts for the following properties: URL Specify the location of the SAML server. SAML Match Select the minimum authorization criteria. All Authorization requires the presence of all configured SAML attributes All-Values Authorization requires that all configured attribute names and values be present in the SAML attribute statement Any Authorization requires the presence of a single SAML attribute Any-Value Authorization requires that a single configured attribute name and value be present in the SAML attribute statement XPath Authorization requires that SAML server responses are evaluated with an XPath expression SAML XPath If SAML Match is XPath, specify the operative XPath expression. SAML Name Qualifier Optionally specify the value of the NameQualifier attribute of the NameIdentifier in the generated SAML query. Some SAML implementations require this value to be present. SAML Version Select the SAML protocol version to use when employing SAML for authorization. Versions 1.0, 1.1 and 2.0 are supported. The version selected affects the format of the messages sent to SAML authorities. Appendix A. Referenced objects 73

SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authorization server. Retain the default value to use a non-ssl connection. Generate a SAML Authorization Query The requester is authorized by a SAML authorization query/response exchange between the DataPower appliance and a SAML server. If selected, the WebGUI prompts for the following properties: URL Specify the location of the SAML server. SAML Match Select the minimum authorization criteria. All Authorization requires the presence of all configured SAML attributes All-Values Authorization requires that all configured attribute names and values be present in the SAML attribute statement Any Authorization requires the presence of a single SAML attribute Any-Value Authorization requires that a single configured attribute name and value be present in the SAML attribute statement XPath Authorization requires that SAML server responses are evaluated with an XPath expression SAML XPath If SAML Match is XPath, specifies the operative XPath expression SAML Name Qualifier Optionally specify the value of the NameQualifier attribute of the NameIdentifier in the generated SAML query. Some SAML implementations require this value to be present. SAML Version Select the SAML protocol version to use when employing SAML for authorization. Versions 1.0, 1.1 and 2.0 are supported. The version selected affects the format of the messages sent to SAML authorities. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authorization server. Retain the default value to use a non-ssl connection. Contact Tivoli Access Manager The requester is authorized by a Tivoli Access Manager (TAM). A TAM object must exist for this method to succeed. Refer to IBM Tivoli Access Manager on page 88 for more information. Use SAML Attributes from Authentication The requester is authorized by the same SAML authentication or attribute statements used to authenticate the requester. If selected, the WebGUI prompts for the following property: SAML Match Select the minimum authorization criteria. 74 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

All Authorization requires the presence of all configured SAML attributes All-Values Authorization requires that all configured attribute names and values be present in the SAML attribute statement Any Authorization requires the presence of a single SAML attribute Any-Value Authorization requires that a single configured attribute name and value be present in the SAML attribute statement XPath Authorization requires that SAML server responses are evaluated with an XPath expression SAML XPath If SAML Match is XPath, specifies the operative XPath expression Use XACML Authorization Decision The requester is authorized by an XACML Policy Decision Point (PDP), which might be configured and located on the DataPower appliance, or which might reside on a remote network appliance. If selected, the WebGUI prompts for the following properties: XACML Version Select the XACML version (1.0 or 2.0, the default) used for communications between the PDP and this AAA Policy, acting as an XACML Policy Enforcement Point (PEP). PEP Type Select how the AAA Policy, acting as an XACML PEP, processes the PDP authorization response. Base PEP If the XACML response to the authorization request is permit, the client is authorized; if the permit response is accompanied by obligations, the client is authorized only if the AAA Policy, acting as a PEP, can understand and discharge the conditions. If the XACML response to the authorization request is deny, the client is rejected; if the deny response is accompanied by obligations, the client is rejected only if the AAA Policy, acting as a PEP, can understand and discharge the conditions. Deny-biased PEP If the XACML response to the authorization request is permit, the client is authorized; if the permit response is accompanied by obligations, the client is authorized only if the AAA Policy, acting as a PEP, can understand and discharge the conditions. Any other XACML response results in the client s rejection. Permit-biased PEP If the XACML response to the authorization request is deny, the client is rejected; if the deny response is accompanied by Appendix A. Referenced objects 75

obligations, the client is rejected only if the AAA Policy, acting as a PEP, can understand and discharge the conditions. Any other XACML response results in the client s authorization. Use On Box PDP Use this toggle to specify the location of the PDP. on off (Default) Specifies use of a local PDP. If selected, the WebGUI displays the following property: Policy Decision Point Select the PDP to provide authorization services for the AAA Policy. Refer to XACML Policy Decision Point on page 95 for more information. Specifies the use of a remote XACML PDP. If selected, the WebGUI displays the following property value: URL of External Policy Decision Point Specify the URL to which to send XACML-based authorization requests. PDP Requires SAML 2.0 Use this toggle to force the use of the SAML2.0 Profile. Meaningful only when the XACML version is 2.0. on Forces the use of the SAML2.0 profile. off (Default) Does not require the use of the SAML2.0 profile. SOAP Enveloping Use the toggle to determine whether the external PDP requires SOAP enveloping. If the custom binding style sheet generated SOAP enveloping, retain the default setting. on Before the PEP posts the context request to the external PDP with the HTTP POST method, the SOAP Body of the content request is wrapped by the <xacml-samlp:xacmlauthzdecisionquery> SAML Profile element. off (Default) The PEP posts the context request to the external PDP with the HTTP POST method. This property can be combined with the PDP Requires SAML 2.0 property when the XACML request is wrapped by the <xacml-samlp:xacmlauthzdecisionquery> SAML Profile element. AAA XACML Binding Method Retain the default value, which is the only supported option. Custom Stylesheet to Bind AAA and XACML Select the custom style sheet that maps the AAA result or input message to the XACML context request. This context request contacts the PDP for an XACML decision. 76 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Obligation Fulfillment Custom Stylesheet Specify the custom style sheet to parse any obligation that accompany an authorization decision that is received from the PEP. AAA Info File The requester is authorized by an XML file. If selected, the WebGUI prompts for the following property: AAA Info File URL Specify the location of the XML file used for authorization purposes. To identify a local resource, use the form store:///authfile.xml. To example a sample AAA Info file, open store:///authfile.xml. The following inputs appear for all methods. Cache authorization results Select the caching strategy. By default, authorization information from remote resources is cached for a period of three seconds. On authorization failure, authorization information is removed from the cache. Absolute (Default) Caches all authorization data with an explicit TTL (time-to-live), specified by the Cache Lifetime property Disabled Disables caching of authorization data Maximum Compares the explicit TTL with the received TTL (if any). Use the data-specific TTL if it is less than the explicit TTL. Otherwise, use the explicit value. Minimum Compares the explicit TTL (specified by the Cache Lifetime property) with the received TTL (if any). Use the data-specific TTL if it is greater than the explicit TTL. Otherwise, use the explicit value. Cache Lifetime Specify the explicit TTL in seconds. Defaults to 3. 3. Click Apply to commit AAA Policy properties. 4. Optionally, click Save Config to save the object to the startup configuration. Post Processing tab After authorizing the client, an AAA Policy can perform postprocessing activities. For example, it could generate a SAML authentication assertion and place that assertion in the header of the message. Use the Post Processing panel to specify postprocessing behavior. 1. Click the Post Processing tab to display the AAA Policy Configuration (Post Processing) screen. 2. Provide the following inputs: Run custom post processing stylesheet Select whether to enable (on) or disable (off) custom (style sheet-based) postprocessing. If selected, the WebGUI prompts for the following property: Appendix A. Referenced objects 77

Custom URL If custom post processing is enabled, specify a local or remote URL that locates the style sheet. Generate SAML Authentication Assertion Select whether to enable (on) or disable (off) the generation of SAML authentication assertions. If selected, the WebGUI prompts for the following properties: Issuer for generated SAML assertions If generation of SAML authentication assertions is enabled, Optionally specify the assertion originator or retain the default value, XS. SAML Name Qualifier If generation of SAML authentication assertions is enabled, Optionally specify a NameQualifier as defined by the SAML protocol version selected. SAML Version If generation of SAML authentication assertions is enabled, select the SAML protocol version to use when employing SAML for authentication. Versions 1.0, 1.1 and 2.0 are supported. The version selected affects the format of the messages sent to SAML authorities. Include a WS-Security Kerberos AP-REQ token Select whether to enable (on) or disable (off) the inclusion of a WS-Security Kerberos AP-REQ token, attesting to the authenticity of the requesting client, in the appliance transmission to the target server. If selected, the WebGUI prompts for the following properties: Kerberos client principal Provide the name part of the client s identity (the client name contained in the cname field of the unencrypted portion of the Kerberos ticket). Kerberos client password If obtaining a Kerberos ticket for the requesting client, specify the client Kerberos password (the shared secret known only to the requesting client and the Kerberos Key Distribution Center). Specify the shared secret in the upper field and confirm the entry in the lower field. Kerberos server principal Provide the name part of the server s identity (the server name contained in the cname field of the unencrypted portion of the Kerberos ticket). Kerberos Client Keytab Provide the location of the Kerberos keytab. Generate requested WS-Trust token Set to on to generate a WS-Trust token after authentication and authorization has taken place. This token can serve as WS-SecureConversation token. If selected, the WebGUI prompts for the following properties: Generate token timestamp If generation of WS-Trust tokens is enabled, set to on to generate a WS-Trust token timestamp. 78 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Allow WS-Trust token renewal If generation of WS-Trust tokens is enabled, set to on to allow for the renewal of the WS-Trust token. Send SAML Logout Message (SAML 2.0 only) Click on to enable SAML Version 2.0 Single Logout. If selected, the WebGUI prompts for the following properties: SAML Logout Message Session Authority Specify the URL of the SAML authority to which to send the logout message. SSL Proxy Profile Optionally select the SSL Profile to support a secure connection to the SAML authority. Add WS-Security UsernameToken Select whether to enable (on) or disable (off, the default) the inclusion of a WS-Security UsernameToken in the server-bound message. If selected, the WebGUI prompts for the following properties: WS-Security UsernameToken Password Type Select the password type. Text The actual password for the user name, the password hash, or derived password Digest The digest of the password as specified in Web Services Security UsernameToken Profile 1.0 Include Password Select whether to enable (on) or disable (off) the inclusion of the password in the WS-Security Username Token. Generate an LTPA Token Add an LTPA Token to the HTTP headers transmitted to the server. If selected, the WebGUI prompts for the following properties: LTPA Token Version Select the token version/type. Domino LTPA Used in Lotus environments WebSphere Version 1 LTPA Used in WebSphere environments WebSphere Version 2 LTPA (Default), Used in WebSphere environments (introduced in WebSphere Application Server version 5.1.0.2, for z/os, and version 5.1.1, for other platforms) LTPA Token Expiry Specify the LTPA token lifetime (the number of seconds from the cookie creation to its expiration). LTPA Key File Specify the name of the file that contains the cipher keys used for encryption and decryption. LTPA Key File Password and Confirm LTPA Key File Password Provide and confirm the cleartext password to the LTPA key file. Refer to Understanding LTPA for more information. Appendix A. Referenced objects 79

Generate a Kerberos SPNEGO Token Add an Kerberos SPNEGO token to be inserted into the WWW-Authenticate HTTP header sent to the target server. If selected, the WebGUI prompts for the following properties: Kerberos Client Principal Specify the name part of the client s identity (the client name contained in the cname field of the unencrypted portion of the Kerberos ticket). Kerberos Server Principal Specify the name part of the server identity (the server name contained in the cname field of the unencrypted portion of the Kerberos ticket). Kerberos Client Keytab Specify the location of the Kerberos keytab. Refer to Understanding SPNEGO for more information. Request TFIM Token Mapping Select whether to enable or disable token mapping by IBM Tivoli Federated Identity Manager (TFIM). If enabled, the WebGUI prompts for the following property: TFIM Configuration Select an existing TFIM object. Refer to IBM Tivoli Federated Identity Manager on page 90 for more information. 3. Click Apply to commit AAA Policy properties. 4. Optionally, click Save Config to save the object to the startup configuration. Namespace Mapping tab An AAA Policy can use XPath expressions as it processes client requests specifically XPath expressions can be used while: v Identifying service requestors v Mapping authentication credentials v Identifying requested resources v Mapping requested resources v Authorizing an authenticated service requestor Use the Namespace Mapping panel to provide namespace mappings that might be required by XPath expressions. 1. Click the Namespace Mapping tab to display the AAA Policy Configuration (Namespace Mapping). 2. Click Add to display the Namespace Mapping Property window. 3. Provide the following inputs: Prefix Specify the namespace prefix. URI Specify the namespace URI. 4. Click Save to return to the AAA Policy Configuration (Namespace Mapping). 5. Click Apply to commit AAA Policy properties. 6. Optionally, click Save Config to save the object to the startup configuration. 80 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

SAML Attributes tab Use the SAML Attributes panel to provide SAML attribute namespace data. These attribute name mappings and attribute values can be used for authentication and authorization. 1. Click the SAML Attributes tab to display the AAA Policy Configuration (SAML Attributes). 2. Click Add to display the SAML Attributes Property window. 3. Provide the following inputs: Namespace URI Specify the attribute namespace URI. Local Name Specify the attribute name. Attribute Value Specify the appropriate value. 4. Click Save to return to the AAA Policy Configuration (SAML Attributes). 5. Click Apply to commit AAA Policy properties. 6. Optionally, click Save Config to save the object to the startup configuration. LTPA Attributes tab The WebSphere Version 1 and Version 2 LTPA tokens, but not the Domino LTPA token, can optionally contain an extended attribute field, consisting of an arbitrary list of name-value pairs. Such pairs provide a means to transmit additional information about the cookie subject to applications which can decrypt the cookie. Such information, for example, can identify the server which authenticated the user, or specify various user-associated LDAP attributes. If desired, you can use the following procedure to add name-value pairs to the LTPA token. 1. Click the LTPA User Attributes tab to display the LTPA User Attributes catalog. 2. Click Add to display the LTPA User Attributes Property window. a. Specify the attribute name in the LTPA User Attribute Name field. b. Select the method to assign a value to this attribute from the LTPA User Attribute Type field. Static (Default) Use the value explicitly assigned by the value for the LTPA User Attribute Static Value property XPath Use an XPath expression to set the value dynamically c. If XPath is selected, the expression specified in the LTPA User Attribute XPath Value is evaluated against the input context of the AAA action with the result of the evaluation assigned as the value portion of the name-value pair at runtime. d. Use the LTPA User Attribute Static Value property (meaningful only when the attribute type is set to Static) to explicitly set the value assigned to LTPA User Attribute Name e. Use the LTPA User Attribute XPath Value property (meaningful only when the attribute type is set to XPath) to provide the XPath expression used to extract a value dynamically assigned to LTPA User Attribute Name. To assist in creating the XPath expression, click XPath Tool. This tool allows you to upload an XML document and build the expression by pointing at the desired node. If the defined expression contains namespace elements, you can click XPath Binding to provide namespace/prefix data. Appendix A. Referenced objects 81

Refer to Setting namespace mappings (XPath bindings) for more information. Transaction Priority tab Click the Transaction Priority tab to display the Transaction Priority catalog. Click Add to display the Transaction Priority Property window. 1. Specify the name of the mapped credential in the Credential Name field. Note: You might need to use the multistep probe to determine the string for the mapped credential. 2. Select the priority of the transaction from the Transaction Priority list. The default is Normal. 3. Select whether to require authorization with the Require Authorization toggle. The default is off. 4. Click Save to return to the catalog. Setting namespace mappings (XPath bindings) If you need to provide namespace data for XPath expressions, use the following procedure: 1. Click XPath Bindings to display the XPath Bindings catalog. 2. Click Add to display the Namespace Property window. a. Specify the namespace prefix in the Prefix field. b. Specify the namespace URI in the URI field. c. Click Save to return to the XPath Bindings catalog. 3. If necessary, repeat the step 2 to add additional namespace mappings. 4. Click Done to complete the namespace mapping. 5. Click Commit. This commits all changes to the AAA Policy under construction or modification. 6. Click Done to close the confirmation window. Defining SAML attributes To define SAML attributes, use the following procedure: 1. Click SAML Attributes to display the SAML Attributes catalog. 2. To create new SAML attribute, click Add. 3. Define the following properties: Namespace URI The URI for the namespace of the Local Name. Local Name The local attribute name. This name can be used for matching. Attribute Value The attribute value. This value can be used for matching. All of these fields are optional, depending on the specific context or the SAML Match Type selected. 4. Click Save to save the configuration. 5. Repeat step 2 through step 4 to create as many SAML attributes as needed. 6. After defining all SAML attribute, click Done. 82 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Adding LTPA user attributes To add name-value pairs to the LTPA token, use the following procedure: 1. Click LTPA User Attributes to display the catalog. 2. Click Add to display the LTPA User Attributes window. 3. Provide the following inputs: LTPA User Attribute Name Specify the name of the attribute. LTPA User Attribute Type Select the type of attribute. Static (Default) Use the explicitly assigned value. XPath Use an XPath expression to set the value dynamically. If selected, the expression is evaluated against the input context of the AAA action with the result of the evaluation assigned as the value portion of the name-value pair at runtime. LTPA User Attribute Static Value Meaningful only when the type is Static. The explicit value of the attribute. LTPA User Attribute XPath Value Meaningful only when the type is XPath. The XPath expression used to extract a value dynamically. For assistance in creating the XPath expression, click XPath Tool. This tool allows you to load an XML document and build the expression by selecting the desired node. If the defined expression contains namespace elements, click XPath Binding to provide namespace/prefix data. Refer to Setting namespace mappings (XPath bindings) on page 82 for more information. Using an AAA Info file AAA Info File An AAA Info file can be selected as the method for the following steps of an AAA policy: v Authenticate v Map Credentials v Map Resource v Authorize The AAA Info XML file has the following basic structure, which mirrors the steps of an AAA Policy. The following is a reproduction of the AAAInfo.xsd file in the store: directory. <xsd:element name="authenticate" type="tns:authenticatetype" maxoccurs="unbounded"> </xsd:element> <xsd:element name="mapcredentials" type="tns:mapcredentialstype" maxoccurs="unbounded"> </xsd:element> <xsd:element name="mapresource" type="tns:mapresourcetype" maxoccurs="unbounded"> Appendix A. Referenced objects 83

</xsd:element> <xsd:element name="authorize" type="tns:authorizetype" maxoccurs="unbounded"> </xsd:element> Note: Any given XML File could be used for one or more of these operations. Only the part of the file that supports the desired operation needs to be completed. For example, if the file is only used for Map Credentials, it does not need to include an Authenticate, Map Resource, or Authorize section. The schema for an AAA Info file uses the AAAInfo.xsd file in the store: directory. One or more XML files could be used for these operations. In each case, the field that offers the ability to select an XML file has the + and... buttons. These buttons allow for the creation of a new XML file or the editing of an existing XML file, respectively. Clicking either of these buttons launches the AAA Info File Editor. Refer to AAA Info File editor on page 85 for more information. Note: The AAA Info file can be edited outside of the AAA Info File Editor and uploaded to the appliance. Authenticate element: The Authenticate element or elements contain the database of identities that can be authenticated by this file. Identities can be identified by one or more of the following attributes: v User name v Password v IP address or host name v IP network v Distinguished name (DN) v Custom token Each identity is given a credential by this element. MapCredentials element: The MapCredentials element takes in a credential string and maps it to another. The input can be matched by a PCRE regular expression. This element can be fed directly from an Authenticate element contained in this file. Usually, however, this element is used to map an identity extracted from a message to another identity more meaningful to the authorization method. MapResource element: The MapResource element takes in a resource string extracted from the message and maps it to another, perhaps more meaningful to the authorization method. Input resources can be one or more of the following types: v Original (client) URL v URL sent to server (target URL) v SOAP Operation Namespace (request URI) v SOAP Operation Name (request operation) v HTTP method v Token extracted by XPath These resource inputs map to Resource Extraction methods used by the AAA Policy. The input resource name can be matched by a PCRE regular expression. 84 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Authorize element: The Authorize element takes in a Credential and a Resource and returns an access status (allow or deny). Both the Credential and the Resource can be matched by a PCRE regular expression. AAA Info File editor The AAA Info File Editor, launched by the WebGUI, steps through each of these sections in an AAA Info file and helps to configure them. Click Next or Back to move between pages. The AAA Info File Editor has the following pages: v Default credential (unauthenticated identity) v Credentials (authenticated identities) v Map credentials v Map resources v Authorized access to resources v File information At any point, click Cancel to abandon all changes and close the file editor. Default credential (unauthenticated identity): The initial screen presents the opportunity to set the default credentials for unauthenticated identities. This is the credential assigned to identities for which no other credential can be found in the Authenticate section. If left blank, all unauthenticated identities are denied access. Credentials (authenticated identities): The authenticated identities page provides a list of identities that are authenticated by this file. When creating a new file, none are initially listed. Click Next if this file will not be used for authentication. Click Add to create new identities that this file can authenticate. A new window opens with a form for adding identities. Host Name or IP Address The host name or IP address of the client that submitted the message. The IP address takes dotted decimal form w.x.y.z. The entry 0.0.0.0 (or 0) is not allowed. v Use this field only when the identity extraction method is set to Client IP address. v If this field is used, you cannot use the IP Network field. IP Network The IP network of the client that submitted the message. This entry takes the form x.y.z.a/b (for example 192.168.2.25/24). v Use this field only when the identity extraction method is set to Client IP address. v If this field is used, you cannot use the Host Name or IP Address field. User name The user name extracted from the message. User names can be extracted from messages in a number of ways, including HTTP Basic Authentication, WS-Security UserName, and Name from SAML headers. If those AAA Policy identity extraction methods are not used, do not use this field. Password The password extracted from the message. Passwords can be extracted from messages by HTTP Basic Authentication and WS-Security UserName. Appendix A. Referenced objects 85

If the Identity Extraction method used by the AAA Policy does not use either of these methods, do not use this field. Distinguished Name The DN extracted from the message. The AAA Policy identity extraction methods Subject DN from SSL certificate or Subject DN from SAML signature return this value. If those methods are not used, do not use this field. Custom token A custom token is extracted from the message. The AAA Policy identity extraction methods Token extracted from the message and Token extracted as cookie value return this value. If those methods are not used for extraction, do not use this field. Credential Name The credential returned by the authentication. This can be the same as the extracted identity or different. The value should be meaningful either to the AAA Policy Map Credentials method or to the AAA Policy Authorize method. All of the fields that contain information must be matched for the authentication to succeed. If the identity extraction method returns only a user name (such as with SAML) and the Authenticate Identity entry contains both user name and password, authentication will fail. The AAA policy, however, tests an extracted identity against all entries in the order in which they are listed, stopping after it finds a complete match. It is possible to create one entry for user name Bob that also has a password of foo and another with no password entry. Should the extraction method only retrieve the user name and not the password, Bob will still authenticate. Map credentials: The Map Credentials page presents a list of all credential maps contained in the file. When creating a new file, this list is empty. Click Next to move to the next page if this file will not be used for mapping credentials. Click Add to create a new credential map. Input Credential The credential input to the mapping. This field accepts PCRE expressions, allowing a single expression to match more than one input credential. Entering foo causes the AAA policy to match all input credentials that contain the string foo. Credential Name The credential to output in place of the input credential. This is the value to which the input credential is mapped. This is not a regular expression. Click Submit to add the new map to the list of maps. Create as many mapping entries as needed by clicking Add for each new entry. Note: If this file is used for mapping credentials, any input credential that does not match a map is converted to a blank credential for the purposes of authorization. Map resources: The Map Resource page presents a list of all resource mappings contained in the file. Resource mapping is used to map the resource identifier extracted from the message to something else. If the AAA Policy uses more than one resource extraction method, all methods will be executed. 86 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Click Next if this file will not be used for resource identity mapping. Click Add to create a new map. Original URL The URL sent by the client submitting the message. This is a PCRE expression. Target URL The URL used to send the message to the back end server, after the firewall URL Rewrite Policy has executed. This is a PCRE expression. Request URI The Namespace URI of the action or method requested in the body of the SOAP message. This is identified as the topmost element in the SOAP:Body element. Request Operation The name of the operation requested in the body of the SOAP message. HTTP Method Select the desired method. Select any to allow any method. Result of XPath Expression Any value that is extracted from the message by an XPath expression. This is a PCRE expression. Resource The resource string to which the input resource is mapped. This field is required. Note: If this file is used for mapping resources, any resource that does not mapped by the file will be converted to a blank resource for the purposes of authorization. Authorized access to resources: The Authorize page presents a list of all authorization pairs contained in this file. Authorization is based on an input credential (after mapping, if any) and an input resource (after mapping, if any). If this file is not used for authorization, click Next. To create an authorization entry, click Add. Credential The credential to match for authorization. This field accepts PCRE expressions. Resource The resource to match for authorization. This field accepts PCRE expressions. Access Select allow or deny as the authorization result. Note: When this file is used for authorization, access is denied by default. Any unmatched entries result in denied access. Access is allowed only if a match is found and the Access for that match is allow. File Information: The file information page provides a means to name the file and add a comment if desired. This file is typically placed in the local: directory. Appendix A. Referenced objects 87

Confirmation: The last page of the reflects the name of the file and offers the opportunity to make changes or save the changes to the file. v Click Cancel to abandon all changes and close the window. v Click Back to move backward through the file to make any additional changes needed. v Click Commit to save the file and close the window. IBM Tivoli Access Manager Integrating with IBM Tivoli Access Manager (TAM) allows a user to be authenticated using a simple user name and password. Authorization decisions are made for an authenticated user on a resource and an operation. Only authenticated users can receive an authorization decision. In this case, a resource is passed as a string. Note: Integration with TAM requires the presence of a license on the DataPower appliance. An AAA Policy object can use TAM for both authentication and authorization. The AAA policy will not succeed with TAM without first configuring an instance of the TAM object with at least one authorization server replica. Tivoli Access Manager configuration Configuration consists of creating a TAM client configuration file and configuring a TAM object. The configuration files specify the network and security configuration for the policy server, replica authorization servers, and the LDAP (directory) server. During object configuration, the TAM configuration files must reside on the appliance. Although native TAM supports both local and remote clients, the appliance supports only remote client operations. The TAM configuration supports only one policy server and supports only LDAP directories. Although the configuration files allow specifications for Microsoft Active Directory and Lotus Domino, the appliance does not support these directory servers. Tivoli Access Manager security The TAM client supports LDAP along with the proprietary IBM protocol. SSL keys and certificates must be in the proprietary IBM CMS database format and must be uploaded to the appliance. The configuration files identify the location of these files. You do not need to create Key objects or Certificate objects. The files can be placed in the encrypted cert: or sharedcert: flash directories. Creating TAM configuration files Before configuring a TAM object, you need to have the TAM configuration files on the appliance. Both the ASCII and obfuscated versions of the configuration files are needed. You can create TAM configuration files either on the appliance or using the native TAM configuration utilities. The following files are needed to create the TAM object or are created using the appliance: v The ASCII version of the configuration file (.conf extension) v v v The obfuscated version of the configuration file (.conf.obf extension) using the same file name as the ASCII version The TAM SSL key file (.kdb extension) The TAM SSL stash file (.sth extension) 88 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Notes: v v If you use the native TAM configuration utilities to create the configuration files, you might need to modify them before creating the TAM object. During the creation of TAM object, you might need to upload the SSL key file for the LDAP server (.kdb extension). When using secure communication, ensure that this file is on the workstation. Modifying native TAM configuration files: When the configuration files are generated by the native TAM utilities, you might need to make the following modifications: v Unless the LDAP key stash file is uploaded to the appliance, modify the TAM configuration file by defining the ssl-keyfile-pwd entry in the [ldap] stanza. v The TAM object needs at least one authorization server replica. You can create authorization server replicas during the creation of the TAM object, or you can define replica entries in the [manager] stanza. When defined in the configuration file, the replicas are not shown in the Authorization Server Replica catalog. v Ensure that the obfuscated version of the configuration file is on the workstation and is the same name as the ASCII version. If not the same name, ensure that the file entry in the [configuration-database] stanza defines the location of the obfuscated version of the configuration file on the appliance. Creating configuration files on the appliance: To create a TAM configuration file: 1. Select Administration Miscellaneous IBM Tivoli Access Manager Tools to display the action screen. 2. Define the operational properties. Refer to the online help for details. 3. Click Create Tivoli Access Manager Configuration. 4. Follow the prompts. The ASCII version and the obfuscated version of the TAM configuration files are stored in the local: directory. The key file and the stash file that TAM uses are stored in the cert: directory. If you set the Create File Copies to Download property to on, copies of the key file and the stash file are stored in the temporary: directory. Creating and configuring TAM objects After creating the TAM configuration, key, and stash files, you can now create and configure a TAM object. Each TAM object requires at least one authorization server replica. A replica indicates the network location of a remote TAM authorization server. If necessary, configure additional replicas for failover purposes. To create and configure a TAM object: 1. Select Objects Access IBM Tivoli Access Manager to display the catalog. 2. Click Add to display the configuration screen. 3. Define the operational parameters. Refer to the online help for details. 4. Define at least one authorization server replica. a. Click the Authorization Server Replica tab. b. Define a replica. 1) Click Add to display the properties window. Use this window to specify the operational parameters. 2) Define the operational parameters. Refer to the online help for details. Appendix A. Referenced objects 89

3) Click Save. c. If necessary, repeat the previous step to create another replica. 5. Click Apply to save the object to the running configuration. 6. Optionally, click Save Config to save the object to the startup configuration. Refreshing certificates Refreshing Tivoli Access Manager (TAM) certificates first refreshes the password of the keystore associated with the TAM object and then refreshes the client certificate in the keystore with the configured TAM server. The clients associated with this configuration and any other configuration which use the same keystore will be stopped if running and restarted when the refresh is complete. To refresh certificates: 1. Select Administration Miscellaneous IBM Tivoli Access Manager Tools to display the action screen. 2. Click the Refresh Tivoli Access Manager Client Certificate tab. 3. Define the operational properties. Refer to the online help for details. 4. Click Refresh Tivoli Access Manager Client Certificate. 5. Follow the prompts. IBM Tivoli Federated Identity Manager DataPower appliances integrate with IBM Tivoli Federated Identity Manager (TFIM) through the exchange of WS-Trust SOAP messages. The TFIM management object centralizes the configuration of the TFIM endpoint and prevents parameter duplication between the Map Credential and the Post Processing phases in an AAA Policy. During the Map Credential phase, an authenticated identity can be mapped to the identity for authorization. During the Post Processing phase, an authorized identity can be mapped to the output AAA identity. When integrating with TFIM, the provided input credentials must be able to be expressed in the request token format for the TFIM endpoint. For example, a WS-Security Username token as the request token cannot be created when the available user credential is an X.509 certificate. Creating the TFIM object To create and configure a TFIM object, use the following procedure: 1. Use the Objects Access Settings IBM Tivoli Federated Identity Manager menu path to display the IBM Tivoli Federated Identity Manager catalog. 2. Click Add to display the IBM Tivoli Federated Identity Manager configuration screen. Use this screen to specify operational parameters. a. Specify the name for the object in the Name field. b. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. c. Specify a descriptive object-specific summary in the Comment field. d. Specify the host name or IP address of the TFIM server in the Server field. e. Specify the port number of the TFIM server in the Port field. The default is 9080. f. Select the currently configured version of TFIM from the Compatibility Mode list. The value determines the details for the namespace and WS-Trust messages. 90 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Note: Selecting Version 6.2 as the compatibility mode will cause the TFIM client/endpoint to generate WS-Trust messages using version 1.3 of the WS-Trust specification. In this case, trust chains in the TFIM 6.2 server must use the Validate OASIS URI as the Request Type. To use WS-Trust version 1.2 messages with a TFIM 6.2 server, select TFIM 6.1 as the compatibility mode. If the 6.1 compatibility mode is selected, TFIM 6.2 will behave the same as TFIM 6.1. Version 6.0 Indicates Tivoli Federated Identity Manager, version 6.0. Version 6.1 (Default) Indicates Tivoli Federated Identity Manager, version 6.1. Version 6.2 Indicates Tivoli Federated Identity Manager, version 6.2. g. Select the format of the request token from the Request Token Format list. The available formats depend on the selected value for Compatibility Mode. v If Version 6.0, the following formats are available: Custom Indicates a custom style sheet for generating the TFIM request. When selected, requires the specification of a Custom Request. SAML 1.0 Indicates a SAML Assertion 1.0. SAML 1.1 Indicates a SAML Assertion 1.1. Username Token (Default) Indicates a WS-Security Username Token Type. v If Version 6.1 or Version 6.2, the following formats are available: Binary Security Token Indicates a WS-Security BinarySecurityToken. Custom Indicates a custom token. When selected, requires the specification of a Custom Request. Custom Token Indicates a custom token. SAML 1.0 Indicates a SAML Assertion 1.0. SAML 1.1 Indicates a SAML Assertion 1.1. SAML 2.0 Indicates a SAML Assertion 2.0. Kerberos Token Indicates a WS-Security Kerberos Token. Username Token (Default) Indicates a WS-Security Username Token Type. X.509 Token Indicates a WS-Security X.509 Token. Appendix A. Referenced objects 91

h. When using TFIM 6.0, TFIM 6.1, or TFIM 6.2 and when Request Token Format is Custom, select the location of the custom style sheet in the Custom Request field. The custom style sheet file must be in the local: or store: directory. Click Upload or Fetch to upload the custom style sheet file. i. When Request Token Format is not Custom, define the following properties: 1) When using TFIM 6.0, TFIM 6.1, or TFIM 6.2, specify the scope for this security token in the Applies-To Address field. For example, specify the services to which this token applies: http://tfim.ibm.com:9080/echoapplication/services/echoserviceuser http://9.33.97.251:9080/echoapplication/services/echoserviceuser In the TFIM service, this information specifies the destination of the request. The TFIM trust service uses this information to determine which trust chain to invoke. To determine the correct value, consult your TFIM administrator. 2) When using TFIM 6.0, TFIM 6.1, or TFIM 6.2, specify the identity that issued the request in the Issuer field. For example, in the TFIM WS-Security Management (WSSM) component, the Issuer is either the WSSM token generator or the WSSM token consumer: urn:itfim:wssm:tokenconsumer The TFIM trust service uses this information to determine which trust chain to invoke. To determine the correct value, consult your TFIM administrator. 3) When using TFIM 6.1 or TFIM 6.2, optionally specify the name of the Web services port type to use in the Port Type field. A port type is a group of Web services operations. For example: EchoService The TFIM trust service uses this information to determine which trust chain to invoke with finer granularity. If a value is not specified, a default value of NotSpecified is used. To determine the correct value, consult your TFIM administrator. 4) When using TFIM 6.1 or TFIM 6.2, optionally specify the name of the Web services operation to use in the Operation field. For example: echo The TFIM trust service uses this information to determine which trust chain to invoke with finer granularity. If a value is not specified, a default value of NotSpecified is used. To determine the correct value, consult your TFIM administrator. j. From the SSL Proxy Profile list, select an SSL Proxy Profile to manage secure communications with the peer. k. Use the Schema Validate Response toggle to specify whether to schema-validate responses from the TFIM server. When enabled, TFIM responses are schema-validated with the WS-Trust version that is defined by the compatibility mode. on Responses are schema-validated. off (Default) Responses are not schema-validated. 3. Click Apply to save the object to the running configuration. 4. Optionally, click Save Config to save the object to the startup configuration. Working with Kerberos objects A basic description of the Kerberos authentication protocol is helpful for understanding the support provided by the DataPower appliance. 92 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

The Kerberos authentication protocol uses a star topology. The Key Distribution Center (KDC) is at the center of the star. Each Kerberos principal (a human, a computer client, or an instance of a service running a specific computer) is registered with the KDC and has a shared secret known only to the principal and to the KDC. This shared secret takes the form of a password for human principals and a randomly generated keytab file for nonhuman principals. When a Kerberos client (for example, Alice) wants to communicate securely with a Kerberos server (for example, the FTP service), Alice must access KDC of her Kerberos realm and request a ticket for the FTP service. At this point, the KDC has the option of requiring pre-authentication before responding, or the KDC can immediately issue the ticket to Alice. The KDC response contains two items: v A randomly generated session key encrypted with Alice s shared secret v A ticket for the FTP service The ticket contains: v The idobj for Alice v The idobj for the FTP service v A ticket lifetime v Another copy of the session key The ticket is encrypted with the shared secret of the FTP service principal. Consequently, there are two encrypted copies of the session key (one for Alice, and one for the FTP service). At this point, Alice uses her shared secret to decrypt her copy of the session key and generates an authenticator (which proves that the person talking to the FTP service is the client for which this ticket was issued, and not a malicious user replaying a previously issued ticket) that she sends along with her ticket to the FTP service. The ticket plus authenticator is called an AP-REQ message. When the FTP service receives the AP-REQ from Alice, it decrypts the ticket and verifies the authenticator. At this point the FTP server has authenticated Alice, and they share a session key which can be used to secure the rest of their communications. Points to remember when using Kerberos When using Kerberos, keep the following points in mind: v v v v v v v v Both clients and servers are principals in the KDC database. More accurately, services running on server computers are principals in the KDC database. A client principal must request a separate ticket for each server with which it communicates. Services must have a name and shared secret registered with the KDC. A service must have access to its shared secret to decrypt Kerberos tickets. A Kerberos ticket that is issued by a KDC contains the cryptographic material that allows both the client and the server to generate the same session key. All Kerberos cryptographic operations are symmetric in nature. In an AAA Policy, Kerberos is an idobj extraction, authentication protocol, or both. Kerberos is not an authorization protocol. Appendix A. Referenced objects 93

There is no restriction in Kerberos that specifies which clients can request tickets for a particular service. Note: Microsoft Windows, when configured to use an Active Directory domain, is based on a security infrastructure that is, at its core, Kerberos. As of Windows 2000, authentication in a Windows domain is handled by Kerberos. Such authentication is entirely transparent to the user. Refer to Understanding SPNEGO for implementation details. Kerberos KDC Server objects Use the following procedure to configure a Kerberos KDC Server: 1. Select Objects Crypto Kerberos KDC server to display the Kerberos KDC Server catalog. 2. Click Add to display the Kerberos KDC Server configuration screen. 3. Provide the following inputs: Name Specify the name of the object. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Kerberos realm name Specify the name of the Kerberos realm that is serviced by this KDC. There is exactly one KDC per Kerberos realm. Kerberos KDC Server Specify the host name or IP address of the KDC server. Click Ping to verify connectivity. Use TCP Select whether to use UDP or TCP as the Transport Layer protocol to access the KDC server. on Use Transmission Control Protocol (TCP) off (Default) Use User Datagram Protocol (UDP) Server Port Number Specify the UDP or TCP port that is monitored by the KDC for incoming Kerberos requests. The default is 88. UDP Timeout When the Transport Layer protocol is UDP, specify the UDP timeout. 4. Click Apply to save the object to the running configuration. 5. Optionally, click Save Config to save the object to the startup configuration. Kerberos Keytab File objects A Kerberos Keytab file contains the keys needed to decrypt the ticket presented by a client attempting to obtain services. Previously, only a password was required. This has been changed to an encrypted key for added security. The Kerberos Keytab File object identifies the file that contains the keys needed to decrypt the ticket. Use the following procedure to configure a Kerberos Keytab File: 94 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

1. Select Objects Crypto Kerberos Keytab to display the Kerberos Keytab catalog. 2. Click Add to display the Kerberos Keytab Configuration screen. 3. Provide the following inputs: Name Specify the name of the object. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. File Name Select the keytab file. This list includes files that are stored in the encrypted and protected cert: directory of the appliance. If the file does not reside on the appliance, click Upload or Fetch to transfer the file. Note: This file is not generated on the DataPower appliance. It is generated through the Kerberos system itself. 4. Click Apply to save the object to the running configuration. 5. Optionally, click Save Config to save the object to the startup configuration. XACML Policy Decision Point During the authorization phase of an AAA Policy, you can select Use XACML Authorization Decision. The AAA Policy acts as an XACML Policy Enforcement Point (PEP). The PEP allows the XACML Policy Decision Point (PDP) to decide whether or not to authorize access. The DataPower appliance supports the mandatory to implement and optional specifications that are listed in Section 10.2.8 of the OASIS Standard, extensible Access Control Markup Language (XACML) Version 2.0, dated February 1, 2005. Use the following procedure to configure an XACML Policy Decision Point (PDP). 1. Select Objects Access XACML Policy Decision Point to display the XACML Policy Decision Point catalog. 2. Click Add to display the XACML Policy Decision Point Configuration screen. a. Use the Name field to specify the name of this XACML PDP. b. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. c. Specify a descriptive object-specific summary in the Comment field. d. Use the Evaluate Individual Policies Equally toggle to signal the presence of a comprehensive top-level XACML policy-set. on Indicates the presence of multiple XACML policy-sets, each of which will be used in the authorization decision off (Default) Indicates the presence of a top-level XACML policy-set that is specified by the General Policy File property In the event of multiple authorization matches, a policy combining algorithm, which defines a procedure for arriving at an authorization decision given the individual results of evaluation by a set of policies, is employed to render the final decision. Appendix A. Referenced objects 95

e. Specify the location of the top-level XACML policy-set in the General Policy File field. This property is meaningful only if the Evaluate Individual Policies Equally radio button is set to off. f. Specify the policy combining algorithm used by this XACML PDP in the Dependent Policies Combining field. This property is meaningful only if the Evaluate Individual Policies Equally radio button is set to on. The XACML Version 2.0 standard defines the following policy combining algorithms: Deny Overrides The deny-overrides policy-combining algorithm evaluates each policy in the order that it appears in the XACML policy set. If any policy in the set evaluates to deny, the policy combination evaluates immediately to deny. In other words a single deny takes precedence over other policy evaluations. If all policies are determined to be NotApplicable, the policy combination evaluates to NotApplicable. First Applicable (Default) The first-applicable policy combining algorithm evaluates each policy in the order that it appears in the XACML policy set. For an individual policy, if the target (resource) evaluates to TRUE and the policy conditions evaluate unambiguously to permit or deny, evaluation is immediately halted, and the policy combination evaluates to the effect of that individual policy. If the individual policy evaluates the target as FALSE or the policy conditions as NotApplicable, then the next policy in the order is evaluated; if no further policy exists in the order, the policy combination evaluates to NotApplicable. Only One Applicable The only-one-applicable policy combining algorithm evaluates each policy in the order that it appears in the XACML policy set; unlike the other policy combining algorithms, only-one-applicable must evaluate all policies to render a final evaluation. If after evaluating all policies, no policy is considered applicable by virtue of its target (the requested resource), the policy combination evaluates to NotApplicable. If after evaluating all policies, more than one policy is considered applicable by virtue of its target, the policy combination evaluates to Indeterminate. If after evaluating all policies, only one single policy is considered applicable by virtue of its target, the policy combination evaluates to the result of evaluating that single policy. Permit Overrides The permit-overrides policy combining algorithm evaluates each policy in the order that it appears in the XACML policy set. If any policy in the set evaluates to permit, the policy combination evaluates immediately to permit. In other words a single permit takes precedence over other policy evaluations. If all policies are determined to be NotApplicable, the policy combination evaluates to NotApplicable. g. Use the Dependent Policy Files field with the Add and Delete buttons to construct a list of dependent policy files. 96 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Application Security Policy Policy sets can be local or remote to the appliance; use local or standard URLs to locate files. h. Optionally, use the Other Policy Files from Directory field with the Add and Delete buttons to construct a list of local directories that contain dependent files. All files in noted directories with a.xml or.xacml extension are considered as potentially available to the current XACML PDP. i. Use the XACML Policies Cache Lifetime field to specify the policy combining algorithm used by this XACML PDP. Specify an integer (in the range from 0 to 2,678,400) that specifies the time, in seconds, that compiled XACML policies are maintained in the PDP cache. The default value of 0 specifies that the cache is never expired. There are several ways for users to control the XACML PDP policy caches. Explicitly clear the cache Use the clear pdp cache CLI command to clear the cache. Specify the TTL for the PDP During PDP configuration, use the WebGUI or CLI to specify a cache lifetime. Use the XML Manager When the PDP is used by an AAA policy for authorization, users can access the XML manager that is associated with the AAA policy with the clear xsl cache CLI command. This command also clears the compiled XACML policies that are referenced by AAA polices that are supported by the XML manager. Use a URL Refresh Policy Use a URL Refresh Policy whose conditions match the internal URL xacmlpolicy:///pdpname to perform periodic cache refreshes. v v v v When TTL for the PDP is 0 (cache never expires), the URL Refresh Policy controls cache refresh When the URL Refresh Policy is no-cache, XACML policies are never cached, regardless of any assigned TTL value When the URL Refresh Policy is protocol-specified, the TTL setting for the PDP will govern cache refresh unless its value is 0 When the URL Refresh Policy is default with a refresh interval, the TTL for the PDP is ignored and the URL Refresh Policy refresh interval controls cache refresh v When the URL Refresh Policy is no-flush with a refresh interval, the greater of the URL Refresh Policy refresh interval or the TTL for the PDP controls cache refresh 3. Click Apply to save the object to the running configuration. 4. Optionally, click Save Config to save the object to the startup configuration. An Application Security Policy establishes the rules used to enforce security for a Web Application Firewall service. This policy employs Request Maps, Response Maps, and Error Maps. Each of these maps, in turn, matches a Web Request Profile, Web Response Profile, or Error Policy, respectively, to client requests that are based on a set of matching criteria. The Profiles selected then provide the detailed security configuration. Appendix A. Referenced objects 97

Select Objects Web Applications Application Security Policy to display the Application Security Policy catalog. This catalog lists all Application Security Policy objects that are configured in the current domain. Click on the name of a Policy to edit it. Click Add to create a new Policy. Provide the following inputs: Name Specify a name for this Policy. This is the name that appears in all Policy listings. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Request Maps tab Request Maps select Web Request Profiles to execute on client requests based on a set of matching criteria. If the client request meets the matching criteria, the corresponding Web Request Profile executes. At least one Request Map entry is required. Click the Request Maps tab to establish Web Request matching maps. A catalog of all configured maps is displayed. Click the name of a Map to edit it. Click Add to create a new Map. Provide the following inputs: Matching Rule Select an existing Matching Rule. Refer to Matching Rule on page 106 for more information. Request Profile Select a Web Request Profile. Refer to Web Request Profile on page 132 for more information. Click Save to save the map and close the window. The new map then appears in the catalog list of maps. Response Maps tab Response Maps select Web Request Profiles to execute on server responses based on a set of matching criteria. If the server response meets the matching criteria, the corresponding Web Request Profile executes. At least one Response Map entry is required. Click the Response Maps tab to establish Web Response matching maps. A catalog of all configured maps is displayed. Click the name of a Map to edit it. Click Add to create a new Map. Provide the following inputs: 98 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Count Monitor Error Policy Matching Rule Select an existing Matching Rule. Refer to Matching Rule on page 106 for more information. Response Profile Select a Web Response Profile. Refer to Web Response Profile on page 139 for more information. Click Save to save the map and close the window. The new map then appears in the catalog list of maps. Error Maps tab Error Maps select a Processing Rule to execute on errors based on a set of matching criteria. If the error meets the matching criteria, the corresponding Processing Rule executes. To establish Error Policy matching maps, use the following procedure: 1. Click the Error Maps tab to display the Error Maps catalog. This catalog lists all configured maps. 2. Click the name of a Map to edit it. Click Add to create a new Map. 3. Provide the following inputs: Matching Rule Select an existing Matching Rule. Refer to Matching Rule on page 106 for more information. Processing Rule Select an existing Processing Rule. Refer to Processing Rule on page 111 for more information. 4. Click Save to save the map and close the window. The new map is in the Error Maps catalog. Click Cancel to abandon any changes. Although the configuration of the following objects all the configuration of count monitors, Web Application Firewall services do not support this type of monitor configuration. v AAA Policy v Error Policy A Web Application Firewall service can employ an Error Policy to handle errors returned by the backend service. An Error Policy can take action on the error, changing the error response received by the requesting client. Select Objects Web Applications Error Policy to display the Error Policy catalog. This catalog lists all the Error Policy objects. Click on the name of an existing Policy to edit it. Click Add to create a new Policy. The Error Policy object configuration screen is displayed. Provide the following inputs: Appendix A. Referenced objects 99

Name Specify a name for this Error Policy object. This name will appear in the catalog listing of objects as well as in any list of Error Policy objects. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Mode Select a mode of operation. Redirect Redirects the client to the specified URL. The URL field appears when this mode is selected. Proxy The appliance fetches the specified URL and then return its contents to the client. The URL field appears when this mode is selected. Error-rule The appliance executes a selected Processing Rule and return the result to the client. The Error Rule field appears when this mode is selected. Standard The appliance passes the error to the Application Security Policy selected for the Web Application Firewall. If the Application Security Policy includes an Error Map that will match the error, then that action is taken. This mode is useful when you want to execute error handling rules for specific requests and want to enforce monitoring of all errors, even if no Error Map matches the request. URL Specify a fully qualified URL (http://host/...). This URL is used only for the Redirect or Proxy modes of operation. Error Rule Select a Processing Rule when the mode is set to Error-rule. This rule is executed against the error returned by the application server. Monitor Do not select a Count Monitor object. The Web Application Firewall service does not support this configuration. Defining an LDAP Search Parameters object The LDAP Search Parameters object serves as a container for the parameters that are used to perform an LDAP search operation. Authentication The parameters for an LDAP search to retrieve the DN of the user. Credentials mapping The parameters for an LDAP search to retrieve the group name (DN or attribute) based on the DN of the authenticated user. You need to add a prefix and optionally add a suffix to create the LDAP filter. The prefix and suffix are constructs of the LDAP filter expression, as defined in LDAP: String Representations of Search Filters. This filter is used to perform the LDAP search and return matching entries. 100 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Load Balancer Group To create an LDAP Search Parameters object, use the following procedure: 1. Select Objects Access Settings LDAP Search Parameters to display the catalog. 2. Click Add to display the configuration screen. 3. Specify the name of the object in the Name field. 4. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. 5. Specify a descriptive object-specific summary in the Comment field. 6. Specify the base DN to begin the search in the LDAP Base DN field. This value identifies the entry level of the tree used by the LDAP Scope property. 7. Specify the name of the attribute to return for each entry that matches the search criteria in the LDAP Returned Attribute field. The default is the dn attribute. 8. Specify the prefix of the LDAP filter expression in the LDAP Filter Prefix field. If the prefix is mail= and the user name is bob@example.com, the LDAP search filter would be mail=bob@example.com. 9. Optionally specify the suffix of the LDAP filter expression in the LDAP Filter Suffix field. If the prefix is mail=, the suffix is )(c=us)), and the user name is bob@example.com, the LDAP search filter would be (&(mail=bob@example.com)(c=us)). 10. Select the depth of the search from the LDAP Scope list: Base Searches the entry level of the tree only. One level Searches the entry level of the tree and any object that is one-level below the input. Subtree (Default) Search the entry level of the tree and all of its descendents. 11. Click Apply to save the object to the running configuration. 12. Optionally, click Save Config to save the object to the startup configuration. A Load Balancer Group is a server pool that can provide redundancy among a collection of servers. A Load Balancer Group can be used as the backend server for a DataPower service or can be used to provide LDAP or IMS Connect server failover protection. A request to connect to a Load Balancer Group results in the selection of a healthy server to receive an incoming client request. Each instance of a Load Balancer Group can support 512 members. Health of member servers The health of each member of the group is considered one of the following : v Healthy or up v Quarantined or softdown v Convalescent or down Appendix A. Referenced objects 101

Healthy By default, all servers are considered healthy and are eligible to receive forwarded client requests. When healthy, the health state is up. Quarantined During a normal HTTP transaction or the TCP ping, a failure to connect to a server causes the server to be quarantined until a dampening period elapses. When the dampening period elapses, the server returns to the healthy state and becomes eligible to receive forwarded client requests. When quarantined, the health state is softdown. While quarantined, the server is: v Removed from the server pool v Ineligible to receive forwarded client requests v Excluded from the optional health check Convalescent Optionally, you can associate a periodic health check with a Load Balancer Group. If the health check fails, the server is deemed convalescent. The server is not considered to be healthy until it passes a health check. When deemed convalescent, the health state is down. While deemed convalescent, the server is: v Removed from the server pool v Ineligible to receive forwarded client requests Setting the health state with a variable The health state for each server can be set with the service/lbhealth/ service variable. This variable takes one of the following syntax statements: var://service/lbhealth/group/server/state var://service/lbhealth/group/server:port/state Where: group server port state The name of the Load Balancer Group The IP address or host name of the member The port of the member The state of the server, which is one of the following values: v up v down v softdown Refer to Health of member servers on page 101 for details. Configuring Load Balancer Group objects The configuration of a Load Balancer Group consists of the following activities: 1. Providing basic configuration properties on the Main tab 2. Defining server members on the Members tab 3. Optionally defining health check criteria on the Health tab 102 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Providing basic configuration To start the configuration, perform the following procedure: 1. Select Objects Network Load Balancer Group to display the catalog. 2. Click Add to display the configuration screen. 3. Provide the following inputs: Name Specify the name for the Load Balancer Group. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Algorithm Select the algorithm to select the actual server. The following values are available: First Alive Uses the concept of a primary server and backup servers. When the primary server is healthy, all connections are forwarded to this server. When the primary server is quarantined or convalescent, connections are forwarded to backup servers. The primary server is the first server in the members list. Hash Uses the IP address of the client or the value of an HTTP header as the basis for server selection. When using an HTTP header, use the Load Balancer Hash Header property to identify the header to read. This property is available for Multi-Protocol Gateway and Web Service Proxy services only. Additionally, this property is available only in the object view, and this property is on the Main tab. The same client is served by the same server. This algorithm is used in applications that require the storage of server-side state information, such as cookies. Least Connections Maintains a record of active server connections and forward a new connection to the server with the least number of active connections. Round Robin (Default) Maintains a list of servers and forwards a new connection to the next server on the list. Weighted Round Robin Maintains a weighted list of servers and forwards new connections in proportion to the weight (or preference) of each server. Damp Time Specify the number of seconds that a server remains in an softdown state. Use a value in the range of 1 through 86400. The default is 120. This property does not impact servers that are in the down state. Do not Bypass Down State Select the connection-behavior when no member is up. Appendix A. Referenced objects 103

on Does not forward the connection to any member. Makes the next attempt when at least one members is in the up state. off (Default) Selects the first member in the down state and forwards the connection to this server. Try Every Server Before Failing Select the retry-behavior for a failed attempt. on Sends the requests to each server until one responds or all fail. Each server that fails is set to the softdown state. off (Default) Does not attempt to contact other members. Masquerade as Group Name Select which name to present in the message header. on Uses the name of the Load Balancer Group. If appserver1.domain.com is a member of the Appsters Load Balancer Group, the message header contains Appsters. off (Default) Use the host name of the member. If appserver1.domain.com is a member of the Appsters Load Balancer Group, the message header contains appserver1.domain.com. 4. Continue with procedure that is provided in Defining server members. Defining server members Use the following procedure to add members or assign weight to members. For all algorithms except First Alive, the order of members is not important. 1. Select the Members tab to display the catalog. 2. Click Add to display the property window. 3. Provide the following inputs: Actual Host Specify the IP address or the domain-qualified host name of the member. Weight If the algorithm is Weighted Round Robin only, specify the relative weight (preference). Use a value in the range of 1 through 65000. The default is 1. The greater the value, the more likely this server is to receive a connection request. For example there are three members (A, B, and C) that have the assigned weights of 100, 60, and 40, respectively. Because of the weighting, A receives 50% of requests, B receives 30% of requests, and C receives 20% of requests. Mapped Server Port Specify the member-specific target port or retain the default value (0) to use the DataPower service-defined port. Use a value in the range of 0 through 65535. The default is 0. By default, member servers are contacted on the DataPower service-defined port. However, if you have services running on different ports for different member servers, explicitly identify the member-specific target port. If you specify a nonzero value, that member server will always be contacted on this port. 104 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Health Port Specify the member-specific health port or retain the default value (0) to use the Load Balancer Group-defined port. Use a value in the range of 0 through 65535. The default is 0. A nonzero value overrides the value for the Remote Port property of the health check. This property is available during the configuration of the health check on the Health screen. 4. Click Save to return to the catalog. Assignment of all members to a Load Balancing Group completes the required configuration. v v v To associate a periodic health check with the new Load Balancer Group, refer to Defining health checks. If you are completed with the configuration, click Apply to save the object to the running configuration and return to the object catalog. Optionally, click Save Config to save the object to the startup configuration. Defining health checks A health check is essentially a scheduled rule that sends the same request to each server member. The successful completion of the health check requires that the server passes normal TCP and HTTP connection criteria. Optionally, the health check contains a filter to test the response from the server. If the filter accepts the response, the server is considered to be healthy; otherwise, it is considered to be convalescent. Use the following procedure to define the health check: 1. Click the Health tab to display the configuration screen. 2. Provide the following inputs: Enabled Controls whether to perform the periodic health check. on Enables the health check. off (Default) Disables the health check. URI When the check type is Standard, specify the non-server (file path) portion of the target URI. That is, specify the URI to receive the client request that is generated by the rule. The default is /. This URI is used with the specified remote port. Remote Port Specify the port on the target server to receive the query. The default is 80. You can override this value for one or more members of the Load Balancer Group with the Health Port property. This property is available during the configuration of member servers in the group. The response from the server is evaluated to determine the health status of each member server in the group. The request is sent to the target URI and remote port. Health Check Type Select the type of check to perform. Standard (Default) Select if the group does not consist of LDAP servers. Appendix A. Referenced objects 105

LDAP Select if the group consists of LDAP servers. IMS Connect Select if the group consists of IMS Connect servers. Send SOAP Request? When the check type is Standard, specify the HTTP method to access the target URI. on (Default) Click to access the target URI with an HTTP POST operation (by posting a SOAP message). off Click to access the target URI with an HTTP GET operation. SOAP Request Document When Send SOAP Request? is on, specify the SOAP message to send as a client request. The default is the healthcheck.xml file in the store: directory (store:///healthcheck.xml). Timeout Specify the number of seconds for the completion of the health check. Use a value in the range of 2 through 86400. The default is 10. If successful, the server is deemed healthy and is marked as up; otherwise, the server is deemed convalescent and is marked as down. Frequency Specify the number of seconds between health checks. Use a value in the range of 5 through 86400. The default is 180. XPath Expression When the check type is Standard, use with the XSL Health Check Filter property to specify the XPath expression that must be found in a valid server response. If necessary, click XPath Tool to define an XPath expression. XSL Health Check Filter When the check type is Standard, specify the style sheet to filter the server response. The default is the healthcheck.xsl file in the store: directory (store:///healthcheck.xsl). This style sheet uses the specified XPath Expression value as input and scans the server response for its presence. If found, the server is deemed healthy and is marked as up; otherwise, the server is deemed convalescent and is marked as down. SSL proxy profile Optionally, when the check type is Standard, select an SSL Proxy Profile to provide the resources for a secure connection. 3. Click Apply to save the object to the running configuration. 4. Optionally, click Save Config to save the object to the startup configuration. Matching Rule Matching Rule objects support the implementation of processing policies and XML manager-based schema validation rules. Both use a Matching Rule to determine if a candidate XML document is subject to a particular processing or validation action in a processing policy. A Matching Rule contains one or more match expressions. Match expressions are of the following types: 106 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

v v v v Error code expressions define an error set that is subject to a specific error-rule. As error codes are written as hexadecimal integers, the error code expression matches one or more hexadecimal integers. HTTP expressions work with a specified HTTP header to define a group of HTTP headers. An HTTP expression can define, for example, an HTTP header that contains a specific header field or an HTTP header that contains a defined value in a specific header field. URL expressions define a group of URLs. For example, a URL expression could define all URLs or only URLs that contain a specific domain name. XPath expressions define content in the XML document. For example, an XPath expression could define all attributes of a specific name. Note: Candidate documents are evaluated against all match expressions in the Matching Rule. A document matches the rule only if it conforms to all expressions in the rule. Documents that fail to match all expressions do not match the rule. To configure a Matching Rule, use the following procedure: 1. Select Objects XML Processing Matching Rule to display the catalog. 2. Click Add to display the configuration screen. 3. Specify the name of the object in the Name field. 4. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. 5. Specify a descriptive object-specific summary in the Comment field. 6. Use the Match with PCRE toggle to indicate whether match patterns use PCRE expression or shell-style expressions. on Uses PCRE expressions. off (Default) Uses shell style expressions. 7. Use the Boolean Or Combinations toggle to indicate whether to combine the match criteria with OR semantics or with AND semantics. on Uses OR semantics to evaluate the criteria. Only a single match condition needs to be true for the match to succeed. off (Default) Uses AND semantics to evaluate the criteria. All match conditions must be true for the match to succeed. 8. Define matching rules on the Matching Rule tab a. Click Add to display the Property window. b. Select the desired match type from the Matching Type list. Error Code Bases the match on an error code. This type is for use in the processing of error rules. Full URL Deprecated. Use URL. This legacy type creates a match that uses a shell-style match pattern against the full inbound URL. Host Deprecated. Use HTTP. This legacy type creates a match that uses a shell-style match pattern against the Host: header in HTTP 1.1 requests. HTTP Bases the match on HTTP header fields. Appendix A. Referenced objects 107

Name-Value Profile URL XPath Bases the match on the inbound URL after any URL rewrite. Bases the match on an XPath expression. The expression is applied to the inbound document. When the XPath expression evaluates to true, a match is made. c. Define the matching criteria: v When HTTP: 1) Specify the target HTTP header field in the HTTP Header Tag field. 2) Specify the HTTP expression in the HTTP Value Match field. Wildcards are allowed. v When URL, specify the URL match expression in the URL Match field. You can use wildcards to define a match pattern as follows: * The string wildcard matches 0 or more occurrences of any character. For a PCRE expression, use.* rather than * to match any number of any characters.? The single character wildcard matches one occurrence of any single character. [] The delimiter pair to bracket a character or numeric range. [1-5] Matches 1, 2, 3, 4, or 5 [xy] Matches x or y You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. v When Error Code, identify the target error code in the Error Code field. Click Select to view a list of selectable error codes. v When XPath, specify the XPath expression in the XPath Expression field. Click XPath Tool for help creating this expression. d. Click Save. Repeat this step to define another matching rule. 9. Click Apply to save the object to the running configuration. 10. Optionally, click Save Config to save the object to the startup configuration. Web applications communicate with clients using the various mechanisms of the HTTP protocol. The protocol provides for HTTP headers, cookie values, URL-encoded query strings, and URL-encoded request messages. Each of these kinds of communication mechanisms operate using a string of name-value pairs (such as token=valuea&token1;=valueb&broken;=reject). To provide integrity and security for such an application, it is necessary to inspect and take action on these names and values. A Name-Value Profile provides a means to implement this inspection and action configuration. A Name-Value Profile filters names, and for names that match a given expression, sets constraints on the corresponding values, again expressed as a match expression. The Name-Value Profile works by comparing each name in a name-value pair to all entries in a configured Validation List. If a match is found, the corresponding value is compared to a corresponding match expression. If a match is found, the pair passes. If no match is found, one of several actions is taken. 108 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

For example, given the URL-encoded string token=valuea&token1;=valueb &broken;=reject, only names that contain the substring token will be accepted, and those that are accepted must have a value that contains the string value. The name-value pair with a name of broken can optionally be passed through, stripped from the string or replaced with a known value, or the entire string can be rejected (in which case, the profile will fail to pass). 1. Select Objects Web Applications Name-Value Profile to display the Name-Value Profile catalog. The catalog lists all available Name Value Pair objects. 2. To edit an existing object, click the object name. To create a new object, click Add. The Name-Value Profile configuration page appears. 3. Provide the following inputs: Name Specify an alphanumeric name for this profile object. This name appears in all lists of available Name-Value Profiles. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Maximum Count Specify an integer to determine the maximum number of name value pairs allowed in a single entity (header, cookie set, Post body, or Query String). Total Size Specify an integer to determine the maximum size, in bytes, of the aggregated names and values in a single entity. Max Name Length Specify an integer to determine the maximum size, in bytes, of a name attribute used in this profile. The default is 512 bytes. Max Value Length Specify an integer to determine the maximum size, in bytes, of a value attribute used in this profile The default is 1024 bytes. No Match Policy Select an option to determine the action taken when a given name does not match a Name Matching expression in the configured Validation List (refer to Validation List tab on page 110). Error The Profile validation fails and an error is generated. This is the default. Pass-thru The given Name Value pair is passed through to the next step in processing. Set The given Name token is replaced with a default value. The No Match Map Value input appears when this option is selected. Strip The Name-Value pair is removed from the entity (headers, Post body, Query String or cookie) and processing continues. No Match Map Value Specify an alphanumeric string. The Value of any Name Value pair that Appendix A. Referenced objects 109

does not match at least one entry in the Validation List will be replaced with this constant value when the No Match Policy is Set. No Match XSS Policy When set to on, name values that do not match an entry in the Validation List are checked for Cross Site Scripting (sometimes called CSS or XSS) signatures. These signatures are generally attempts to obfuscate the real meaning of the value if the value were displayed directly in a browser. Use to validate any data that might get stored and displayed again later - such as the contents of a comment form. When set to on, investigates escaped characters, those characters with the high-bit set, and various forms of the term script which is often used to engage JavaScript on a browser without the user's knowledge. The default is off. Validation List tab The Name-Value Profile works by comparing each name of a name-value pair to the expression on the Validation List. If no match is found, the No Match Policy is executed. When a match is found, the corresponding value is compared to the corresponding Value Constraint in the Validation List. If a match is found, the Name Value Pair passes. If no match is found, the Failure Policy is executed. In addition, unmatched values can also be checked for cross site scripting (XSS). 1. Click the Validation List tab to edit and create a Validation List. 2. Click Add to create new entries. 3. Provide the following inputs: Name Expression The regular expression that the submitted names are matched against. If they match, the value must also match against the corresponding value constraint to be passed through. Value Constraint The regular expression (PCRE style) that is applied to a value input to determine whether it is an expected input. Failure Policy Select an option to determine the action taken when a given value does not match the Value Constraint expression. Error The Profile validation fails and an error is generated. This is the default. Pass-thru The given Name Value pair is passed through to the next step in processing. Set The given Value is replaced with a default value. The Map Value input appears when this option is selected. Strip The Name Value pair is removed from the entity (headers, Post body, Query String, or cookie) and processing continues. Map Value Specify an alphanumeric string. The value will be replaced with this constant value when the Failure Policy is Set. Check XSS When set to on, the values that do not match the Value Constraint expression are checked for cross site scripting (sometimes called CSS or XSS) signatures. These signatures are generally attempts to obfuscate the real meaning of the value if the value were displayed directly in a 110 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

browser. Use to validate any data that might get stored and displayed again later - such as the contents of a comment form. When set to on, investigates escaped characters, characters with the high-bit set, and various forms of the term script, which is often used to engage JavaScript on a browser without the user's knowledge. The default is off. Processing Rule You can create global, reusable processing rules which can later be assigned to one or more processing policies. 1. Select Objects XML Processing Processing Rule to display the catalog. 2. Click Add to display the configuration screen. 3. Provide the following inputs: Name Specify the name of this Processing Rule. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Rule Direction Select the rule type or direction. Error A specialized bidirectional rule used for error handling Client to Server A rule applied only to client-originated documents Server to Client A rule applied only to server-originated documents Both Directions A bidirectional rule applied to both client- and server-originated documents Input Filter Select a decompression algorithm to apply to the entire message payload prior to the first action of the rule executing. gzip The message will be decompressed using the gzip algorithm. PKZIP The message will be decompressed using the pkzip algorithm. If the message is not compressed using the selected algorithm, an error will result. This is, in effect, a filter. Output Filter Select a compression algorithm to apply to the entire message payload after the last action of the rule executes. gzip The message will be decompressed using the gzip algorithm. PKZIP The message will be decompressed using the pkzip algorithm. The created archive contains only one file. If the message contains attachments, the attachments are contained in the one file. Appendix A. Referenced objects 111

Non-XML Processing Select whether to enable or disable the processing of non-xml documents. on Enables the processing of non-xml documents. off (Default) Disables the processing of non-xml documents. Unprocessed Select whether to determine whether the actions of the rule will take effect on the message. This duplicates the Request Type and Response Type properties of the services. Actions Use the Add and Delete buttons, with the list of available processing actions, to manage actions for this processing rule. 4. Click Apply to save the object to the running configuration. 5. Optionally, click Save Config to save the object to the startup configuration. Rate Limiter A Rate Limiter object establishes policies used to control the rate at which requests are received by a Web Application Firewall. When the rate exceeds the limits set, the Limiter can reject requests, post notification or shape, or delay traffic to remain in the limits set. A Rate Limiter object is used by a Web Request Profile. Select Objects Web Applications Rate Limiter to display the Rate Limiter catalog. This catalog lists all Rate Limiter objects. To edit an existing object, click the name. To create a new object, click Add. The Rate Limiter object configuration page appears. Provide the following inputs: Name Specify an alphanumeric name for this object. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Rate Specify an integer to set the rate of acceptable traffic, per user, expressed in transactions per second. The default is 500. Enforcement Style Select the action taken when the rate limit is exceeded. Notify Generate log message in the appropriate application domain. Log targets must subscribe to this event to capture message. Reject Requests are rejected until transaction rate drops below the configured limit. Shape Delay requests as much as possible to lower the transaction rate to the configured limit. Once too many messages are buffered, creating a low memory state, transactions are rejected until rate drops. The ability to shape transactions is limited when concurrent connections are high. 112 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Session Management Policy Distinct Users The count is organized by the identity most recently used. When too many distinct counts are observed, the users not seen in the longest time are discarded. This parameter specifies how many distinct users to track before discarding. Concurrent Connections The number of simultaneous connections allowed per user. Set to 0 to disable this enforcement. A Session Management Policy controls and manages the following Web request attributes: v The URL of the pages that start, or begin, a session (such as a login page) v The lifetime of the session v Session renewal Select Objects Web Applications Session Management Policy to display the Session Management Policy catalog. This catalog lists all Session Management Policy objects. Click on the name of an existing Policy to edit it. Click Add to create a new object. The Session Management Policy configuration page appears. Provide the following inputs: Name Specify an alphanumeric name for this Policy. This name appears in all listings of available Policies. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Auto Renew If this property is enabled (on), the session lifetime is renewed on each use of the session. The click of a mouse or submission of a form constitutes a use. When this is set to on, the Session Lifetime then measures idle time between uses. When this is set to off, the session lifetime is the total amount of time allowed before returning to the login sections. Session Lifetime Specify an integer that determines the lifetime of a session, in seconds. The login cookie is only good for the amount of time specified by this property. The login cookie can be renewed during activity depending on the value of the Auto Renew property. Use an integer in the range of 1 through 864000. The default is 3600. Address Independent Sessions Normally the session cookie contains the client IP address to prevent using the session on any other host. Some environments might make this behavior undesirable. Enabling this property makes the session cookie address independent. Start Pages Select the matching rule that is used to identify start pages. Start pages are pages that can be accessed without a session cookie. If a security policy is Appendix A. Referenced objects 113

enforced on the page, these pages will then issue a session cookie. Refer to Matching Rule on page 106 for more information. URL Rewrite Policy You can design a URL Rewrite Policy that defines rules for the following rewrite and replacement operations: v Rewrite the entire URL or a portion of the URL v Replace a header value in the message v Rewrite the HTTP POST body in the message The rewrite rules in the URL Rewrite Policy are applied before document processing. Therefore, the evaluation criteria in the Matching Rule is against the rewritten value. Use the following method to create a URL Rewrite Policy: 1. Select Objects XML Processing URL Rewrite Policy to display the URL Rewrite Policy catalog. 2. Click Add to display the URL Rewrite Policy Configuration (Main) screen. 3. Provide the following inputs: Name Specify the name of this URL Rewrite Policy. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. URL Rewrite Direction Select the direction of the URL Rewrite Policy. Direction is applied at the service level and has no effect on other policies. Both Applies to both client requests and server responses. Request Applies to client requests only. Response Applies to server responses only. 4. Continue with URL Rewrite Rule tab. URL Rewrite Rule tab 1. Click the URL Rewrite Rule tab to display the URL Rewrite Policy Rule Configuration (URL Rewrite Rule) screen. 2. Click Add to display the URL Rewrite Policy Property window. 3. Provide the following inputs: URL Rewrite Type Select the rule type. absolute-rewrite Rewrites the entire URL or a portion of the URL based on a URL match. content-type Replaces the value of the Content-Type header based on a URL match. 114 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

header-rewrite Replaces the value of an arbitrary header based on its value. post-body Rewrites the body of an HTTP POST request. The POST body contains the input values for a basic HTTP POST request. rewrite This rule type is deprecated. Match Expression Specify a PCRE (Perl-compatible regular expression) that defines the match condition that triggers the rewrite rule. Depending on the rule type, a candidate URL or specific HTTP header field is matched against the expression. v For absolute-rewrite, content-type, and post-body, defines the expression to be matched against the URL..* or * Matches any string. (.*)xsl=(.*)\?(.*) Matches a string of the following format: a. A text subpattern. b. Followed by xsl=. c. Followed by a text subpattern. d. Followed by?. The backward slash (\) in the PCRE is a URL escape. e. Followed by a text subpattern. (.*)&[Xx][Ss][Ll]=([^&]+)(.*) Matches a string of the following format: a. A text subpattern. b. Followed by &. c. Followed by X or x. d. Followed by S or s. e. Followed by L or l. f. Followed by =. g. Followed by a text subpattern that does not contain an ampersand (&) character. h. Followed by a text subpattern. v For header-rewrite, defines the expression to be matched against the contents of a specific HTTP header field. For example *.* matches any value. PCRE documentation is available at http://www.pcre.org. Input Replace Expression Specify a PCRE-style replacement that defines the rewritten URL, HTTP header field, or HTTP POST body. v For absolute-rewrite, defines the rewritten URL. If the match pattern is.* or *, specify the complete replacement. If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation replacement for any text subpattern or retain the original text subpattern. To retain the first text subpattern, specify $1; to retain the second text subpattern, specify $2, and so forth. To replace the second text subpattern only, specify $1xsl=ident.xsl?$3. Appendix A. Referenced objects 115

v v If a rewritten URL begins with a host name or port that is different from the configured remote address, the host name or port portion of the rewritten URL is ignored. For content-type, defines the replacement value for the Content-Type header. For header-rewrite, defines the replacement value for the specified header. v For post-body, defines the rewritten body of the HTTP POST. For example: If the match pattern is.* or *, specify the complete replacement. If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation replacement for any text subpattern or retain the original text subpattern. To retain the first text subpattern, specify $1; to retain the second text subpattern, specify $2, and so forth. To omit the second text subpattern only, specify $1$3. Stylesheet Replace Expression Specify a PCRE-style replacement that identifies the replacement style sheet. This option is available for absolute-rewrite or post-body only. v If the match pattern is.* or *, specify the complete replacement. v If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation replacement for any text subpattern or retain the original text subpattern. To retain the first text subpattern, specify $1; to retain the second text subpattern, specify $2, and so forth. To retain the second text subpattern only and not use the third text subpattern, specify http://mantis:8000/$2. Input URL Unescape Select whether URL-encoded characters (for example, %2F) that occur in the rewritten URL are replaced with literal character equivalents. This option is available for absolute-rewrite or post-body only. on Enables the substitution of literal characters for URL-encoded characters. off (Default) Disables the substitution of literal characters for URL-encoded characters. Stylesheet URL Unescape Select whether URL-encoded characters (for example, %2F) that occur in the replacement URL are replaced with literal character equivalents. This option is available for absolute-rewrite or post-body only. on (Default) Enables the substitution of literal characters for URL-encoded characters. off Disables the substitution of literal characters for URL-encoded characters. Header Name Identifies the name of the header to have its value rewritten. The header name must be entered exactly as it is defined in the message. This option is for header-rewrite only. URL Normalization Select whether to enable normalization of URL strings. Normalizing a URL compresses "." and ".." and converts backward slashes (\) to forward slashes (/). 116 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

on (Default) Enables normalization. off Disables normalization. 4. Click Save to return to the URL Rewrite Policy Configuration (Main) screen. 5. Click Apply to save the object to the running configuration. 6. Optionally, click Save Config to save the object to the startup configuration. User Agent A User Agent is a client that initiates a request for a local service. An XML Manager uses a User Agent, for example, to retrieve resources from elsewhere on the network. The settings of a User Agent can affect messages that sent out by a specific DataPower service when its XML Manager employs a User Agent. Select Network User Agent to display the User Agent catalog. Click Add to display the User Agent configuration (Main) screen. Provide the following inputs: Name Specify the User Agent name. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. HTTP Request-Header Optionally, include the User Agent HTTP request-header field in client requests issued by this User Agent, and to specify the contents of the field. The field contains information about the user agent that sends the request. The HTTP specification does not require this field. By default, the appliance does not include the request-header field. Leave blank to suppress the inclusion of this field in client requests that the User Agent issues. Maximum Redirects Specify the maximum number of HTTP redirect messages that this User Agent can receive before the it declares the target URL as unreachable. Timeout Specify the amount of time, in seconds, that the connection can be idle before the User Agent times out and closes the connection. Use an integer in the range of 1 through 86400. The default is 300. Note: The default timeout for a connection failure is 10 seconds, which cannot be changed. The timeout applies when a specified server cannot be contacted. Click Apply to save the object to the running configuration and return to the object catalog. Optionally, click Save Config to save the object to the startup configuration. Appendix A. Referenced objects 117

Proxy Policy The User Agent will forward all requests that meet the URL Matching Expression to an HTTP server instead of to the host that is identified in the target URL. When there are multiple proxy policies, candidate URLs are evaluated against each proxy policy in the order in which it was created. Consequently, the sequence of proxy policies is important. 1. Click the Proxy Policy tab to display the User Agent configuration (Proxy Policy) screen. 2. Click Add to display the Proxy Policy Property window. 3. Provide the following inputs: URL Matching Expression Define the target URL sets associated with this Proxy Policy. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character.? Indicates a single character that matches one occurrence of any single character. [] Indicates a delimited range of alphabetic or numeric characters. For example, [1-5] would match 1, 2, 3, 4, or5, and [x-y] would match x or y. Skip You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. Use the toggle to specify whether requests for an identified URL (that is, a member of the target URL set) are forwarded to the specified HTTP server. on Does not forward requests. off (Default) Forwards requests to the specified HTTP server. When selected, provide the following inputs. Remote Host Specify the host name or IP address of the HTTP server to which to forward requests. Remote Port Specify the port on the HTTP server to which to forward requests. 4. Click Save. 5. Click Apply to save the object to the running configuration. 6. Optionally, click Save Config to save the object to the startup configuration. SSL Proxy Profile Certain User Agent requests require a secure (SSL-enabled) connection. The resources required for SSL support are provided by an SSL Proxy Profile. Refer to Defining SSL Proxy Profile objects on page 19 for more information. To assign an instance of an SSL Proxy Profile object to the User Agent, use the following procedure: 1. Click the SSL Proxy Profile Policy tab. 2. Click Add. 118 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

3. In the URL Matching Expression field, define the target URL sets associated with this policy. If the target URL matches this expression, the communication will use SSL employing the SSL Proxy Profile specified. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character.? Indicates a single character that matches one occurrence of any single character. [] Indicates a delimited range of alphabetic or numeric characters. For example, [1-5] would match 1, 2, 3, 4, or5, and [x-y] would match x or y. You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. 4. From the SSL Proxy Profile list, select an instance of the SSL Proxy Profile object to support secure access to the HTTP Proxy Server. The SSL Proxy Profile must be either a client or two-way profile. 5. Click Save. Basic HTTP Authentication Certain User Agent requests require basic HTTP authentication (user name and password). Click the Basic-Auth Policy tab to display the User Agent configuration (Basic-Auth Policy) screen, which lists all user name/password pairs. Click Add to display the Basic-Auth Policy Property window. Provide the following inputs: URL Matching Expression Define the target URL(s) set associated with this policy. If the target URL matches this expression, an HTTP Authorization header will be added, using the User Name and Password supplied. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character.? Indicates a single character that matches one occurrence of any single character. [] Indicates a delimited range of alphabetic or numeric characters. For example, [1-5] would match 1, 2, 3, 4, or5, and [x-y] would match x or y. You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. The URL set defined by this matching expression could be identical to the set defined by the HTTP Proxy Policy, or it could be a subset. User name Specify the user name. Password Specify the associated password. Confirm Password Specify the associated password again. Appendix A. Referenced objects 119

Click Save to complete basic authentication and return to the User Agent configuration (Basic-Auth Policy) screen, which now lists the newly created user name-password pair. Optionally, click Save Config to save the object to the startup configuration. SOAP Action Policy Certain User Agent requests require that the contents of the SOAPAction HTTP request header field be supplied. Click the Soap-Action Policy tab to display the User Agent configuration (SOAP-Action Policy) screen, which lists all SOAP actions. Click Add to display the SOAP Action Property window. Provide the following inputs: URL Matching Expression Define the target URL set that is associated with this policy. If the target URL matches this expression, the corresponding header will be inserted in the request to the resource. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character.? Indicates a single character that matches one occurrence of any single character. [] Indicates a delimited range of alphabetic or numeric characters. For example, [1-5] would match 1, 2, 3, 4, or5, and [x-y] would match x or y. You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. Soap Action Specify the SOAP action (a URI that identifies the intent of the SOAP HTTP request). In the following example, the Soap Action is: GetCatalogList POST /webservices/soap/endpoint HTTP/1.1 Host: www.somedomain.info Content-Type: text/xml; charset="utf-8" Content-Length: <length of HTTP request> SOAPAction: GetCatalogList Click Save to complete specification of the header field contents and return to the User Agent configuration (Soap-Action Policy) screen, which now lists the newly created SOAP action. Optionally, click Save Config to save the object to the startup configuration. Public Key Authentication Policy A User Agent can use public key authentication in its communications with remote resources. This feature is useful when the agent uses the SCP or SFTP protocol for communication. Click the PubKey-Auth Policy tab to set the configuration values for this feature. 120 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Click any existing policy to edit the policy, or click Add to create a new policy. The Public Key Property window is displayed. Provide the following inputs: URL Matching Expression Specify a URL Match expression in the URL Matching Expression field. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character.? Indicates a single character that matches one occurrence of any single character. [] Indicates a delimited range of alphabetic or numeric characters. For example, [1-5] would match 1, 2, 3, 4, or5, and [x-y] would match x or y. You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. Examples include the following: v https://server.domain.com/transactions/* v sftp://user@server.com/images/* v scp://user[a-c]@10.10.[0-4].23/inbound/* Private Key Select the desired private key. If the Crypto Key object needed is not presented in the list, click the + button to create the object. The Private Key file must be uploaded to the local appliance to create the Crypto Key object. The remote server must also possess the appropriate certificate. This certificate must reside in $HOME/.ssh/authorized_keys on the remote server. Click Save to add this policy to the list. Allow Compression Policy A User Agent can compress the payload of its communications with remote resources. This feature is useful when the payload is large. Click the Allow-Compression Policy tab to set the configuration values needed for this feature. Click any existing policy to edit the policy, or click Add to create a new policy. The Allow Compression Property window is displayed. Provide the following inputs: URL Matching Expression Specify a URL Match expression in the URL Matching Expression field. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character. Appendix A. Referenced objects 121

? Indicates a single character that matches one occurrence of any single character. [] Indicates a delimited range of alphabetic or numeric characters. For example, [1-5] would match 1, 2, 3, 4, or5, and [x-y] would match x or y. You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. Allow Compression Use the toggle to enable (on) or disable (off) compression. Click Save to add this policy to the list. Restrict to HTTP 1.0 Policy The User Agent can restrict HTTP communications to the HTTP 1.0 specification, if so desired. Use this Policy to control this behavior. Click the Restrict to HTTP 1.0 Policy tab. Click any existing policy to edit the policy, or click Add to create a new policy. The Restrict to HTTP 1.0 Policy Property window is displayed. Provide the following inputs: URL Matching Expression Specify a URL Match expression in the URL Matching Expression field. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character.? Indicates a single character that matches one occurrence of any single character. [] Indicates a delimited range of alphabetic or numeric characters. For example, [1-5] would match 1, 2, 3, 4, or5, and [x-y] would match x or y. You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. Restrict to HTTP/1.0 Use the toggle to enable (on) or disable (off) HTTP protocol restriction. Click Save to add this policy to the list. Inject Header Policy The User Agent can inject an HTTP Header and corresponding value into the communication with the remote server. Click the Inject Header Policy tab. Note: A Multi-Protocol Gateway can also inject HTTP headers. The User Agent operates on the communication after the gateway. Click any existing policy to edit the policy, or click Add to create a new policy. The Inject Header Property window is displayed. Provide the following inputs: 122 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

URL Matching Expression Specify a URL Match expression in the URL Matching Expression field. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character.? Indicates a single character that matches one occurrence of any single character. [] Indicates a delimited range of alphabetic or numeric characters. For example, [1-5] would match 1, 2, 3, 4, or5, and [x-y] would match x or y. You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. Header Name Specify the name of the HTTP Header to inject. Header Value Specify the corresponding value string for the injected header. Click Save to add this policy to the list. Chunked Uploads Policy The User Agent can use HTTP 1.1 Chunked content encoding. This is useful for streaming large documents. When the appliance employs the HTTP 1.1 protocol, the body of the document can be delimited by either Content-Length or chunked encoding. While all servers will understand how to interpret Content-Length, many applications will fail to understand Chunked encoding. For this reason, Content-Length is the standard method. However doing so interferes with the ability of the appliance to fully stream. To stream full documents towards the backend server, this property should be enabled. However, the backend server must be RFC 2616 compatible, because this feature cannot be renegotiated at run time, unlike all other HTTP 1.1 features that can be negotiated down at runtime if necessary. Click the Chunked Uploads Policy tab. Note: A Multi-Protocol Gateway can also control Chunked Uploads. The User Agent operates on the communication after the Multi-Protocol Gateway. Click any existing policy to edit the policy, or click Add to create a new policy. The Chunked Uploads Property window is displayed. Provide the following inputs: URL Matching Expression Specify a URL Match expression in the URL Matching Expression field. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character.? Indicates a single character that matches one occurrence of any single character. Appendix A. Referenced objects 123

[] Indicates a delimited range of alphabetic or numeric characters. For example, [1-5] would match 1, 2, 3, 4, or5, and [x-y] would match x or y. You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. Enable/Disable HTTP 1.1 Chunked Request Bodies Use the toggle to enable (on) or disable (off) chunked encoding. Click Save to add this policy to the list. FTP Client Policies The User Agent can associate a set of FTP URLs with a specified policy that controls the default values of many FTP client options for outgoing FTP connections. These controls can be further overridden by query parameters in the URL that is used to initiate the file transfer. Click the FTP Client Policies tab to display the User Agent configuration (FTP Client Policies) screen. Click any existing policy to edit or click Add to create a new policy to display the FTP Client Policies Property window. Provide the following inputs: URL Matching Expression Specify a shell-style expression that defines a URL set. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character.? Indicates a single character that matches one occurrence of any single character. [] Indicates a delimited range of alphabetic or numeric characters. For example, [1-5] would match 1, 2, 3, 4, or5, and [x-y] would match x or y. You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. Passive Mode Select how the use of FTP passive mode to control the direction in which FTP data connections are made. Passive Mode Not Requested Do not use the FTP PASV command to allow the client to open FTP data connections. The FTP server will open all data connections to the FTP client. Often, this mode is incompatible with firewalls. Request Passive Mode Use the FTP PASV command to request that the FTP client be allowed to open all data connections to the FTP server, but do not fail if the server does not support PASV. 124 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Require Passive Mode (Default) Use the FTP PASV command to request that the FTP client be allowed to open all data connections to the FTP server, and fail if the server does not support PASV. Encrypt Command Connection Select how to control the use of TLS to secure the FTP command connection. No Authentication Requested (Default) Do not use the FTP AUTH command to allow encrypt the command connection. The user name and password will be passed in the clear. Request TLS Authentication Use the FTP AUTH TLS command to encrypt the command connection, if available. Require TLS Authentication Use the FTP AUTH TLS command to encrypt the command connection. If not available, fail. Stop Command Encryption After Authentication Select how to control the cessation of FTP command channel encryption after user authentication. Encryption must be stopped for compatibility with NAT (Network Address Translation) and other firewall applications. Although this behavior might be a security risk, this behavior is the only option when a NAT is in use. Leave Encrypted (Default) Leave the FTP command connection encrypted after (optional) authentication of the USER and PASS commands. The command connection remains secure. This setting is not compatible with NAT and many firewalls. Request Stop Encryption Use the FTP CCC command to request the end of encryption of the command channel using TLS, if supported by the server. Require Stop Encryption Use the FTP CCC command to request the end of encryption of the command channel using TLS. If not supported, fail. Some servers do not support CCC. This setting is required for compatibility with NAT and many firewall. Encrypt File Transfers Select how to control the encryption of file transfers. All setting are compatible with NAT. Unencrypted Data (Default) Do not encrypt FTP data connections, even if the command channel is encrypted. Use the FTP PROT C command if command channel is encrypted or has been encrypted. Request Data Encryption Request encryption of FTP data connections using the FTP PROT P command. This setting requires that the command change is encrypted or has been encrypted. Do not fail if the server does not support data encryption. Require Data Encryption Request encryption of FTP data connections using the FTP PROT P Appendix A. Referenced objects 125

command. This setting requires that the command change is encrypted or has been encrypted. Fail if the server does not support data encryption. Data Type Select the default data type of file transfers. In most cases, the default value of binary is appropriate. ASCII Data Transfer files in ASCII mode. This setting allows for the standardizations of end-of-line conventions between different operating systems. This setting increases the overhead at both ends of the transfer. This setting uses the FTP TYPE A command. Image (Binary) Data (Default) Transfer files in image mode, which transfers data as binary 8-bit bytes. This setting is more efficient and has less overhead at both ends of the transfer. Some XML files, such as ones that are signed, must be transferred in image mode. This setting uses the FTP TYPE I command. Write Unique Filename if Trailing Slash Select whether the FTP server creates unique file names. Some FTP servers provide the STOU command. The STOU command causes the FTP server to choose a unique file name to write to in the current directory, instead of having the FTP client choose a unique name. When enabled and the URL end in a slash, the STOU command is used instead of the STOR command. Before enabling, ensure that the FTP server support the STOU command. Request Unique File Name When Trailing Slash (Default) If the supplied file name ends in a slash (before the question mark (?) character that initiates the query parameter, or the semicolon (;) character that begins the suffix), use the STOU command to request that the server generates a unique file name in the target directory. This behavior allows multiple systems to write files to the same directory without any risk of duplicate file names that overwrite each other. The transfer fails if the FTP server does not support the STOU command. Use Supplied File name Always uses the supplied file name to generate the target file name that is requested on the server. This setting uses the STOR command to initial the transfer. If the URL ends in a slash, the transfer generally fails, because there is only a directory specification (no file name). Quoted Commands Select an FTP Quoted Command to send to the FTP server before each STOU, STOR, orretr command. Size Check Select whether to perform a size check after a transfer. Disabled Do not perform this check. Optional (Default) If the FTP SIZE command is available, use it to check the size of the file after transfer. The SIZE command compares the 126 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Web Application Firewall returned value to the number of bytes that were transferred. If not equal, the transfer is marked as failing. Click Save to add this policy to the list. A Web Applications Firewall provides security, proxy, threat mediation and content processing services for a Web-based application (such as enrollment, benefits management, ticket sales, or a trading system). The Web Applications Firewall is designed to handle traffic that is primarily URL-encoded HTTP form POST operations (or HTTP GET with or without Query Strings) and not primarily Web services SOAP-based XML payloads (although XML traffic can be handled as well). The Web Application Firewall offers: v Destination service proxy v SSL termination v Authentication and authorization service v Rate limiting v Session start and timeout enforcement v URL-encoded name-value input processing v HTTP protocol filtering v Threat protection, such as SQL Injection v Cookie handling, including sign and encrypt v Error handling v XML and non-xml content processing 1. Select Objects Services Web Application Firewall to display the Web Application Firewall catalog. The catalog lists all Web Application Firewall objects that are configured in the current domain. 2. To edit an existing Web Application Firewall, click the name of the firewall in the catalog. To create a new Web Application Firewall service, click Add. The Web Application Firewall Configuration (Main) screen is displayed. 3. Provide the following inputs: Name Specify a unique name for this object. The name must be unique throughout the appliance. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Remote Host Specify the host name or IP address of the backend server. To use a load balancer, specify the name of the Load Balancer Group. If the appliance should employ an SSL connection to the backend server, configure an SSL Proxy Profile that in turn uses a Crypto Profile configured for client (or forward) connections. Remote Port Specify the TCP port number of the backend server. SSL Proxy Profile Select an existing SSL Proxy Profile to assign the SSL Proxy Profile to Appendix A. Referenced objects 127

this handler. When selected, communication with clients, the backend server, or both will use SSL in accordance with the configured Crypto Profile. v v To implement SSL communication with requesting clients, use an SSL Proxy Profile that uses a Crypto Profile configured as a Server (reverse) profile. Under Source Addresses, set the SSL check box for at least one source address. To implement SSL communication with the backend server, use an SSL Proxy Profile that uses a Crypto Profile configured as a Client (forward) profile. v To implement SSL communication with both requesting clients and the backend server, use an SSL Proxy Profile that uses a Crypto Profile configured for two-way SSL. Refer to Defining SSL Proxy Profile objects on page 19 for more information. Security Policy To establish the security policy to be enforced by this firewall, select an Application Security Policy. To override (disable) the defined request or response security policy that is defined by the selected Application Security Policy, click off for these fields on this configuration screen. Refer to Application Security Policy on page 97 for more information. XML Manager Select an existing XML Manager to assign that manager to this firewall. The default XML Manager is used if you do not create one. An XML Manager manages the compilation and caching of XSL style sheets and XML documents and provides configuration constraints on the size and parsing depth of XML documents. You can enable the streaming of XML operations by configuring the XML Manager to use a Streaming Compile Option Policy. Optionally, an XML Manager can employ a User Agent. The User Agent settings, in turn, can affect the behavior of the gateway when communicating with backend servers or with clients when returning responses. User Agent settings override settings on the XML Manager. More than one firewall can use the same XML Manager. Refer to XML Manager on page 142 for more information. Error Policy Select an existing Error Policy to assign that policy to this firewall. If any part of the Application Security Policy is violated, the rules in this policy handle the violation. This policy is the default policy that handles responses sent to the client. Because an Application Security Policy can also establish an Error Policy, the Error Policy established by the Application Security Policy overrides this selection. Refer to Error Policy on page 99 for more information. Request Security If disabled (off), no request-side security policies are enforced. All 128 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

requests are allowed through. This property overrides the request security policy that is defined in the selected Application Security Policy. Response Security If disabled (off), no response-side security policies are enforced. All responses are allowed through. This property overrides the response security policy that is defined in the selected Application Security Policy. 4. Click Apply to save the object to the running configuration. 5. Optionally, click Save Config to save the object to the startup configuration. Proxy Settings tab To modify the default proxy settings: 1. Click the Proxy Settings tab. 2. Provide the following inputs: Normalize URI When this property is enabled (on, the default), the URI is rewritten to make the URI RFC-compliant. Certain characters will be escaped; additionally, characters that are escaped that do not need to be are unescaped. This makes checking for attack sequences more reliable. Stream Output to Back Select the desired streaming behavior. Buffer Messages Buffers submitted messages until all processing is verified as complete. After verification, forward the message to the appropriate backend. Stream Messages Begins to send the message to the backend before all processing is complete. This behavior potentially increases processing speed. Select this option when the selected XML Manager has streaming enabled or when streaming of attachments is enabled. Stream Output to Front Select the desired streaming behavior. Buffer Messages Buffers submitted messages until all processing is verified as complete. After verification, forward the message to the appropriate requesting client. Stream Messages Begins to send the message to the requesting client all processing is complete. This behavior potentially increases processing speed. Select this option when the selected XML Manager has streaming enabled or when streaming of attachments is enabled. Back Side Timeout Specify the amount of time, in seconds, that a backside client-connection can be idle before being abandoned in a transaction. Front Side Timeout Specify the amount of time, in seconds, that a front-side client-connection can be idle before being abandoned in a transaction. Appendix A. Referenced objects 129

Back Persistent Timeout Specify the maximum amount of time, in seconds (in the range 0 through 86400, with a default of 180), that a gateway maintains an idle persistent TCP connection on the backside. Front Persistent Timeout Specify the maximum amount of time, in seconds (in the range 0 through 86400, with a default of 180), that a gateway maintains an idle persistent TCP connection on the front side. Header and URL Rewrite Policy Optionally assign a URL Rewrite Policy. This policy defines rules to rewrite the entire URL or a portion of the URL, to replace a header value in the message, or to rewrite the HTTP POST body in the message. The rewrite rules are applied before document processing. Therefore, the evaluation criteria in the Matching Rule is against the rewritten value. Refer to URL Rewrite Policy on page 114 for more information. 3. Click Apply to save the object to the running configuration. 4. Optionally, click Save Config to save the object to the startup configuration. HTTP Options tab To modify the default HTTP options: 1. Click the HTTP Options tab. 2. Provide the following inputs: HTTP Version to Server Select the HTTP version (HTTP 1.0 or HTTP 1.1, the default) to use on the server-side connection. Certain HTTP 1.1 features, such as chunked uploads, require the selection of 1.1. The backend server must also support HTTP 1.1 for the connection to be established and maintained using the HTTP 1.1 protocol. HTTP Response Version Select the HTTP version (HTTP 1.0 or HTTP 1.1, the default) to use on client responses. Incoming HTTP 1.0 requests will always be replied to with 1.0 compatible responses regardless of this setting. Use HTTP 1.1 to support chunked responses. Follow Redirects Some protocols generate redirects as part of the protocol; for example, HTTP response code 302. If this property is enabled (on, the default) the firewall tries to resolve the redirects. Rewrite Host Names When Gatewaying Some protocols have distinct name-based elements, separate from the URL, to demultiplex. HTTP uses the Host header for this purposes. When enabled (on, the default) the backside server receives a request that reflects the final route. When disabled (off) the backside server receives a request that reflects the information as it arrived at the DataPower appliance. Web servers that issue redirects might want to disable this feature. Web servers often depend on the Host header for the value of their redirect. Allow Chunked Uploads Enable (on) or disable (off, the default) the ability to send Content-Type Chunked Encoded documents to the backend server. 130 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

When the appliance uses the HTTP 1.1 protocol, the body of the document can be delimited by either Content-Length or chunked encoding. While all servers can interpret Content-Length, many applications fail to understand Chunked Encoded documents. For this reason, Content-Length is the standard method. Retaining the default value interferes with the ability of the appliance to stream full documents. To stream full documents toward the backend server, enable this property. When enabled, the backend server must be RFC 2616 compatible. This feature cannot be renegotiated at run time. All other HTTP 1.1 features can be negotiated at run time. Alternatively, this property can be enabled at the User Agent on a per-url basis. Refer to User Agent on page 117 for more information. HTTP Client IP Label Retain X-Client-IP, the default value, or provide another value (for example, X-Forwarded-For). 3. Click Apply to save the object to the running configuration. 4. Optionally, click Save Config to save the object to the startup configuration. Source Addresses tab Source addresses determine the IP addresses and TCP ports to assign to the service. Remote clients connect to these addresses. At least one source address must be configured. To add a source address, use the following procedure: 1. Click the Source Addresses tab to display the Source Addresses catalog. 2. Click Add. 3. Provide the following inputs: Local IP Address Specify the IP address, host name, or host alias on which the service listens. The default is 0.0.0.0. This value indicates that the service is active on all addresses. Port Number Specify the TCP port on which the service listens. Use an integer in the range of 1 through 65535. The default is 3000. SSL Indicates whether the service acts as an SSL server for requesting clients. v Select the check box to enable. v Ensure that the check box is not selected to disable. When enabled, the Crypto Profile of the selected SSL Proxy Profile handles these requests. 4. Click Save. 5. Repeat steps 2 through 4 to define additional source addresses. 6. Click Apply to save the object to the running configuration. 7. Optionally, click Save Config to save the object to the startup configuration. Appendix A. Referenced objects 131

Web Request Profile A Web Request Profile establishes the security policy to apply to requests that originate from clients. A Web Request Profile can do any or all of the following: v Allow or deny SSL communications v Perform authentication, authorization and audit v Rate limit traffic v Filter access by IP address v Establish error handling v Manage sessions v Filter HTTP methods v Filter HTTP header, URL-encoded HTTP POST, and HTTP Query String values v Manage XML traffic v Allow or disallow, encrypt or sign, and filter cookies v Provide service threat protection, such as filtering SQL injection attacks Select Objects Web Applications Web Request Profile to display the Web Request Profile catalog. This catalog lists all Web Request Profile objects. Click the name of an existing object to edit it. Click Add to create a new Web Request Profile. The Web Request Profile configuration screen is displayed. Provide the following inputs: Name Specify a name for this object. This name appears in the catalog listing and in all lists of available Web Request Profiles. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Mode Select the satisfaction style. Admission If a request passes the criteria defined in this profile, the client s request (the transaction request) is immediately forwarded to the backend service. No other matching profile is run. Prerequisite If a request passes the criteria defined in this profile, any other profile that matches the request can now run. The request is not necessarily forwarded to the backend service. However, if there are no other matching profile and the request passes this profile, the request is passed to the backend service. Each transaction could match more than a single request profile on the same transaction. If this happens, the satisfaction style helps determine how the results of those profiles are combined. A failed profile always results in the failure of the transaction; however, a passed profile of the prerequisite satisfaction style does not, on its own, guarantee acceptance of the transaction. In those circumstances, any other matching profiles will be run and the whole transaction only passes if no failure is found. The admission style, on the other hand, passes the transaction as soon as the profile is declared passing. 132 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Profile tab Click the Profile tab. Most profiles will be admission style, but a typical use of a prerequisite profile would be a broad match that enforces some very basic items (maximum sizes for example) that is followed up with more specific matches for stronger criteria. Provide the following inputs: Allow SSL Select a profile policy regarding SSL communications. Allow Allow SSL communications to the appliance. The connection might employ SSL. If the Web Application Firewall is not configured as an SSL server and the client attempts to use SSL, the connection is refused before this policy executes. Deny Do not allow SSL communications to the appliance. When this option is selected, an SSL connection request will be refused even when Web Application Firewall is configured to accept SSL connections from clients. This profile will only run when the corresponding match rule, established in the Application Security Policy, is met. Require Require SSL communications links to the appliance. The connection will not succeed unless the Web Application Firewall is configured as an SSL Server and the client requests SSL communications. AAA Policy Select an AAA Policy to establish AAA filtering on Web requests. Only those requests that successfully pass the AAA policy selected will be forwarded to the backend service. Leave the default selection (none) to enforce no authentication and authorization policy on requests. Any input to this transaction as XML, application/www-url-encoded, or multipart/form-data MIME types will be automatically provided to the AAA processing policy. Refer to AAA Policy on page 57 for more information. Rate Limiting Select a Rate Limit Policy to enforce rate limiting on Web requests. A Rate Limit Policy restricts identities (as determined by AAA or the client IP address if AAA has not been selected) to a specific number of transactions per second or a specific number of concurrent transaction connections. Refer to Rate Limiter on page 112 for more information. Retain the default value of (none) to not enforce rate limiting. To limit connections from a given IP address (after a count of requests from that address results in an error) hits a certain level, use an Error Policy (refer to Error Policy on page 99). An Error Policy allows for error count monitoring. Access Control List Select an Access Control List. This Access Control List will be used to allow or deny access to this service based on the IP address of the client. When attached to a service, an Access Control List denies all access by Appendix A. Referenced objects 133

default. To deny access to only selected addresses, first grant access to all addresses (allow 0.0.0.0) and then create deny entries for the desired hosts. Retain the default value of (none) to not enforce access control. Error Policy Select an Error Policy. This Error Policy will run when any client request violates this Web Request Profile. The Error Policy selected will also override any Error Policy selected at the Web Application Firewall object level. Retain the default value of (none) to not enforce no Error Policy. Refer to Error Policy on page 99 for more information. Session Policy Select a Session Policy. A Session Policy establishes the URLs that are acceptable starting points (start pages) for a Web application session. In addition, a Session Policy limits the duration of any session. Retain the default value of (none) to not enforce session management. Refer to Session Management Policy on page 113 for more information. Content-Type List Specify which content-type headers to allow on the request. Use a PCRE to define the allowed content types, such as text/xml. If you do not define any content type, all content types are allowed. v v Requests without a content type are assumed to have their content-type header set to an empty string. Requests without a body are not subject to this constraint. Methods & Versions tab Click the Methods & Versions tab to control the HTTP methods and versions accepted by this Profile. Provide the following inputs: Methods Use the check boxes to establish accepted HTTP methods. Any request that does not employ one of the checked methods will be rejected by the Profile. Versions Use the check boxes to establish accepted HTTP versions. Any request that does not employ one of the checked versions will be rejected by the Profile. Processing tab It is possible to perform actions on Web requests (such as transform XML content, if encountered, or send a copy of request content to a third location). Click the Processing tab to access these configuration options. Provide the following inputs: XML Processing Select how requests containing an XML MIME type in the HTTP header Content-type: field (text/xml, for example), are processed. No processing (Default) No processing performed. 134 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Well Formed XML The appliance parses the request to validate that the request is well-formed XML. The XML Transformation Rule specified then runs on the request and the result is used as the request content. Well Formed SOAP The appliance parses the request to validate that the request adheres to the SOAP specifications. The XML Transformation Rule specified then runs on the request and the result is used as the request content. XML Transformation Rule Select a Processing Rule for requests when they contain an XML MIME type and the XML processing policy is set to Well Formed XML or Well Formed SOAP. Refer to Processing Rule on page 111 for more information. Non-XML Processing Select how requests that do not contain an XML MIME type in the HTTP header Content-Type field (www-url-encoded, for example), are processed. No processing (Default) No processing performed. Side-Effect Rule The appliance executes the Non-XML Processing Rule specified. This rule cannot alter the content of the request (cannot access the INPUT and OUTPUT multistep processing contexts). The Rule can perform such actions as authenticate and authorize, or send a copy of the request content to a third destination. Binary Rule The appliance executes the Non-XML Processing Rule specified. The request payload is submitted as an non-parsed binary object. This rule can alter the content of the request. The Rule can perform such actions as authenticate and authorize, convert to XML, repackage with additional information retrieved from elsewhere or send a copy of the request content to a third destination. The result of this rule is then used as the request payload for further processing. Non-XML Processing Rule Select a Processing Rule for requests when they do not contain an XML MIME type and the XML processing policy is set to Side Effect or Binary. Refer to Processing Rule on page 111 for more information. Name Value tab The profile can filter the names and corresponding values of HTTP headers, URL-encoded HTTP Post body content or HTTP Query strings. These values can also be mapped to alternate values. This provides a means to control the name-value pairs passed to the backend server, thus providing both content control and threat protection. This is done using the inputs available on the Name Value tab. Provide the following inputs: Header Name-Value Profile Select a Name-Value Profile. Each HTTP header name-value pair will be Appendix A. Referenced objects 135

subjected to the rules set forth in the selected Profile. If no profile is specified, any header is allowed. Refer to Name-Value Profile on page 108 for more information. URL-Encoded Body Name-Value Profile Select a Name-Value Profile. Each element in the HTTP POST body will be subjected to the rules set forth in the selected Profile. If no profile is specified, any element is allowed. Refer to Name-Value Profile on page 108 for more information. Allow Query String Select an option to determine how to handle HTTP Query Strings. Allow Query strings are allowed. When selected, the Query String Name-Value Profile input is displayed. Deny Query strings are not allowed. Requests that contain query strings are rejected by this profile. Require Query strings must be present in the request. Requests without query strings are rejected by this profile. When selected, the Query String Name-Value Profile input is displayed. Query String Name-Value Profile Select a Name-Value Profile. Each query string name-value pair in the HTTP request is subject to the rules in the selected profile. If no profile is specified, any query string pair is allowed. Refer to Name-Value Profile on page 108 for more information. Cookie tab A Web Request Profile can manage cookies. Cookies can be allowed, denied or required. When cookies are not denied, the Profile can sign or encrypt cookies, as well as enforce filters on the name-value pairs contained in the cookie. Click the Cookie tab to access these configuration properties. Provide the following inputs: Allow Cookies Select how cookies are handled by this profile. Allow Cookies are allowed. When this option is selected, the Sign/Encrypt Cookies, and Cookie Content Name-Value Profile inputs appear. Deny Cookies are not allowed. Requests containing cookies will be rejected by this profile. Require Cookies must be present in the request. Requests with no cookies will be rejected by this profile. When this option is selected, the Sign/Encrypt Cookies, and Cookie Content Name-Value Profile inputs appear. Sign/Encrypt Cookies Select how to enable signing or encrypting of cookie content. Encrypt When this option is selected, the appliance encrypts outbound cookies sent by the backend application. When the client returns the cookie on a subsequent request, the appliance decrypts the 136 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

cookie before passing it back to the server. The Secret Key and IP Address-specific Cookie inputs appear when this option is selected. (none) (Default) Cookies are neither signed nor encrypted. This is the default. Sign When this option is selected, the appliance signs outbound cookies sent by the backend application. When the client returns the cookie on a subsequent request, the appliance verifies and removes the signature before passing it back to the server. The Secret Key and IP Address-specific Cookie inputs appear when this option is selected. Secret Key Signing or Encrypting cookies requires a secret password phrase for the cryptographic operation. If this key is the same on multiple appliances, then each appliance can verify or decrypt a cookie generated by another appliance without the need to maintain any state information. IP Address-specific Cookies Normally the signed or encrypted cookie contains the client IP address and this prevents the client from using this cookie from any other host. Some environments make this behavior undesirable. Disabling this property makes the generated cookies address independent. Cookie Content Name-Value Profile Select a Name-Value Profile. Each name-value pair in the cookie will be subjected to the rules set forth in the selected Profile. If no profile is specified, any query string pair is allowed. Refer to Name-Value Profile on page 108 for more information. Multipart Form tab This Web Request Profile can impose limits on multipart/form submissions. Click the Multipart Form tab to access these configuration options. Here is an example of a multipart/form submission. POST 116.xml HTTP/1.0 Host: patriot User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-us; rv:1.7.12) Gecko/20051010 Firefox/1.0.7 (Ubuntu package 1.0.7) Accept: text/xml,application/xml,application/xhtml+xml,text/html; q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5 Accept-Language: en-us,en;q=0.5 Accept-Encoding: gzip,deflate,rot13 Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7 Content-Type: multipart/form-data; boundary= -----------------------------1943549852707912569510983863 Content-Length: 1289 -----------------------------1943549852707912569510983863 Content-Disposition: form-data; name="upfile"; filename="notes" Content-Type: application/octet-stream /home/mcm/iso>sudo cdrecord dev=atapi:0,1,0 -v speed=4 x86-basic-1.4-20030911.iso -----------------------------1943549852707912569510983863 Content-Disposition: form-data; name="hdrx21" PRE1776 -----------------------------1943549852707912569510983863 Content-Disposition: form-data; name="hdrx25" Appendix A. Referenced objects 137

Post2000 -----------------------------1943549852707912569510983863 Provide the following inputs: Max Number of Parts Specify an integer to determine the maximum number of parts allowed in the request. This defaults to 4. Max Size Per Part Specify an integer to determine the maximum size, in bytes, per part. This defaults to 5000000. Max Aggregate Size of All Parts Specify an integer to determine the maximum size, in bytes, of all parts combined. This defaults to 5000000. Restrict Sub-Content Types Use the toggle to restrict types (on) or to allow all types (off). If enabled, this setting forces the individual form-data content types to be matched against the general list of request acceptable content-type expressions provided on the Main configuration panel for this Web Request Profile. Threat Protection tab Click the Threat Protection tab to access the configuration options that provide basic threat protection services, such as filtering for SQL Injection attacks, limiting the size of requests, or filtering potentially dangerous content based on URI. Provide the following inputs: Minimum Size Specify an integer to determine the minimum request body size in bytes if the HTTP method provides a body. The defaults is 0. Maximum Size Specify an integer to determine the maximum request body size in bytes if the HTTP method provides a body. The default is 128000000. SQL Injection Filter Set to on to cause the appliance to pass data parameters from the query string, application/www-urlencoded requests, and multipart/form-data requests through the standard SQL Injection filter. Maximum URI Length Specify an integer to determine the maximum URI length, in characters. Defaults to 1024. Filter Unicode Reject (on) or allow (off) requests if Unicode is detected in the URI. Defaults to on. Filter Dot Dot Reject (on) or allow (off) requests containing.. in URI after URI normalization has been performed. Defaults to on. Filter.exe Reject (on) or allow (off) requests containing exe in URI after URI normalization has been performed. Defaults to on. 138 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Web Response Profile Fragmented URI Policy A URI fragment is the portion of a URI after the hash (#) symbol. Select an option to determine a policy for handling URI fragments. Allow URI fragments are allowed. Reject If the request contains URI fragments, the request will be rejected by this profile. Truncate If the request contains URI fragments, the fragments will be removed from the request. A Web Response Profile establishes the security policy applied to responses returned from application servers. A Web Response Profile can do any or all of the following: v Establish error handling v Filter HTTP methods v Filter HTTP header values v Manage XML traffic v Provide service threat protection by managing response sizes Select Objects Web Applications Web Response Profile to display the Web Response Profile catalog. This catalog lists all Web Response Profile objects. Click the name of an existing object to edit it. Click Add to create a new Web Response Profile. The Web Response Profile configuration screen is displayed. Provide the following inputs: Name Specify a name for this object. This name appears in the catalog listing and in all lists of available Web Response Profiles. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Mode Select the satisfaction style. Admission If a response passes the criteria defined in this profile, the server response (the transaction response) is immediately forwarded to the client. No other matching profile is run. Prerequisite If a response passes the criteria defined in this profile, any other profile that matches the response can now run. The response is not necessarily forwarded to the backend service. However, if there are no other matching profile and the response passes this profile, the response is passed to the backend service. Each transaction could match more than a single response profile on the same transaction. If this happens, the satisfaction style helps determine how Appendix A. Referenced objects 139

the results of those profiles are combined. A failed profile always results in the failure of the transaction; however, a passed profile of the prerequisite satisfaction style does not, on its own, guarantee acceptance of the transaction. In those circumstances, any other matching profiles will be run and the whole transaction only passes if no failure is found. The admission style, on the other hand, passes the transaction as soon as the profile is declared passing. Most profiles will be admission style, but a typical use of a prerequisite profile would be a broad match that enforces some very basic items (maximum sizes for example) that is followed up with more specific matches for stronger criteria. Profile tab Click the Profile tab. Provide the following inputs: Error Policy Select an Error Policy. This Error Policy will run when any client response violates this Web response Profile. The Error Policy selected will also override any Error Policy selected at the Web Application Firewall object level. Leave the default (none) selected to enforce no Error Policy. Refer to Error Policy on page 99 for more information. Content-Type List Specify which content-type headers to allow on the response. Use a PCRE to define the allowed content types, such as text/xml. If you do not define any content type, all content types are allowed. v Responses without a content type are assumed to have their content-type header set to an empty string. v Responses without a body are not subject to this constraint. Codes & Versions tab Click the Codes & Versions tab to control the HTTP methods and versions accepted by this Profile. Provide the following inputs: Response Codes Use the check boxes to establish accepted HTTP methods. Any response codes that do not employ one of the checked methods will be rejected by the Profile. Response Versions Use the check boxes to establish accepted HTTP versions. Any response version that does not employ one of the checked versions will be rejected by the Profile. Processing tab It is possible to perform actions on Web responses (such as transform XML content, if encountered, or send a copy of response content to a third location). Click the Processing tab to access these configuration options. 140 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Provide the following inputs: XML Processing Select how responses containing an XML MIME type in the HTTP header Content-Type field (text/xml, for example), are processed. No processing (Default) No processing performed. Well Formed XML The appliance parses the response to validate that the response is well-formed XML. The XML Transformation Rule specified then runs on the response and the result is used as the response content. Well Formed SOAP The appliance parses the response to validate that the response adheres to the SOAP specifications. The XML Transformation Rule specified then runs on the response and the result is used as the response content. XML Transformation Rule Select a Processing Rule. The appliance applies this Processing Rule to responses when the response contains an XML MIME type and the XML processing policy is set to Well Formed XML or Well Formed SOAP. Refer to Processing Rule on page 111 for more information. Non-XML Processing Select how responses that do not contain an XML MIME type in the HTTP header Content-Type field (www-url-encoded, for example), are processed. No processing (Default) No processing performed. Side-Effect Rule The appliance executes the Non-XML Processing Rule specified. This rule cannot alter the content of the response (cannot access the INPUT and OUTPUT multistep processing contexts). The Rule can perform such actions as authenticate and authorize, or send a copy of the response content to a third destination. Binary Rule The appliance executes the Non-XML Processing Rule specified. The response payload is submitted as an non-parsed binary object. This rule can alter the content of the response. The Rule can perform such actions as authenticate and authorize, convert to XML, repackage with additional information retrieved from elsewhere or send a copy of the response content to a third destination. The result of this rule is then used as the response payload for further processing. Non-XML Processing Rule Select a Processing Rule. The appliance applies this Processing Rule to responses when the response does not contain an XML MIME type and the XML processing policy is set to Side Effect or Binary. Refer to Processing Rule on page 111 for more information. Name Value tab The Profile can filter the names and corresponding values of HTTP headers. These values can also be mapped to alternate values. This is done using the inputs available on the Name Value tab. Appendix A. Referenced objects 141

XML Manager Provide the following inputs: Header Name-Value Profile Select a Name-Value Profile. Each HTTP header name-value pair will be subjected to the rules set forth in the selected Profile. If no profile is specified, any header is allowed. Refer to Name-Value Profile on page 108 for more information. Threat Protection tab Click the Threat Protection tab to access the configuration options that provide basic threat protection services, by limiting the size of responses. Provide the following inputs: Minimum Size Specify an integer to determine the minimum response body size in bytes if the HTTP method provides a body. This defaults to 0. Maximum Size Specify an integer to determine the maximum response body size in bytes if the HTTP method provides a body. This defaults to 128000000. The firmware creates a default XML Manager object in the default domain and in each application. The default instance in each domain can be edited like any other instance of an XML Manager object. The default instance in each domain operates independently of each other. An XML Manager object obtains and manages XML documents, style sheets, and other document resources on behalf of one or more services. An XML Manager also provides the following capabilities: v v v v v v Basic network configuration, such as load balancing and accessing remote servers. Set manager-associated limits on the parsing of XML documents. By default, the appliance imposes limits on various characteristics of XML documents. These limitations provide for increased security and stability to protect against DoS attacks or runaway data. Parser limits defined by the XML Manager object that is associated with a service can be overridden by service-specific settings. Enable the caching of documents that this XML Manager object obtains. XML Manager objects obtain documents via HTTP. The number of documents in the cache depends on the availability of allocated memory. Define extension function mapping. An XML Manager object can automatically map custom style sheet extension functions to DataPower extension functions. This ability removes the need to alter or rewrite a style sheet for use by the appliance. The most common example is the node-set() extension function. If a service uses style sheets that reference the Microsoft node-set, Oracle node-set, or Salon nodeset XSLT extension functions, you must map these extensions to their DataPower equivalent. It is possible to map any extension function to a DataPower extension function. Define the caching policy for documents. This policy allows an administrator to determine how to cache documents. The policy defines the time-to-live, the priority, and the type. Enable schema validation by defining schema-validation rules. These rules apply to all documents that match predefined criteria. Alternatively, the appliance can 142 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

v validate documents with a validate action in a processing rule. Do not mix and match schema validation strategies. Policy-based schema validation is the preferred strategy. Schedule processing rules. Certain applications might require the running of a scheduled processing rule. Integration with a CA Unicenter Manager is facilitated by a regularly scheduled processing rule that obtains relationship data from the Unicenter Manager. Configure XML Manager objects The specification of the name completes the required configuration. The remaining properties modify default values or implement enhanced behavior. For information about the configuration properties, refer to the online help. To configure an XML Manager: 1. Select Objects XML Processing XML Manager to display the catalog. 2. Click Add to display the configuration screen. 3. On the Main tab, define the basic configuration. 4. On the XML Parser Limits tab, define the limits to impose when parsing XML documents. 5. On the Document Cache tab, define the caching of documents that are obtained via HTTP. 6. On the Extension Functions tab, define the maps for custom extension functions to DataPower extension functions. 7. On the Document Cache Policy tab, define the documents to store in the document cache. 8. On the Schema Validation Rules tab, define rules to enforce validation of all documents that match the defined criteria. 9. On the Scheduled Processing Policy Rule tab, define scheduled processing rules. 10. Click Apply to save the object to the running configuration. 11. Optionally, click Save Config to save the object to the startup configuration. Flushing the document cache The appliances maintains a cache of documents. To flush the cache, click Flush Document Cache. This function is available from the following screens: v The configuration screen for an XML Manager object (Objects XML Processing XML Manager) v The status screen for the document cache (Status XML Processing Document Cache) Flushing the stylesheet cache The appliances maintains a cache of style sheets. To flush the cache, click Flush Stylesheet Cache. Note: After a change to a Compile Options Policy object, flush the stylesheet cache. Otherwise, the XML Manger object continues to use the previous compiled style sheets until they are recompiled. This function is available from the following screens: Appendix A. Referenced objects 143

v z/os NSS Client v The configuration screen for an XML Manager object (Objects XML Processing XML Manager) The status screen for the stylesheet cache (Status XML Processing Stylesheet Cache) The z/os NSS client enables integration with RACF on the z/os Communications Server. The z/os NSS Client object specifies the authentication information required to allow the DataPower appliance to function as an NSS client. The z/os NSS Client object specifies the following properties: v Remote Address v Remote Port v SSL Proxy Profile v Client ID v System Name v User Name v Password Based on these properties and the request type, the following actions occur: v DataPower requests a secure connection to the z/os Communications Server v RACF performs authentication of users v RACF performs authorization to resources v RACF logs authorized and unauthorized attempts to access RACF-protected resources v z/os Communications Server NSS protocol provides return codes and reason codes for connectivity requests To support this functionality, the NSS server must be configured to support the NSS client. See the following z/os Communications Server documentation for these configuration steps: v v v Enable the XMLAppliance discipline support. For further information, refer to the section on network security services server in the z/os Communications Server: IP Configuration Reference. Authorize the client userid to SAF profiles representing security services and resources. For further information, refer to the section on preparing to provide network security services in the z/os Communications Server: IP Configuration Guide. Configure SSL for the TCP connection between the client and server. For further information, refer to the section on configuring the NSS server in the z/os Communications Server: IP Configuration Guide. Only one physical connection per Remote Address, Remote Port, and Client ID is allowed. Additional z/os NSS Client objects might be configured, but if more than one client with the same tuple try to connect, the connection will fail. If the connection is not established or the provided parameters are not valid, the object operational state is down and shows one of the following event codes: v Invalid registration parameters v TCP connection retry (interval is 1 minute) v TCP connection in progress v Communication failed 144 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

v Cannot connect to host For additional information on logged NSS protocol return codes and reason codes, refer to http://www.ibm.com/support/docview.wss?rs=852&uid=swg21329236 for z/os Communications Server: IP Diagnosis Guide updates. Contact NSS for SAF Authentication is selected as the Authenticate method in the AAA policy configuration and Contact NSS for SAF Authorization is selected for the Authorization method. Creating the z/os NSS Client To configure a z/os NSS client, use the following procedure: 1. Select OBJECTS z/os Configurations z/os NSS Client to display the catalog. 2. To display the configuration screen, click Add. 3. Specify the name of the object in the Name field. 4. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. 5. Specify a descriptive object-specific summary in the Comment field. 6. Specify the IP address or hostname of the NSS server in the Remote Address field. 7. Specify the port on which the NSS server listens in the Remote Port field. 8. Select an SSL Proxy Profile in the SSL Proxy field to provide a secure connection to the remote authentication server. 9. Specify the client ID to be used for registration with the NSS server in the Client ID field. 10. Specify the system name to identify the NSS client to the NSS server in the System Name field. 11. Specify the user name to use to authenticate with the SAF in the User Name field. 12. Specify the password to use to authenticate with the SAF in the Password field. 13. Reenter the password in the Confirm Password field. 14. Click Apply to save the object to the running configuration. 15. Optionally, click Save Config to save the object to the startup configuration. Appendix A. Referenced objects 145

146 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Appendix B. Working with variables Variables can be used in most context, except PIPE. To use a variable, you must create it with the Set Variable action. This action creates a variable in a specified context and assigns it a value. There are the following distinct variable types, each expressed in the var://url format: var://local/variable A local context variable to addresses a variable called variable in the default (current) context. The following example transforms the document in the tmp1 context with a style sheet that is referenced by the stylesheet-1 variable (also in the tmp1 context) and stores the transformed document in the tmp2 context: xform tmp1 var://local/stylesheet-1 tmp2 The local context does not persist beyond the scope of the multistep transaction. A multistep transaction can include both a request component and a response component. The local context cannot be accessed by any object outside of the scope of the multistep transaction. In other words, the service cannot read and use the variable. A local context variables can be user-defined or based on an extension variable. For a complete list of the available extension variables, refer to Extension variables on page 156. var://context/context/variable Addresses a variable called variable in a context called context. The following example transforms the document in the tmp1 context with a style sheet that is referenced by the stylesheet-1 variable (in the apple context) and stores the transformed document in the tmp2 context: xform tmp1 var://context/apple/stylesheet-1 tmp2 A named context does not persist beyond the scope of the multistep transaction. A multistep transaction can include both a request component and a response component. The local context cannot be accessed by any object outside of the scope of the multistep transaction. In other words, the service cannot read and use the variable. Note: Creating variables in a named context is the recommended approach. This form decouples the variable from the input and output contexts and allows the variable to be accessed from any step in a multistep scope. A named context variables can be user-defined or based on an extension variable. For a complete list of the available extension variables, refer to Extension variables on page 156. var://service/variable Address a variable that is made available to a service (such as HTTP or XSL Co-Processor) that is attached to a multistep session. The majority of service variables are read-only and cannot be set. Copyright IBM Corp. 2002, 2009 147

Service variables For a complete list of the available service variables, refer to Service variables. var://system/variable Addresses a global variable that is available in all contexts. System variables persist beyond the multistep scope and can be read by other objects in the system. If the content of a variable needs to be read or set outside the scope of the multistep process, use a system variable. For a complete list of the available global system variables, refer to System variables on page 158. Note: Refer to List of available variables on page 159 for the list of variables that you can define for document processing. Service variables enable the setting and retrieval of pieces of state that usually reflect the state of the current transaction. The available service variables are separated alphabetically into the following categories: v Service variables that are available to all DataPower services v v v v Service variables that are available to only Multi-Protocol Gateway and Web Service Proxy services Configuration services Load balancer service Legacy MQ-specific services General service variables This section contains information about general variables in alphabetic order by permission category. General variables are available to all services. Table 1 lists the names and permission for these variables. Table 1. Names and permissions for variables that are available to all DataPower services Variable name var://service/soap-fault-response Permission Read-write Read-write variables var://service/soap-fault-response Set when the response input rule is treated as a SOAP fault. Multi-Protocol Gateway and Web Service Proxy service variables This section contains information about general service variables for Multi-Protocol Gateway and Web Service Proxy services in alphabetic order by permission category. Table 2 lists the names and permission for these variables. Table 2. Names and permissions for general service variables that are available to only Multi-Protocol Gateway and Web Service Proxy services Variable name var://service/mpgw/backend-timeout Permission Read-write 148 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Table 2. Names and permissions for general service variables that are available to only Multi-Protocol Gateway and Web Service Proxy services (continued) Variable name Permission var://service/mpgw/skip-backside Write-only var://service/reply-to-q Write-only var://service/reply-to-qm Write-only Write-only variables var://service/mpgw/skip-backside For Multi-Protocol Gateway and Web Service Proxy services only, indicates that the service skips backside processing. Set this variable to 1 to prevent backside processing. Use this variable as a custom redirect implementation, not as the point of the service. Because the service is not aware of the processing flow, unusual messages might be written to the event log. Read-write variables var://service/mpgw/backend-timeout For Multi-Protocol Gateway and Web Service Proxy services only, gets or sets the backend timeout, in seconds. Setting this variable overrides the default timeout. Use an integer in the range of 1 through 86400. var://service/reply-to-q Read and write the value in the ReplyToQ (Reply to Queue) MQ header. When read, shows the input message value. When write, changes the dynamic routing. var://service/reply-to-qm Read and write the value in the ReplyToQMgr (Reply to Queue Manager) MQ header. When read, shows the input message value. When write, changes the dynamic routing. Configuration services service variables This section contains information about variables for configuration services in alphabetic order by permission category. Table 3 lists the names and permission for these variables. Table 3. Names and permissions for variables that are available for configuration services Variable name Permission var://service/config-param Write-only var://service/max-call-depth Read-write Write-only variables var://service/config-param/parametername value Sets the specified stylesheet parameter to the specified value. Read-write variables var://service/max-call-depth Gets or sets the maximum call depth for each transaction. This variable controls how many levels of called rules can be layered before an error is thrown. The default is 128. Appendix B. Working with variables 149

Load balancer service variables This section contains information about load balancer variables in alphabetic order by permission category. Table 4 lists the names and permission for these variables. Table 4. Names and permissions for variables that are available for load balancers Variable name Permission var://service/lbhealth/ Write-only Write-only variables var://service/lbhealth/ Sets the member and state of a load balancer group. Legacy MQ-specific service variables This section contains information about MQ-specific variables in alphabetic order by permission category. MQ-specific variables are available to only the legacy MQ Host and MQ Proxy services. Table 5 lists the names and permission for these variables. Table 5. Names and permissions for service variables that are available to MQ Host and MQ Proxy services Variable name Permission var://service/correlation-identifier Read-write var://service/expiry Read-write var://service/format Read-write var://service/message-identifier Read-write var://service/message-type Read-write var://service/mq-ccsi Write-only var://service/mqmd-reply-to-q Write-only var://service/mqmd-reply-to-qm Write-only var://service/persistence Read-write var://service/priority Read-write var://service/reply-to-q Read-write var://service/reply-to-qm Read-write var://service/report Read-write Write-only variables var://service/mq-ccsi Sets the MQ message descriptor character set for an MQ Host or MQ Proxy service. var://service/mqmd-reply-to-q Sets the output MQ message descriptor.replytoq value for an MQ Host or MQ Proxy service. var://service/mqmd-reply-to-qm Sets the output MQ message descriptor.replytoqmgr value for an MQ Host or MQ Proxy service. 150 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Read-write variables var://service/correlation-identifier Read and write the MQ value in the Correlation Identifier header for MQ Host and MQ Proxy services. var://service/expiry Read and write the MQ value in the Expiry header for MQ Host and MQ Proxy services. var://service/format Read and write the MQ value in the Format header for MQ Host and MQ Proxy services. var://service/message-identifier Read and write the MQ value in the Message Identifier header for MQ Host and MQ Proxy services. var://service/message-type Read and write the MQ value in the Message Type header for MQ Host and MQ Proxy services. var://service/persistence Read and write the MQ value in the Persistence for MQ Host and MQ Proxy services. var://service/priority Read and write the MQ value in the Priority header for MQ Host and MQ Proxy services. var://service/reply-to-q Read and write the MQ value in the ReplyToQ (Reply to Queue) header for MQ Host and MQ Proxy services. When read, shows the input message value. When write, changes the dynamic routing. var://service/reply-to-qm Read and write the MQ value in the ReplyToQMgr (Reply to Queue Manager) header for MQ Host and MQ Proxy services. When read, shows the input message value. When write, changes the dynamic routing. var://service/report Read and write the MQ value in the Report header for MQ Host and MQ Proxy services. Multistep variables This section contains information about system variables in alphabetic order by permission category. Multistep variables usually impact the behavior of specific actions in the context of a processing rule. Table 6 lists the names and permission for these variables. Table 6. Names and permissions for variables that are available to all services Variable name Permission var://service/log/soapversion Read-write Read-write variables var://service/log/soapversion Gets or sets the version of SOAP for use by a SOAP log targets. Use a setvar action before a log action to change the version of SOAP to use when logging this message. Appendix B. Working with variables 151

Transaction variables Supports the following values: soap11 Uses SOAP 1.1. soap12 (Default) Uses SOAP 1.2. The available transaction variables are separated alphabetically into the following categories: v Asynchronous transactions v Error handling v Headers v Persistent connections v Routing v URL v Web Services Management (WSM) Asynchronous transaction variables This section contains information about asynchronous transaction variables in alphabetic order by permission category. Table 7 lists the names and permission for these variables. Table 7. Names and permissions for variables that are available for asynchronous transactions Variable name Permission var://service/soap-oneway-mep Read-write var://service/transaction-key Write-only var://service/transaction-name Write-only var://service/transaction-timeout Write-only Write-only variables var://service/transaction-key Sets the token for asynchronous transactions. var://service/transaction-name Sets the name for asynchronous transactions. var://service/transaction-timeout Sets the timeout for asynchronous transactions. Read-write variables var://service/soap-oneway-mep Gets or sets the SOAP one-way Message Exchange Pattern (MEP) notification. v When true, notifies the service layer that this transaction is performing a one-way MEP operation. This setting enables the service layer to optimize resource usage while preventing Web Services Addressing (WSA) from waiting for and faulting on a response that will never arrive. v When false, no notification is sent. When using WSA and one-way MEPs, the service layer will time out waiting for a response. When a DataPower service is configured for WSA-to-WSA and it receives a WSA annotated message without the wsa:messageid, the DataPower service 152 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

assumes that this is a one-way MEP and notifies the service layer by setting this value of this variable to true. This variable is not needed for Web Service Proxy services, as one-way MEPs are identified by reviewing the specifics of the port operation. Error handling transaction variables This section contains information about error handling variables in alphabetic order by permission category. Table 8 lists the names and permission for these variables. Table 8. Names and permissions for variables that are available for error handling Variable name Permission var://service/error-code Read-write var://service/error-ignore Read-write var://service/error-message Read-write var://service/error-protocol-reason-phrase Write-only var://service/error-protocol-response Write-only var://service/error-subcode Read-write var://service/strict-error-mode Read-write Write-only variables var://service/error-protocol-reason-phrase Sets the protocol-specific reason phrase for an error. This variable overwrites the reason phrase in the response to provide a short description that an be understood by people. var://service/error-protocol-response Sets the protocol-specific response for an error. This variable overwrites the protocol-specific response code in an error condition. Read-write variables var://service/error-code Gets or sets the assigned error code from the Result Code table. var://service/error-ignore Gets or sets a flag that controls how the Front Side Handler processes error condition. If the value is set and greater than zero, it does not run any error handling action and produces a regular response. The content of the message is produced by an error rule. The default value is 0. Currently, on the TIBCO EMS and WebSphere JMS Front Side Handler use this variable. If any error happens and the variable is set, the Front Side Handler acknowledges a request message and puts the response message in the PUT queue. This response message will be a SOAP-fault or any output that error rule generates. var://service/error-message Gets or sets the generic error message that is sent to the client. This variable contains the error condition that stopped multistep processing. Setting this variable overwrites the error response that is sent to the client in an error condition. To set the error message that is written to the log file, use the var://service/formatted-error-message variable. Appendix B. Working with variables 153

var://service/error-subcode Gets or sets the error sub-code. This variable can help to disambiguate the reason for which the error rule was invoked. Often, the sub-code is the same as the value of the var://service/error-code variable. Sometimes, the sub-code is a more specific result code. var://service/strict-error-mode Gets or sets the strict error mode. This variable controls the error mode for multistep processing. v v If the value is set, an invocation of the dp:reject extension element stops multistep processing. If the value is not set, an invocation of the dp:reject extension element logs a message but does not stop multistep processing. Headers transaction variables This section contains information about header variables in alphabetic order by permission category. Table 9 lists the names and permission for these variables. Table 9. Names and permissions for variables that are available for headers Variable name var://service/append-request-header/ var://service/append-response-header/ var://service/set-request-header/ var://service/set-response-header/ Permission Write-only Write-only Write-only Write-only Write-only variables var://service/append-request-header/ Appends to the protocol request header. var://service/append-response-header/ Appends to the protocol response header. var://service/set-request-header/ Sets the protocol request header. This variable directly correlates to the dp:set-request-header() extension function. Setting the var://service/set-request-header/foo variable to the value BAR would set the request header FOO to BAR. var://service/set-response-header/ Sets the protocol response header. This variable directly correlates to the dp:set-response-header() extension function. Setting the var://service/set-response-header/foo variable to the value BAR would set the response header FOO to BAR. Persistent connection transaction variables This section contains information about persistent connection variables in alphabetic order by permission category. Table 10 lists the names and permission for these variables. Table 10. Names and permissions for variables that are available for persistent connections Variable name var://service/connection/note Permission Read-write 154 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Read-write variables var://service/connection/note Gets or sets the annotation for the current connection. This variable allows the user to annotate the current protocol session. The value could be an identifier that could be used to maintain the state based on an existing protocol session. Routing transaction variables This section contains information about routing variables in alphabetic order by permission category. Table 11 lists the names and permission for these variables. Table 11. Names and permissions for variables that are available for routing Variable name var://service/routing-url var://service/routing-url-sslprofile Permission Write-only Write-only Write-only variables var://service/routing-url For XML Firewall, Multi-Protocol Gateway, and Web Service Proxy services, sets the routing URL. This variable can be set one time only and takes the following format: <dp:set-variable name="var://service/routing-url" value="'protocol://target/uri'" /> v For XML Firewall services: The protocol must be HTTP or HTTPS. If any other protocol, the service generates an error. The URI is stripped. To specify the URI, use the var://service/uri variable, as shown in the following excerpt: <dp:set-variable name="'var://service/routing-url'" value="'http://10.10.36.11:2064'" /> <dp:set-variable name="'var://service/uri'" value="'/service'" /> v For Multi-Protocol Gateway and Web Service Proxy services: The protocol can be any valid backend protocol. The URI is absolute and cannot be controlled with the Propagate URI toggle (WebGUI) or propagate-uri command. The var://service/routing-url variable is an addition to the dp:set-target and dp:xset-target extension elements. These extension elements do not allow the specification of a protocol. These extension element, if provided, overrides the value of the target server that is specified in this variable. var://service/routing-url-sslprofile Sets the SSL proxy profile for the routing URL (dynamic route). Use this variable when the ssl property for the DataPower service is not sufficient for the route to be selected. Use this variable before using the var://service/routing-url variable. URL-based transaction variables This section contains information about URL-based transaction variables in alphabetic order by permission category. Table 12 on page 156 lists the names and permission for these variables. Appendix B. Working with variables 155

Table 12. Names and permissions for variables that are available for URL-based transactions Variable name Permission var://service/uri Read-write Read-write variables var://service/uri Gets or sets the request URI of the transaction. Web Services Management transaction variables This section contains information about Web Services Management (WSM) variables in alphabetic order by permission category. Table 13 lists the names and permission for these variables. Table 13. Names and permissions for variables that are available to WSM Variable name Permission var://service/wsa/timeout Read-write var://service/wsa/genpattern Read-write var://service/wsm/wsdl-error Write-only var://service/wsm/wsdl-warning Write-only Extension variables Write-only variables var://service/wsm/wsdl-error Sets the WSDL error. var://service/wsm/wsdl-warning Sets the WSDL warning. Read-write variables var://service/wsa/timeout Gets or sets the timeout value for the WS-Addressing asynchronous reply. var://service/wsa/genpattern Gets or sets the pattern for the WS-Addressing asynchronous reply. This section contains information about system variables in alphabetic order by permission category. Extension variables usually impact the behavior of specific actions, particularly fetch, results, and results-async actions. Table 14 lists the names and permission for these variables. Table 14. Names and permissions for extension variables Variable name var://local/_extension/allow-compression var://local/_extension/donot-follow-redirect var://local/_extension/header/ var://local/_extension/http-10-only var://local/_extension/prevent-persistent-connection var://local/_extension/sslprofile Permission Write-only Write-only Write-only Write-only Write-only Write only 156 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Write-only variables var://local/_extension/allow-compression Enables compression of HTTP requests. Set this variable to allow compression of outgoing results content and negotiate the returned document to be compressed if the underlying protocol supports it. For HTTP, this means the content-encoding and accept-encoding headers. var://local/_extension/donot-follow-redirect Disables HTTP redirects. Set this variable to prevent the following of protocol-level redirect sequences on the outgoing results and fetch calls that are associated with this context. By default, redirects are followed. var://local/_extension/header/ Appends the specified header field to the protocol connection. Variables of the following form can be set to append headers to the dp:url-open() extension function or results action or fetch action connection when a context that contains them is used as the input context: _extension/header/* The following example would add the HTTP header X-foo: bar to the HTTP request: setvar tmpvar2 var://local/_extension/header/x-foo bar results tmpvar2 http://foo.bar.com/foome.asp tmpvar3" var://local/_extension/http-10-only Restricts HTTP to version 1.0. Set this variable to prevent the use of HTTP/1.1 on the related context of a results action or fetch action. var://local/_extension/prevent-persistent-connection Disables HTTP persistent connection. Set this variable to prevent persistent connections of the outgoing a results action call or fetch action call that is associated with this context. Persistent connections are supported by default, where appropriate. var://local/_extension/sslprofile Sets the SSL proxy profile for the request. This variable can be set on the input context to a dp:url-open() extension function or to a results action or to a fetch action to override the selection of an SSL Proxy Profile. For instance: results tmpvar2 https://foo.bar.com/foome.asp tmpvar3 would normally use the SSL Proxy Profile that is associated with any user-agent configuration for the URL https://foo.bar.com/foome.asp If the profile needed to be determined programmatically, perhaps based on AAA, it could be set up as follows to dynamically resolve the value of *sslprofiletouse: setvar tmpvar2 var://local/_extension/sslprofile var://context/notepad/sslprofiletouse results tmpvar2 https://foo.bar.com/foome.asp tmpvar3 var://local/_extension/timeout Sets the request timeout on an input context to override any previously set timeout parameter. Set the value in seconds. Appendix B. Working with variables 157

System variables This section contains information about system variables in alphabetic order by permission category. Table 15 lists the names and permission for these variables. Table 15. Names and permissions for system variables Variable name var://system/map/debug var://system/tasktemplates/debug Permission Read-write Read-write Read-write variables var://system/map/debug Gets or sets the debugging level for role-based management (RBM). var://system/tasktemplates/debug Gets or sets the debugging level for task templates. 158 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

List of available variables Table 16 lists the variables that you can define for document processing. Table 16. All available variables Short variable name Full variable name Category allow-compression var://local/_extension/allow-compression Extension append-request-header var://service/append-request-header Transaction, headers append-response-header var://service/append-response-header Transaction, headers backend-timeout var://service/mpgw/backend-timeout Service, general config-param var://service/config-param Service, configuration correlation-identifier var://service/correlation-identifier Service, MQ debug var://system/map/debug System var://system/tasktemplates/debug donot-follow-redirect var://local/_extension/donot-follow-redirect Extension error-code var://service/error-code Transaction, error handling error-ignore var://service/error-ignore Transaction, error handling error-message var://service/error-message Transaction, error handling error-protocol-reason-phrase var://service/error-protocol-reason-phrase Transaction, error handling error-protocol-response var://service/error-protocol-response Transaction, error handling error-subcode var://service/error-subcode Transaction, error handling expiry var://service/expiry Service, MQ format var://service/format Service, MQ genpattern var://service/wsa/genpattern Transaction, WSM header var://local/_extension/header Extension http-10-only var://local/_extension/http-10-only Extension lbhealth var://service/lbhealth Service, load balancer max-call-depth var://service/max-call-depth Service, configuration message-identifier var://service/message-identifier Service, MQ message-type var://service/message-type Service, MQ mq-ccsi var://service/mq-ccsi Service, MQ mqmd-reply-to-q var://service/mqmd-reply-to-q Service, MQ mqmd-reply-to-qm var://service/mqmd-reply-to-qm Service, MQ note var://service/connection/note Transaction, persistent connection Appendix B. Working with variables 159

Table 16. All available variables (continued) Short variable name Full variable name Category persistence var://service/persistence Service, MQ prevent-persistent-connection var://local/_extension/prevent-persistentconnection Extension priority var://service/priority Service, MQ reply-to-q var://service/reply-to-q Service, MQ reply-to-qm var://service/reply-to-qm Service, MQ report var://service/report Service, MQ routing-url var://service/routing-url Transaction, routing routing-url-sslprofile var://service/routing-url-sslprofile Transaction, routing set-request-header var://service/set-request-header Transaction, headers set-response-header var://service/set-response-header Transaction, headers skip-backside var://service/mpgw/skip-backside Service, general soap-fault-response var://service/soap-fault-response Service, general soap-oneway-mep var://service/soap-oneway-mep Transaction, asynchronous soapversion var://service/log/soapversion Service, multistep sslprofile var://local/_extension/sslprofile Extension strict-error-mode var://service/strict-error-mode Transaction, error handling timeout var://service/wsa/timeout Transaction, WSM transaction-key var://service/transaction-key Transaction, asynchronous transaction-name var://service/transaction-name Transaction, asynchronous transaction-timeout var://service/transaction-timeout Transaction, asynchronous URI var://service/uri Transaction, URL wsdl-error var://service/wsm/wsdl-error Transaction, WSM wsdl-warning var://service/wsm/wsdl-warning Transaction, WSM 160 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Appendix C. Getting help and technical assistance Searching knowledge bases Getting a fix This section describes the following options for obtaining support for IBM products: v Searching knowledge bases v Getting a fix v Contacting IBM Support on page 162 If you encounter a problem, you want it resolved quickly. You can search the available knowledge bases to determine whether the resolution to your problem was already encountered and is already documented. Documentation The IBM WebSphere DataPower documentation library provides extensive documentation in Portable Document Format (PDF). You can use the search function of Adobe Acrobat to query information. If you download and store the documents in a single location, you can use the search facility to find all references across the documentation set. IBM Support If you cannot find an answer in the documentation, use the Search Support feature from the product-specific support page. From the Search Support (this product) area of the product-specific support page, you can search the following IBM resources: v IBM technote database v IBM downloads v IBM Redbooks v IBM developerworks A product fix might be available to resolve your problem. To determine what fixes are available for your IBM product, check the product support site by performing the following steps: 1. Go to the IBM Support site at the following Web address: http://www.ibm.com/support 2. Select Support & Downloads Download to open the Support & downloads page. 3. From the Category list, select WebSphere. 4. From the Sub-Category list, select WebSphere DataPower SOA Appliances. 5. Click the GO icon to display the list of most recent updates. 6. Click the link for the firmware and documentation download that is specific to your WebSphere DataPower product. 7. Follow the instructions in the technote to download the fix. Copyright IBM Corp. 2002, 2009 161

Contacting IBM Support IBM Support provides assistance with product defects. Before contacting IBM Support, the following criteria must be met: v Your company has an active maintenance contract. v You are authorized to submit problems. To contact IBM Support with a problem, use the following procedure: 1. Define the problem, gather background information, and determine the severity of the problem. For help, refer to the Software Support Handbook. To access the online version of this handbook, use the following procedure: a. Access the IBM Software Support Web page at the following Web address: http://www.ibm.com/software/support b. Scroll down to the Additional support links section of the page. c. Under Support tools, click the Software Support Handbook link. d. Bookmark this page for future reference. From this page, you can obtain a PDF copy of the handbook. 2. Gather diagnostic information. a. Access the product support at the following Web address: http://www.ibm.com/software/integration/datapower/support b. Locate the Assistance area of the product support page. c. Click Information to include to access that technote that lists the information that is required to report a problem. 3. Submit the problem in one of the following ways: Online From the IBM Support Web site (http://www.ibm.com/support), select Support & Downloads Open a service request. Following the instructions. By phone For the phone number to call in your country, refer to Contacts in the Software Support Handbook. From the Software Support Handbook Web site, click Contacts. In the U.S. and Canada, call 1 800 IBM-SERV (1 800 426 7378) and select option 2 for software. If the problem you should submit is for a software defect or for missing or inaccurate documentation, IBM Support creates an authorized program analysis report (APAR). The APAR describes the problem in detail. Whenever possible, IBM Support provides a workaround that you can implement until the APAR is resolved and a fix is delivered. 162 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Notices and trademarks This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information about the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user s responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements or changes in the product(s) or the program(s) described in this publication at any time without notice. Trademarks IBM, the IBM logo, CICS, developerworks, DB2, DataPower, IMS, RACF, Redbooks, Tivoli, WebSphere, and z/os are registered trademarks of the International Business Machines Corporation in the United States or other countries. Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries. Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Copyright IBM Corp. 2002, 2009 163

Other company, product, and service names may be trademarks or service marks of others. 164 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Index Special characters... button list of referenced object 3 referenced object 2.java.policy file 37 [configuration-database] stanza, file entry 89 [ldap] stanza, ssl-keyfile-pwd entry 89 [manager] stanza, replica entry 89 + button list of referenced object 3 referenced object 2 A AAA authentication search parameters 100 search parameters 100 TFIM 90 AAA Info File Authenticate element 84 Authorize element 85 editor authenticated identities 85 authorized access to resources 87 confirmation 88 credentials 85 default credential 85 file information 87 map credentials 86 map resources 86 overview 85 unauthenticated identity 85 MapCredentials element 84 MapResource element 84 overview 83 AAA Policy AAA Info File Authenticate element 84 Authorize element 85 MapCredentials element 84 MapResource element 84 overview 83 file editor authenticated identities 85 authorized access to resources 87 confirmation 88 credentials 85 default credential 85 file information 87 map credentials 86 map resources 86 overview 85 unauthenticated identity 85 LTPA, adding user attributes 83 namespace mappings XPath bindings 82 object pages Authenticate 62 AAA Policy (continued) object pages (continued) Authorize 71 Identity 60 LTPA Attributes 81 Main 57 Map Credentials 68 Map Resource 70 Namespace Mapping 80 Post Processing 77 Resource 69 SAML Attributes 81 Transaction Priority 82 SAML attributes defining 82 z/os NSS Client 144 AAAInfo.xsd file 83 accepted configuration deployment policy 54 Add button list of referenced object 3 admin account exporting configuration data 43 Administration menu 1 administrative states, objects 6 AP-REQ message, Kerberos 92 appliance configuration backing up 43, 44 comparing 52 configuration checkpoints 48 copying files 47 objects 47 exporting 43 select objects and files 45 importing configuration 50 managing configuration changes 52 moving files 47 objects 47 reading change report 53 reverting changes 53 undoing changes 53 appliance-wide log location 33 application domains backing up configuration 44 Application Security Policy configuring 30 object pages Error Maps 31, 99 General 30 Main 97 Request Maps 30, 98 Response Maps 31, 98 Apply button 4 asynchronous transaction variables service/transaction-timeout 152 asynchronous transactions variables listing 152 service/transaction-key 152 asynchronous transactions variables (continued) service/transaction-name 152 asynchronous variables service/soap-oneway-mep 152 audit log location 33 viewing 33 audit: directory 33 Authenticate element, AAA Info File 84 authentication LDAP 100 search parameters 100 Authorize element, AAA Info File 85 auto-config.cfg file 4 B backend-timeout variable 149 bold typeface ix builder deployment policy 55 buttons... 2 + 2 Apply 4 Cancel 4 Delete 5 Edit 3 Logout 1 Save Config 1, 4 Undo 5 View 3 C CA Unicenter Manager 142 caches flushing document cache 143 stylesheet cache 143 Cancel button 4 cert: directory 33 certificate files location 33 Certificate objects export packages 43 certificates DER 9 exporting 11 generating 10 importing 12 PEM 9 PKCS #12 9 PKCS #8 9 security location, shared 34 location, Web browsers 34 supported formats 9 uploading 37 Copyright IBM Corp. 2002, 2009 165

checkpoint configuration files location 33 chkpoints: directory 33 clear pdp cache CLI 97 clear xsl cache CLI 97 Clone link 6 commands clear pdp cache 97 clear xsl cache 97 web-mgmt 1 config: directory 33 configuration managing appliance configuration 41 configuration checkpoints defining number to allow 48 deleting 50 listing 49 loading 50 overwriting 49 rolling back 50 saving 49 configuration data applying 4 backing up WebGUI 43, 44 backing up application domains 44 comparing WebGUI 52 configuration checkpoints 48 copying files 47 objects 47 different release level 43 exchanging 43 exporting location of files 33 select objects and files 45 WebGUI 43 files not included 43 importing WebGUI 43, 50 managing changes 52 moving files 47 objects 47 objects not included 43 reading change report 53 reading changes 53 saving 4 undoing changes 53 configuration files exported, location 33 location 33 TAM ASCII 88 creating 89 modifying 89 obfuscated 88 configuration service variables listing 149 service/config-param/ 149 service/max-call-depth 149 configuration states, objects 6 Control Panel File Management 35 count monitors configuring 99 credentials identification configuring 15 creating 15 credentials mapping LDAP 100 search parameters 100 Crypto Certificate configuring 13 creating 13 object pages 13 Crypto Firewall Credentials object pages 14 Crypto Identification Credentials object pages 15 Crypto Key configuring 16 creating 16 object pages 16 Crypto Profile configuring 17 creating 17 object pages 17 Crypto Shared Secret Key configuring 18 creating 18 object pages 18 Crypto Tools exporting certificates 11 exporting keys 11 generating certificates 10 generating keys 10 importing certificates 12 importing keys 12 Crypto Validation Credentials object pages 21 customer support contacting 162 obtaining fixes 161 searching knowledge bases 161 D dashboard 1 default log location 33 Delete button 5 list of referenced object 3 deployment policy accepted configuration 54 creating 54 filtered configuration 54 modified configuration 54 using the builder 55 Deployment Policy object pages 54 deployment policy builder creating matching statements 55 DER certificate format 9 key format 9 directories audit: 33 available 33 cert: 33 chkpoints: 33 config: 33 directories (continued) displaying contents 35 dpcert: 33 export: 33 hiding contents 35 image: 33 local: 33 logstore: 33 logtemp: 33 managing 33 pubcert: 34 refreshing contents 36 sharedcert: 34 store: 34 tasktemplates: 35 temporary: 35 disabled administrative state 6 documentation conventions, typefaces Domain list 1 down operation state 6 dpcert: directory 33 E Edit button 3 enabled administrative state 6 error handling variables listing 153 service/error-code 153 service/error-ignore 153 service/error-message 153 service/error-protocol-reasonphrase 153 service/error-protocol-response 153 service/error-subcode 153 service/strict-error-mode 154 Error Policy object pages 99 Export link 5 export packages admin account 43 files not included 43 objects not included 43 permission 43 export: directory 33 Extensible Access Control Markup Language See XACML PDP extension functions node-set() 142 extension variables listing 156 local/_extension/allowcompression 157 local/_extension/donot-followredirect 157 local/_extension/header/ 157 local/_extension/http-10-only 157 local/_extension/prevent-persistentconnection 157 local/_extension/sslprofile 157 local/_extension/timeout 157 ix 166 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

F file entry, [configuration-database] stanza 89 File Management utility, launching 35 file system See directories files.java.policy 37 AAAInfo.xsd 83 auto-config.cfg 4 certificates location 33 checkpoint configurations location 33 configurations location 33 copying 38 remote URL 38 deleting 40 editing during configuration 4 File Management utility 40 exported, location 33 fetching 38 healthcheck.xml 106 healthcheck.xsl 106 managing 33 moving 39 not in export packages firmware files 43 log files 43 private keys location 33 renaming 39 TAM ASCII configuration 88 creating configuration 89 modifying configuration 89 obfuscated configuration 88 SSL key 88 SSL stash 88 uploading JKS 37 remote 38 workstation 36 viewing during configuration 4 File Management utility 40 filtered configuration deployment policy 54 Firewall Credentials configuring 14 creating 14 firmware files between release levels 43 export packages 43 firmware images location 33 fixes, obtaining 161 flash drive See directories G general variables listing 148 general variables (continued) service/soap-fault-response 148 H health check filter 106 SOAP request 106 healthcheck.xml file 106 healthcheck.xsl file 106 I IBM Tivoli Access Manager See TAM IBM Tivoli Federated Identity Manager See TFIM Identification Credentials configuring 15 creating 15 image: directory 33 Import Package creating 42 Include Configuration File creating 41 object pages 41 installation images See firmware images intellectual property 163 italics typeface ix J J2RE (j2re1.4.2) 37 j2re1.4.2 (J2RE) 37 j2sdk1.4.2 (SDK) 37 Java Crypto Extension See SunJCE Java Crypto Extension Key Store See JCEKS Java Key Store See JKS java.security package 37 JCE See SunJCE JCEKS 37 JKS crypto extension 37 granting permissions 37 java.security package 37 keytool utility 37 managing 37 required software 37 uploading certificates 37 working with 37 K KDC, Kerberos 92 Kerberos AP-REQ message 92 configuring KDC server 94 KDC 92 keytab 92 principal 92 Kerberos KDC server configuring 94 creating 94 object pages 94 Kerberos keytab configuring 94 definition 92 Kerberos Keytab File object pages 94 Key Distribution Center See KDC Key objects export packages 43 key-certificate pairs creating 9 keys DER 9 exporting 11 generating 10 importing 12 PEM 9 PKCS #12 9 PKCS #7 9 supported formats 9 knowledge bases searching 161 L LDAP authentication search parameters 100 credentials mapping search parameters 100 search parameters 100 licensing sending inquiries 163 links Clone 6 Export 5 Show Probe 7 View Logs 5 View Status 6 load balancer group creating 101 server state 101 Load Balancer Group adding members 104 assigning weight 104 configuring, basic 103 health convalescent (down) 102 healthy (up) 102 quarantined (softdown) 102 health checks enabling 105 overriding port 104 health of members 101 object pages Health 105 Main 103 Members 104 service/lbhealth/ variable 102 load balancer service variables listing 150 service/lbhealth/ 150 local: directory 33 Index 167

local/_extension/allow-compression variable 157 local/_extension/donot-follow-redirect variable 157 local/_extension/header/ variable 157 local/_extension/http-10-only variable 157 local/_extension/prevent-persistentconnection variable 157 local/_extension/sslprofile variable 157 local/_extension/timeout variable 157 log files export packages 43 log/soapversion variable 151 Logout button 1 logs appliance-wide location 33 audit location 33 viewing 33 default location 33 viewing from catalog 5 viewing from configuration screen 5 viewing object-specific logs 5 logstore: directory 33 logtemp: directory 33 LTPA adding user attributes, AAA Policy 83 M MapCredentials element, AAA Info File 84 MapResource element, AAA Info File 84 Matching Rule object pages 106 matching statements deployment policy builder 55 deployment policy, manual 56 message catalogs 34 message monitors count monitors 99 modified configuration deployment policy 54 Modified configuration state 6 monitors count monitors configuring 99 message monitors count monitors 99 monospaced typeface ix MQ Host variables listing 150 service/correlation-identifier 151 service/expiry 151 service/format 151 service/message-identifier 151 service/message-type 151 service/mq-ccsi 150 service/mqmd-reply-to-q 150 service/mqmd-reply-to-qm 150 service/persistence 151 service/priority 151 service/reply-to-q 151 MQ Host variables (continued) service/reply-to-qm 151 service/report 151 MQ Proxy variables listing 150 service/correlation-identifier 151 service/expiry 151 service/format 151 service/message-identifier 151 service/message-type 151 service/mq-ccsi 150 service/mqmd-reply-to-q 150 service/mqmd-reply-to-qm 150 service/persistence 151 service/priority 151 service/reply-to-q 151 service/reply-to-qm 151 service/report 151 Multi-Protocol Gateway service variables backend-timeout 149 service/reply-to-q 149 service/reply-to-qm 149 skip-backside 149 multistep variables log/soapversion 151 N Name-Value Profile object pages Main 108 Validation List 110 namespace mappings, AAA Policy 82 navigation Administration menu 1 Network menu 1 Objects menu 1 Services menu 1 Status menu 1 Network menu 1 New configuration state 6 node-set() extension function 142 notices 163 O object pages AAA Policy Authenticate 62 Authorize 71 Identity 60 LTPA Attributes 81 Main 57 Map Credentials 68 Map Resource 70 Namespace Mapping 80 Post Processing 77 Resource 69 SAML Attributes 81 Transaction Priority 82 Application Security Policy Error Maps 31, 99 General 30 Main 97 Request Maps 30, 98 object pages (continued) Application Security Policy (continued) Response Maps 31, 98 Crypto Certificate 13 Crypto Firewall Credentials 14 Crypto Identification Credentials 15 Crypto Key 16 Crypto Profile 17 Crypto Shared Secret Key 18 Crypto Validation Credentials 21 Deployment Policy 54 Error Policy 99 Include Configuration File 41 Kerberos KDC server 94 Kerberos Keytab File 94 Load Balancer Group Health 105 Main 103 Members 104 Matching Rule 106 Name-Value Profile Main 108 Validation List 110 Processing Rule 111 Rate Limiter 112 Session Management Policy 113 SSL Proxy Profile 19 TAM 89 TFIM 90 URL Rewrite Policy Main 114 URL Rewrite Rule 114 User Agent Allow-Compression Policy 121 Basic-Auth Policy 119 Chunked Uploads Policy 123 FTP Client Policies 124 Inject Header Policy 122 Main 117 Proxy Policy 118 Pubkey-Auth Policy 120 Restrict to HTTP 1.0 Policy 122 Soap-Action Policy 120 SSL Proxy Profile 118 Web Application Firewall General 27 HTTP Options 130 Main 127 Proxy Settings 129 Source Addresses 131 Timeout/Protocol 29 Web Request Profile Cookies 136 Main 132 Methods & Versions 134 Multipart Form 137 Name Value 135 Processing 134 Profile 133 Threat Protection 138 Web Response Profile Codes & Versions 140 Main 139 Name Value 141 Processing 140 Profile 140 Threat Protection 142 168 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

object pages (continued) XACML PDP 95 XML Manager 142 objects administrative state 6 configuration state 6 not in export packages Certificate 43 Key 43 User 43 operational state 6 referenced... button 2 + button 2 creating 2 modifying 2 selecting 2 status 6 TFIM 90 Objects menu 1 operational states, objects 6 P patents 163 PEM certificate format 9 key format 9 persistent connections variables listing 154 service/connection/note 155 PKCS #12 certificate format 9 key format 9 PKCS #7 certificate format 9 PKCS #8 key format 9 Policy Decision Point See XACML PDP principal, Kerberos 92 private key files location 33 private keys uploading 37 Processing Rule object pages 111 pubcert: directory 34 R Rate Limiter object pages 112 referenced objects... button 2 + button 2 creating 2 modifying 2 selecting 2 referenced objects, lists... button 3 + button 3 Add button 3 adding 3 creating 3 Delete button 3 referenced objects, lists (continued) deleting 3 modifying 3 selecting 3 replica entry, [manager] stanza 89 S SAML attributes defining, AAA Policy 82 Save Config button 1, 4 Saved configuration state 6 scenarios Web Application Firewall benefits management site 26 college enrollment form 25 trading site 26 schemas location 34 SDK (j2sdk1.4.2) 37 search parameters, LDAP 100 security certificates shared location 34 Web browsers location 34 server pool See load balancer group server state load balancer group 101 service variables listing 148 types 148 service/append-request-header/ variable 154 service/append-response-header/ variable 154 service/config-param/ variable 149 service/connection/note variable 155 service/correlation-identifier variable 151 service/error-code variable 153 service/error-ignore variable 153 service/error-message variable 153 service/error-protocol-reason-phrase variable 153 service/error-protocol-response variable 153 service/error-subcode variable 153 service/expiry variable 151 service/format variable 151 service/lbhealth/ variable 102, 150 service/max-call-depth variable 149 service/message-identifier variable 151 service/message-type variable 151 service/mq-ccsi variable 150 service/mqmd-reply-to-q variable 150 service/mqmd-reply-to-qm variable 150 service/persistence variable 151 service/priority variable 151 service/reply-to-q variable 149, 151 service/reply-to-qm variable 149, 151 service/report variable 151 service/routing-url variable 155 service/routing-url-sslprofile variable 155 service/set-request-header/ variable 154 service/set-response-header/ variable 154 service/soap-fault-response variable 148 service/soap-oneway-mep variable 152 service/strict-error-mode variable 154 service/transaction-key variable 152 service/transaction-name variable 152 service/transaction-timeout variable 152 service/uri variable 156 service/wsa/genpattern variable 156 service/wsa/timeout variable 156 service/wsm/wsdl-error variable 156 service/wsm/wsdl-warning variable 156 Services menu 1 Session Management Policy object pages 113 sharedcert: directory 34 Show Probe link 7 skip-backside variable 149 SOAP request healthcheck.xml 106 SSL client proxy, creating 19 forward proxy, creating 19 reverse, proxy, creating 19 server proxy, creating 19 two-way proxy, creating 20 SSL authentication 17 SSL Proxy Profile creating client proxy 19 forward proxy 19 reverse proxy 19 server proxy 19 two-way proxy 20 object pages 19 ssl-keyfile-pwd entry, [ldap] stanza 89 Status menu 1 store: directory 34 style sheets flushing the cache 143 healthcheck.xsl 106 location 34 subdirectories creating 35 deleting 36 SunJCE JCEKS 37 support See customer support system variables listing 158 system/map/debug 158 system/tasktemplates/debug 158 system/map/debug variable 158 system/tasktemplates/debug variable 158 T TAM ASCII configuration file 88 authorization server replicas 89 configuration, general 88 configuring TAM objects 89 creating configuration files 89 Index 169

TAM (continued) creating TAM objects 89 licensing 88 modifying configuration files 89 obfuscated configuration file 88 object pages 89 refreshing certificates 90 security 88 SSL key file 88 SSL stash file 88 tasktemplates: directory 35 temporary: directory 35 TFIM AAA 90 object 90 object pages 90 TFIM endpoint WS-Trust messages 90 Tivoli Access Manager See TAM trademarks 163 transaction headers variables listing 154 service/append-request-header/ 154 service/append-response-header/ 154 service/set-request-header/ 154 service/set-response-header/ 154 transaction routing variables listing 155 service/routing-url 155 service/routing-url-sslprofile 155 transaction URL variables listing 155 service/uri 156 transaction variables listing 152 types 152 typeface conventions ix U Undo button 5 up operational state 6 URL Rewrite Policy object pages Main 114 URL Rewrite Rule 114 User Agent object pages Allow-Compression Policy 121 Basic-Auth Policy 119 Chunked Uploads Policy 123 FTP Client Policies 124 Inject Header Policy 122 Main 117 Proxy Policy 118 Pubkey-Auth Policy 120 Restrict to HTTP 1.0 Policy 122 Soap-Action Policy 120 SSL Proxy Profile 118 User objects export packages 43 utilities keytool 37 V Validation Credentials creating non expiring, non-passwordprotected certificates 21 select certificates 21 types of lists 21 variables asynchronous service/soap-oneway-mep 152 asynchronous transactions listing 152 service/transaction-key 152 service/transaction-name 152 service/transaction-timeout 152 configuration service listing 149 service/config-param/ 149 service/max-call-depth 149 error handling listing 153 service/error-code 153 service/error-ignore 153 service/error-message 153 service/error-protocol-reasonphrase 153 service/error-protocolresponse 153 service/error-subcode 153 service/strict-error-mode 154 extension listing 156 local/_extension/allowcompression 157 local/_extension/donot-followredirect 157 local/_extension/header/ 157 local/_extension/http-10-only 157 local/_extension/preventpersistent-connection 157 local/_extension/sslprofile 157 local/_extension/timeout 157 general listing 148 service/soap-fault-response 148 list, all available 159 load balancer service listing 150 service/lbhealth/ 102, 150 MQ Host listing 150 service/correlation-identifier 151 service/expiry 151 service/format 151 service/message-identifier 151 service/message-type 151 service/mq-ccsi 150 service/mqmd-reply-to-q 150 service/mqmd-reply-to-qm 150 service/persistence 151 service/priority 151 service/reply-to-q 151 service/reply-to-qm 151 service/report 151 MQ Proxy listing 150 service/correlation-identifier 151 variables (continued) MQ Proxy (continued) service/expiry 151 service/format 151 service/message-identifier 151 service/message-type 151 service/mq-ccsi 150 service/mqmd-reply-to-q 150 service/mqmd-reply-to-qm 150 service/persistence 151 service/priority 151 service/reply-to-q 151 service/reply-to-qm 151 service/report 151 Multi-Protocol Gateway backend-timeout 149 service/reply-to-q 149 service/reply-to-qm 149 skip-backside 149 multistep log/soapversion 151 persistent connections listing 154 service/connection/note 155 service listing 148 type 148 system listing 158 system/map/debug 158 system/tasktemplates/debug 158 transaction listing 152 type 152 transaction headers listing 154 service/append-request-header/ 154 service/append-response-header/ 154 service/set-request-header/ 154 service/set-response-header/ 154 transaction routing listing 155 service/routing-url 155 service/routing-url-sslprofile 155 transaction URL listing 155 service/uri 156 types 147 using 147 Web Service Proxy backend-timeout 149 service/reply-to-q 149 service/reply-to-qm 149 skip-backside 149 WSM listing 156 service/wsa/genpattern 156 service/wsa/timeout 156 service/wsm/wsdl-error 156 service/wsm/wsdl-warning 156 View button 3 View Logs link 5 View Status link 6 170 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

W Web Application Firewall configuring 27 object pages General 27 HTTP Options 130 Main 127 Proxy Settings 129 Source Addresses 131 Timeout/Protocol 29 scenarios benefits management site 26 college enrollment form 25 trading site 26 Web Management Interface 1 Web Request Profile object pages Cookies 136 Main 132 Methods & Versions 134 Multipart Form 137 Name Value 135 Processing 134 Profile 133 Threat Protection 138 Web Response Profile object pages Codes & Versions 140 Main 139 Name Value 141 Processing 140 Profile 140 Threat Protection 142 Web Service Proxy service variables backend-timeout 149 service/reply-to-q 149 service/reply-to-qm 149 skip-backside 149 web-mgmt command 1 WebGUI accessing 1 Administration menu 1 applying configuration changes 4 canceling changes 4 cloning services 6 common tasks 4 dashboard 1 deleting objects 5 Domain list 1 exporting objects 5 logging in 1 Logout button 1 Network menu 1 Objects menu 1 resetting configuration 5 reverting changes 5 Save Config button 1 saving configuration changes 4 Services menu 1 Status menu 1 viewing object status 6 viewing object-specific logs 5 viewing probe data 7 Welcome screen 1 Welcome screen 1 workstation uploading files 36 WS-Security Management See WSSM WS-Trust messages TFIM endpoint 90 WSM variables listing 156 service/wsa/genpattern 156 service/wsa/timeout 156 service/wsm/wsdl-error 156 service/wsm/wsdl-warning 156 X XACML PDP configuring 95 object pages 95 XML Manager caches flushing the document cache 143 flushing the stylesheet cache 143 configuring 142 document cache, flushing 143 modifying 142 object pages 142 XPath bindings AAA Policy 82 Z z/os NSS Client creating 145 overview 144 Index 171

172 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Printed in USA