Best Practices with DataPower

Table of Contents

Domains
Managing Files
Managing network access to the appliance
The Network Cards
Custom SSL Proxy Profile
Users, Groups and RBM
SLM
Access Policies
Major Service Object Naming Conventions
Naming Conventions with Domains
XML Management Interface (default port 5550)
SNMP Communication (Traps, MIBS, Alerts, Tivoli)
Logging
Frontside Handlers
The XML Manager (not the XML Management Interface)
Backup and Restore - Secure or Normal
Running Configuration
Managing Configuration Checkpoints
Object Status
Managing the Firmware Image
Applying a Firmware Image
Working with Java Key Stores
WAMC
 

Domains

The domains in DataPower should be considered as separate user environments, much like a user environment in Unix or Active Directory. The default domain is the only domain in DataPower that controls system-wide resources such as network interfaces, users, and control objects. For application and service configurations in DataPower, the creation of new Application domains is needed. Do not create services in the Default Domain.

For example, during the life cycle of any certain project, the creation of a new domain during each and every release is one way to be certain that corrections and differentiations can be re-examined and changed from domain to domain. It will allow one to start/stop independently of other domains and it becomes easy to manage user access control.

Application objects/services can also be secured by creating appropriate users and groups. Note that there is no limit on the number of application domains that can be created and it is possible to share DataPower artifacts (not by default) between application domains. This is done by making them ‘visible.’

By sharing files through copying them, such as an XSLT file, or simply viewing them by example, the objects can act as building blocks for other users new to the device. Exporting certain objects can also be very useful for Developers wanting to learn from those objects through importing them into their own domain or environment. All of these actions need to happen inApplication Domains and not the Default Domain.

Naming Conventions

The use of consistent and standard naming conventions when creating new domains is necessary to keep the information created and handled categorized in a concise manner as the projects move forward. This will help developers and administrators easily identify the domains they need to work with in accordance to which services are being run where. Proper naming conventions also simplify the process of debugging services with the use of syslog and other external monitors used.

Reusing DataPower objects: All sharable objects with no application/service specific information such as style sheets and certificates can be reused in other domains by sharing the file system between domains. The sharable objects can be grouped in to a specific domain and by making that domain visible to others will avoid duplicate copies of objects in multiple locations.

Separating Data and Services
DataPower Web services proxies are defined within application domains, and DataPower users can be restricted to access some or all domains. When configuring the DataPower data collector, you must understand how the domains and users are defined on the monitored DataPower SOA appliances, to ensure that the data collector uses valid authentication credentials. This refers to user IDs and passwords that have access to the DataPower domains containing the Web services proxies to be monitored. In addition, you must decide how you want to aggregate or separate the data collected from those domains for display in the Tivoli Enterprise Portal.

You can use DataPower SOA appliances in several typical configurations:

• Single appliance, single domain: The data collector monitors a single DataPower SOA appliance, with all of the monitored resources defined in a single domain on the appliance.
• Single appliance, multiple domains: The data collector monitors a single DataPower SOA appliance, but that appliance has monitored resources that are defined in more than one domain on the appliance.
• Multiple appliances with different configurations: The data collector monitors multiple DataPower SOA appliances, and each appliance has a different configuration of resources to be monitored. Each appliance is configured for a particular job, with no intention of load-balancing or fail-over between appliances.
• Multiple appliances with identical configurations: The data collector monitors multiple DataPower SOA appliances, and all of the appliances have an identical configuration of resources being monitored. All of the appliances are configured for the same job, taking advantage of load-balancing and fail-over capabilities between appliances.

Aggregation

Domains can be used to aggregate data in different ways when using Tivoli, by using DataPower as a data collector. This is done by isolating data to a specific domain. Names can be assigned to groups of data, referred to as display groups. Using these groups, data can be displayed using the Tivoli system in place. By default, the DataPower data collector aggregates data for all of the monitored domains on a single DataPower SOA appliance (even if the domains are accessed using different credentials), and keeps the data from each DataPower SOA appliance separated.

Given these typical configurations, the DataPower data collector provides a great deal of flexibility in defining how the collected monitoring data should be separated or aggregated, across a single appliance or multiple appliances, for display in the Tivoli Enterprise Portal. The following examples illustrate how data can be separated or aggregated for managing the data from various domains and appliances:

• Separation of data at the domain: You can view the services management data for the resources in a single domain, separate from the data for resources in other domains.
• Aggregation of data across domains: You can view the services management data for the resources in several domains (for example, all of the domains on a given DataPower SOA appliance) in an aggregated form, with no regard for the domain in which individual resources are defined.
• Separation of data at the appliance: You can view the services management data for resources on a single DataPower SOA appliance, separate from the data for resources on other appliances.
• Aggregation of data across appliances: You can view the services management data for the resources on several DataPower SOA appliances (for example, all of the appliances in a load-balancing cluster) in an aggregated form, with no regard for what activity occurs on each individual appliance.

Managing Files

Directories on the Appliance

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:
This directory contains the configuration files for the appliance. Each application domain contains one config: directory. This directory is not shared across domains. The configuration file can be manipulated to a point with startup procedures.

dpcert:
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.

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 the 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 onestore: 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.

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 defaultdomain only.

temporary:
This directory is used as temporary disk space by processing rules. Each application domain contains one

 

Managing Network Access to the Appliance

SSH access
Use this page to enable or disable SSH service. Select Network → Management → SSH Service to display the SSH Service Configuration (Main) screen.

Provide the following inputs:

Admin State
Retain the default setting. To place the object in an inactive administrative state, click disabled.

Local IP Address
Optionally bind SSH to a specific active (provisioned) appliance interface. Without an explicit address assignment, SSH, once enabled, first attempts to bind to the appliance management port. If the management port has not been previously configured, SSH binds to all configured appliance interfaces. You can use a host alias instead of a local IP address. Click Select Alias to choose a local host alias.

Port Number
Optionally bind SSH to a specific port. Without an explicit port assignment, SSH, once enabled, binds to port 22, the well-known SSH port.

Access Control List
Assign an Access Control List to the SSH service. 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.

WebGUI access
Access to the appliance via the WebGUI is supported by a dedicated HTTP server that you configured during the initial appliance configuration process. After creating the dedicated server, you can use the WebGUI to modify server properties. Select Network → Management → Web Management Service to display the Web Management Service configuration (Main) screen.

Provide the following inputs:

Admin State
Retain the default setting. To place the object in an inactive administrative state, click disabled.

Local IP Address
Identify the local IP address of the appliance that is monitored for incoming WebGUI requests. If you want the Web Management Service to monitor all active interfaces, retain the default value (0.0.0.0). You can use a host alias instead of a local IP address. Click Select Alias to choose a local host alias

Port Number
Specify the specific UDP port (in the range 1 through 65535) monitored by the Web Management.

Access Control List
Optional, select the ACL to use when making a connection to the WebGUI.

Custom User Agent
Optional, select the User Agent to use when making a connection to the WebGUI.

Save Config Overwrite
Specify the desired behavior after a running configuration is saved as the startup configuration. The startup configuration is saved by clicking the Save Config button. By default, the startup configuration is saved to the autoconfig.cfg file in the config: directory. To override the default behavior, click the no radio button.

Idle Timeout
Specify the idle timeout value. That is, specify the period of inactivity after which the Web Management Service shuts down the WebGUI connection. Allowable values are in the range 0 through 65535, with a default value of 600 (seconds). The special value 0 disables the idle timeout.

To change default security settings and HTTP connections settings, click the Advanced tab to display the Web Management Service configuration (Advanced) screen.

Custom SSL Proxy Profile

To employ an SSL Proxy Profile other than the default for connection to the Web Management interface, select an SSL profile.

By default, the DataPower appliance uses a self-signed certificate during the SSL handshake. This field (possibly used with the Generate Certificate tool) offers an opportunity to employ different certificates and keys in support of the SSL connection to the Web Management interface.

You can access the Generate Certificate tool, which creates an SSL Proxy Profile based on newly generated self-signed certificate and an associated private key, by clicking Generate Certificate on the Advanced screen.

After clicking Generate Certificate, a confirmation window is displayed. Click Confirm to create an SSL Proxy Profile, suitable for Web Management Service usage, named appliance-id.

If desired, you can use the File Management utility to verify that the following files were created:

cert:///appliance-id-privkey.pem
A protected .pem-formatted file that contains the generated private key

cert:///appliance-id-sscert.pem
A protected .pem-formatted file that contains the generated self-signed certificate

Custom User Agent
Select an User Agent to associate with the WebGUI. 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.

Users, Groups and RBM

Local groups are assigned specific access rights called access policies. Access policies identify resources and permissions that users in the group can perform on these resources.

Access policies can be restricted by IP address, by application domain, by resource type, or by a combination of these resource identifiers. Resource identification can be as broad as all objects of a specific object type or as specific as only objects of a specific name.

The DataPower appliance manages access through role-based management (RBM).

RBM provides a flexible and integrated means to control whether an authenticated user has the necessary privileges to access resources through access policies. Settings on the DataPower RBM policy provide the facility to define a global password policy for locally-defined users.

Understanding RBM on the DataPower appliance

RBM controls the relationships between authenticated users and resources. The user logs in to the DataPower appliance. The user is authenticated either by a remote authentication system or by the DataPower appliance. The RBM policy determines whether to allow an authenticated user to access specific resources.

When authentication uses a remote authentication system, such as an LDAP server, RBM extracts the identity of the authenticated user, maps the identity to a credential, and determines whether to authorize access to the resource based on the credential. If a problem occurs during remote authentication, RBM can use one or more locally-defined fallback users.

When authentication is local, authentication is by user name and password. The group in which the user is a member determines whether to authorize access to the resource. Users who are not members of a group are not under RBM control.

The RBM policy uses access profiles to determine authorization to resources. An access profile is made up of one or more access policies. Each access policy defines which privileges to provide to a single resource. An access policy can use wildcard characters in regular expressions to define the same set of privileges to multiple resources.

Because RBM distances access policies from individual users, you can modify an access profile that affects a collection of users instead of modifying each user individually. For example, you can modify the access profile in a user group to change resource authorization for all members of that group. Alternatively, you can change the access profile associated with a credential to modify all users who map to that credential.

The appliance provides a variety of user group accounts, but these are not visible until you have defined at least one user on the appliance. The following types of user group accounts are available:

User Group accounts that are not domain-limited

These groups always belong to the Default Domain, and the appliance automatically assigns access rights to each group. These user groups include:

• A system administrator group that is named sysadmin
• A network administrator group that is named netadmin
• An access management group that is named access
• An account management group that is named account

User Group Accounts that are Domain-limited

Although these groups are normally limited to an Application Domain, these groups can be part of the Default Domain if they are re-configured. The appliance automatically assigns access rights to each group, except the User-Defined Group, otherwise known as the Fine-Grained Group. These user groups include:

• A developer group that is named developer
• A backup user group that is named backup
• A guest group that is named guest and provided with read-only access
• A user-defined group that is named by the individual creating it and whose access policy must be defined at the time of creation. This group is otherwise known as a Fine-Grained Group

The groups and users should be limited on DataPower devices and match up per device if possible for consistency. There will be several groups utilized for permission splits, and in this case, these Users/Groups will be local to the devices, meaning, Role Based Management will not be used to Authenticate and Replicate User/Group settings contained within an Active Directory or LDAP environment. It is recommended that the User/Group assignments remain local to each device. The following Groups will be focused on within this specific environment:

a) Admin

b) Operations (includes networking)

c) Group-Defined (more specific)

1. Group set aside for particular Admin roles but not all of them

2. Group set aside for Certificate/Key Management roles

d) Developer

e) Business-User (Also Group-Defined)

Only 1-2 Administrators should be designated per DataPower device. The Admin Group should never be more than 2 Users. The Admin User, along with the Operations User, are responsible for network assignments and all roles present on all DataPower devices in regard to any changes or additions made. Although it is possible to have a Network Group assigned, and one exists on the device by default, these tasks are often accomplished by the Operations Group. In this environment the same holds true.

Keeping track and managing all the tasks present on various DataPower devices’ can grow into quite an assortment of duties, all of which are important. This is a huge and critical responsibility which involves the following:

o Backups

o Imports/Exports

o Enabling/Disabling Services

o Deletion of Objects

o Certificate/Key Management

o File Structure Layout of Folders

o Restarting/Shutdown of Domains and Devices

o Networking

o Firmware Management

o Memory Allocation Choices

o User and Group Management

o Cache Allocation Choices

o SNMP Monitoring Options and Connectivity with External Tools

o Port Designation per NIC(s) used

o Naming Conventions

o Logging Methods and Rules

o All Inbound/Outbound traffic per 3 NIC’s per device

The ability to define groups in a fine-grained fashion allows certain limitations and freedoms to be granted per User, per Group, per Domain. The Developer Group will have full control to changes and additions made to policies present minus any network and/or user/group changes. These changes will be left up to the administrator(s) of the device.

For example, the Developer Group will have the capacity to create service objects like an XML-Firewall but will be limited to certain domains which have been set up by the Admin of the device. The Admin controls which domains will be visible to other domains, in turn allowing certain service objects to be visible to some users’ while keeping other service objects to either not be visible or only be visible read-only.

In another example, perhaps the Admin requires that one group have write access to some domains while also having various Admin rights as well. In this case a Fine-Grained Group is the answer, as it allows the Admin to assign more specific rights to that newly created group.

Although it is recommended to create and use Group-Defined Groups when needed, it is not recommended to have too many of them, or have them hastily created. A Group-Defined Groupthat has been assigned too many write permissions according to an accidental User assignment to that group can cause problems internally and externally.

SLM

Statement
A Statement establishes criteria for selecting messages, sets a measurement interval, sets thresholds and determines the action to take when the threshold is met for the selected messages.

If no Credential Class is provided, this value is not used to select messages. By default, all messages are selected.

If no Resource Class is provided, this value is not used to select messages. By default, all messages are selected.

A Policy may have many statements. Statements execute in order according to the value of the Identifier field.

Identifier
Each statement is uniquely identified by a positive integer. The statements are executed in their indexed order. Adding a statement with an identifier that duplicates a previous entry replaces the previous entry.

User Annotation
Use this property to configure a custom string or identifier that will appear in logging messages for this statement.

Credential Class
Reference the credential class used to determine the credential(s) this statement executes against. If a credential class is not configured, the statement executes against all messages that are identified as valid resources without respect to credential classification. Leaving this blank effectively considers all messages as belonging to a single global user.

Resource Class
Reference the resource class used to determine the resource(s) this statement executes against. If a resource class is not configured, the statement applies to all messages that pass the credential classification.

Schedule
Reference the schedule that describes the applicable time frames for this policy statement.

SLM Action
Reference the SLM Action to be executed if this statement's threshold is exceeded.

Threshold Interval Length
Specify the length of each measurement interval in seconds.

Threshold Interval Type
A fixed interval is a discrete block of time, from 8:00 am to 9:00 am, for example. A moving interval is a sliding-window, the last 60 minutes, for example. Fixed intervals are calculated from the start of the schedule. If no schedule is assigned, fixed intervals are calculated starting from 12:00 am.

Threshold Algorithm
Specifies how the threshold should be executed within the current interval. Greater-than and less-than are the simple relational operations. Token-bucket is based on a rate and allows bursting. High-low-thresholds trigger at the high threshold and continue to trigger until the low threshold is achieved.

Threshold Type
By default, the threshold level is applied to the count of resources identified by the resource type. To threshold based only on error count, set the threshold type to error.

Threshold Level
Threshold level is the count or value to allow before triggering the threshold and executing the associated action.

High - Low Algorithm Release Level
The high-low-thresholds algorithm allows the user to specify when to start thresholding and when to stop in cases where those two values are not the same. The threshold level is the start point. This property configures the stop point.

Burst Limit
Specify the maximum allowed message burst. Use a value approximately twice the value of threshold level. This property is only applicable to the token-bucket algorithm. The default value of zero enforces no burst limit.

Reporting Aggregation Level
Specifies the base aggregation level in minutes for reporting of statistics. It is the statistic interval. This value does not affect the thresholding intervals.

Maximum Records Across Intervals
A single reporting aggregation interval may contain multiple records, one record per resource or credential, for example. The total records to be saved across the maximum saved intervals is configurable via this parameter. This allows a maximum memory-consumption threshold to be set.

Auto Generated by GUI
When true, this statement was auto-generated as part of a default SLM configuration. This property is read-only and can not be toggled by the user.

Maximum number of credentials-resource combinations to apply threshold
Threshold is defined for the combination of credentials and resource. This property limits the maximum number of such combination. This allows a maximum memory-consumption threshold to be set.

Access Policies

Below are definitions consisting of Access Policies, which as stated, make up the Group and User definitions. The Access Policy Builder is a powerful tool that can be utilized to formulate these Access Policies.

Elements of an Access Policy
When building an access policy statement on the Editing Access Profile Property screen, screen elements appear based on each value selected or added. The full list of elements used for building access policies includes the following terms and definitions:

Device Address
Identifies the local management IP address of the appliance to which the policy is applied. Leave blank for all.

Application Domain
Identifies the Application Domain to which the policy is applied. Select (none) for all or if not applicable to resource type. Accepts regular expressions.

Resource Type
Identifies the type of the resource to which the policy is applied. Select (any) for all resource types.

Name Match
Limits the access policy to resources with the specified names. Use a PCRE to select groups of resource instances.

Local Address Match
Limits the access policy to the specified local addresses. A PCRE expression can be used to select a range of addresses.

Local Port Match
Limits the access policy to the specified local ports. Use a PCRE expression to select a range of ports.

Directory Match
Limits the access policy to the specified directories. Applies only to the file resource type and the file management type. Use a PCRE to select sets of directories.

Filename Match
Limits the access policy to the specified local files. Use a PCRE to select a set of files.

Permissions
Defines the access rights for the resources that match this policy. Options are Read, Write, Add, Delete, and Execute.

Examples of Access Policies

The following example Access Policies include the Access Profile and a description of assigned rights:

*/*/*?Access=r+w+a+d+x
All users who are members of this group have read, write, add, delete, and execute rights to every area of the appliance.

*/*/access/change-password?Access=x
All users who are members of this group have execute rights to change passwords on every domain of the appliance.

*/*/access/radius?Access=r
All users who are members of this group have read rights to Radius Settings on every domain of the appliance.

Major Service Object Naming Conventions
(Regardless of the name of the export file, the object upon import will be named what it was named prior before export. There is no way to change this.)

The Major Service Objects are as follows:

• XML-Firewall (i.e. – XMLFW)
• WS-Proxy (i.e. – WSP)
• Web Application Firewall (i.e. – WAFW)
• Multi-Protocol Gateway (i.e. – MPGW)
• XSL Co-Processor (i.e. – XSLCP)

The Naming Scheme is made up of three nodes separated by underscores:

Project à The name or area requesting the object

Purpose à Gives a high level indication of what the object is for

Object à Abbreviation identifies the category of the object

The filenames of all Major Service Objects in the category of XML-Firewall, WS-Proxy, Web Application Firewall, Multi-Protocol Gateway and XSL Co-Processor should follow the format below. We are calling these Major Service Objects, since they are high-level objects that contain numerous other Minor Service Objects under their hierarchy. Examples of Major Service Objects are below:

[ Project_Purpose_Object-Abbreviation ]

Some examples of this format are:

• CareEstimator_Thomson_XMLFW
• Situs_Sircon_XMLFW
• PriceQuote_Argus_WAFW
• Eas_Srvc-Mntr_XMLFW
• Ecm_Viewer_MPGW
• Ecm_Viewer_XMLFW
• Eas_UserProfile_WSP
• Ecm_FileNet-P8_WSP
• Situs_Sircon_XSLCP

In no way are Minor Service Objects, such as Crypto Objects, AAA Objects or Frontside Handler Objects, considered less relevant to the overall conglomerate of Service Objects within DataPower. They are simply, at the time of this writing, allowed more flexibility in the naming scheme within the environment here at this location. Examples of those objects are shown in the next section entitled Minor Service Objects.

Minor Service Object Naming Conventions
(Regardless of the name of the export file, the object upon import will be named what it was named prior before export. There is no way to change this.)

[ Project_Purpose_Object-Abbreviation ]

Some examples of this format are:

• CareEstimator_Thomson_AAA
• Situs_Sircon_ValCred
• PriceQuote_Argus_IDCred
• Ecm_LogTarget
• PriceQuote_HTTP_8042
• CareEstimator_HTTPS_6822
• Eas_MQM
• Ecm_FTP

Naming Conventions with Domains

The use of consistent and standard naming conventions when creating new domains and objects within them is necessary. This keeps the information categorized in a concise manner as the project moves forward. This also helps developers and administrators easily identify the domains and objects they need to work with in accordance to which services are being run where. Proper naming conventions also simplify the process of debugging services with the use of syslog and other external monitors used.

Note: Reusing DataPower objects: All sharable objects with no application/service specific information, such as style sheets and certificates, can be reused in other domains by sharing the file system between domains. The sharable objects can be grouped in to a specific domain, and by making that domain visible to others, will avoid duplicate copies of objects in multiple locations. This is just one method in regard to sharing objects and files on DataPower.

Examples of Domain Naming Conventions:
(Regardless of the name of the export file, the domain name upon import will remain what it is regardless of what file is being exported – the objects within the imported domain will keep their names as well)

Defining User categories themselves:

• JohnSmith_domain
• AaronChapman_domain
• JudyWilliams_domain
• SarubRamachandran_domain
• GaryLeeman_domain
• RajPatel_domain

XML Management Interface

Firstly, the XML Management Interface is not to be confused with the XML Manager, which can, like any other object in DataPower, be exported, duplicated, create or deleted. The SOMA or XML Management Interface uses port 5550 by default. This can be changed.

This interface accepts SOAP request messages sent from any client. These requests are customized according to the SOMA schema and WSDL inside DataPower, and are sent to DataPower via port 5550 to manage, create and delete all objects necessary. A common usage of the XML Management Interface is for backups and current status of the device.

Summary of the XML Management Interface’s Usage and Purpose:

o Otherwise known as SOMA or SOAP Management Interface.

o Protected with default SSL profile.

o Requires HTTP basic authentication.

o All commands available from XML Management.

o Same users and RBM rights as WebGUI.

o Used for integration/automation and monitoring.

SNMP Communication (Traps, MIBS, Alerts, Tivoli)

o configure Trap and Notification Targets on device for SNMP trap receivers.

o configure Log Target of type SNMP to emit SNMP traps to configured receiver AND/OR configure Trap Event Subscriptions to emit traps globally for specific event error codes

o drNotificationMIB.txt describes the general structure of SNMP traps thrown by DataPower. This can be imported into monitoring solutions to decipher trap structure

o All DataPower traps look exactly the same at the trap receiver. Error codes and text differentiates one notification from another

o Can be used for monitoring and alerting

o Supports v1, v2c and v3 (security).

o MIBs are distributed with firmware and downloadable from WebGUI.

o Can integrate into any SNMP compliant enterprise monitoring solution.

Logging

o Supports many types of common operations systems:

ü Syslog and Syslog-NG for real time network logging to remote file system

ü NFS mounts can be used for storing logs

ü SNMP, SMTP, and SOAP for individual event alerting

ü Cache and File System logging for high volume debugging

o Event Subscription – each log target must have some kind of event subscription to output data

o Event and Object filters are optional to parse out unwanted data from log targets

o Ability to create many log targets for many different monitoring tasks


Log Targets Allow for the following:

o Supports many types of common operations systems:

o Syslog and Syslog-NG for real time network logging to remote file system

o SNMP, SMTP, and SOAP for individual event alerting

o Cache and File System logging for high volume debugging.

o Event Subscription – each log target must have some kind of event subscription to output data

o Event and Object filters are optional to parse out unwanted data from log targets

o Ability to create many log targets for many different monitoring tasks

The XML Manager (not the XML Management Interface)

The XML Manager is extremely important. The XML Manager controls the parsing of every message that comes through DataPower. It is useful to immediately create a new XML Manager so that whatever settings have been customized does not affect the Default XML Manager. As well, it is just as important to notify all developers and administrators within DataPower which XML Manager should be utilized for messaging. In some cases, different XML Managers will be used for different vendors.

An XML Manager obtains and manages XML documents, stylesheets, and other document resources on behalf of one or more services. It also can provide the following functionality:

• Set manager-associated limits on the parsing of XML documents
• Enable and set levels for document caching
• Perform extension function mapping
• Enable XML-manager-based schema validation
• Schedule an XML-manager-initiated Processing Rule
• Contains the User Manager Objects settings
• Domain backups weekly
• FullSys backups quarterly
• Manual Domain backups sporadically upon handing off of Service Level Objects from DEV to Acceptance Domain

Procedure for Exporting and Importing new Objects from DEV to ACCEPTANCE domains:

1. Developer creates Service Objects inside his/her domain

2. Developer exports the required objects

3. Developer places exported objects in PVCS

4. Email is sent to Admin that exported objects are there

5. Admin checks exported objects for proper naming conventions of Objects discussed earlier

6. If naming is okay, Admin agrees to import the Service Objects into the Acceptance domain

7. Prior to importation of the objects, Admin takes note of the Object Status Page and preferably takes a screenshot.

8. Admin takes manual domain backup prior to importing the newly created Service Objects

9. Admin imports the Objects into the Acceptance domain

10. Admin checks the Objects Status page for any differences the import might have caused.

11. If differences have occurred, Admin immediately notifies the Developer of those differences and

12. Admin tests the newly imported objects

13. If functional the Admin backs up the Acceptance domain

Keep backups in Change Management, and on the DataPowers’ themselves in the ‘export’ folder. Every time an export is done within DataPower the device automatically creates a zipped file called ‘export.zip’ in the ‘export’ folder. As long as this folder contains only one Domain Export, a zipped backup of the very Domain one is looking at, the file size will suffice, leaving the performance unharmed.

Yes, it can be argued that the more space a flash device has the ‘faster’ it will run. It can also be argued that having one export file of an entire Domain on the device is quite reassuring and can be used in the future to not only import back into the device, but also to match creation times of the zipped file, if there is ever any confusion as to when an export was placed in Change Management.

This rule of creation dates and modification dates becomes extremely important, in that it is a zipped file, and though there is readable data within it, one usually does not have the time to take on such a task unless extremely necessary. Make sure the modification dates are the same for all devices if all devices are utilizing similar services or policies, and that the names of the ZIP files serve a proper purpose.

Below is how the automation process of backup works. The URLS have been changed from the images shown. The process is still the same. The steps shown for this process are very accurate, including the stylesheet used for the process.

Running Configuration

Check the running configuration in the default domain. The Running Configuration may reveal invalid configurations or a configuration that is not expected.

Use the Main panel of the Troubleshooting page to access this information. Typically, if the running configuration is different than the last saved configuration (which, in production, is typically the startup configuration), then something has changed. This ‘state’ is indicated on all WebGUI pages.

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 to the chkpoints: directory for that application domain.

Defining the 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.
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 and return to the object catalog.
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.

Listing Configuration Checkpoints

You can view the list of saved configuration checkpoint in one of the following ways:

• 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

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.

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:

• From the Configuration Checkpoints screen
• From the File Management screen

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.

Object Status

The Object Status display indicates the operational state of all objects in the system. It is perhaps, one of the most important screens inside the WebGui Interface because it lets one know immediately what service objects are up and down in regard to the domain that one is currently in. Furthermore, it pinpoints which objects within the hierarchy are the culprit of why certain objects are down due to dependency relations from object to object.

An object on which a service depends may go down, bringing down the service itself. To take advantage of this screen, click on the object in red and investigate whether the service has been disabled on purpose or not.

Perhaps the most powerful feature of the Object Status screen lies in the fact that it gives the Administrator or any user on the device, the ability to click on Objects, move that very Object screen and immediately make changes to that Object or its underlying Objects.

Below is an image of what the Object Status screen looks like with various Objects expanded in order to see the full Object Hierarchy of all Services and Policies inside an entire Domain. Keep in mind these Objects pertain to the Domain one is currently in, and not to other Domains on the device.

All of the Objects within the Object Status screen may be viewed by using the dropdowns which reference them (i.e. “+” or “-“) by either Services or Types.

So, as we can see, in this case, the Encrypto XML Firewall Service has been expanded completely to reveal what is actually causing the service to be ‘down.’ And in a common scenario such as this one, the problem is rooted to a Certificate Object.

Applying a Firmware Image

Use the following procedure to apply a firmware image, which might be an upgrade:

1. Select ADMINISTRATION → Main → System Control to display the System Control panel.

2. Locate the Boot Image section of the System Control panel.

3. If the desired firmware file is not on the appliance, click Upload or Fetch

4. From the Firmware File list, select the firmware file.

5. Click Boot Image to boot the appliance with the selected file.

6. Click Confirm to apply the upgrade and reboot the appliance. An additional confirmation screen is display that confirms that the firmware file was installed. The appliance can take up to 3 minutes to reboot.

Rolling Back an Upgrade

Use the following procedure to roll back to the previous firmware image:

1. Select ADMINISTRATION → Main → System Control to display the System Control panel.

2. Locate the Firmware Roll-Back section of the System Control panel.

3. Click Firmware Roll-Back.

4. Click Confirm.The appliance is rolled back to the last-installed release.

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:

Version 1.4.2 of the Java runtime environment (j2re1.4.2) v SDK (j2sdk1.4.2

Internet ExplorerNote: 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:

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.
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.
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. If the upload fails, look at the Java Console of the browser to determine whether an exception was thrown.

Monitoring Datapower

The most common method of monitoring DataPower appliances (e.g. in production) is SNMP polling using any industry standard operations management solution.

Configuring DataPower to support SNMP monitoring is well documented (see the Web GUI guide, Managing the System\Configuring SNMP Settings) and easy to do. In the same place that you configure DataPower's SNMP settings, you can download the MIBs defined by DataPower. The Status MIBs define the most useful variables for monitoring the appliance.

For starters, IBM's ISSW organization recommends monitoring the following variables against the specified thresholds:

If {dpStatusEthernetInterfaceStatusStatus} is {'no-link'} then {raise alert}
If {dpStatusSystemUsageLoad} is {Greater than 90 in 5 successive intervals} then {raise alert}
If {dpStatusMemoryStatusFreeMemory} is {Less than '204800' (kbytes)} then {raise alert}
If {dpStatusFilesystemStatusFreeEncrypted} is {Less than '40' (MB)} then {raise alert}
If {dpStatusFilesystemStatusFreeTemporary} is {Less than '25' (MB)} then {raise alert}

DataPower also supports a handful of SNMP traps through simple SNMP settings configuration. Additionally, you can configure SNMP log targets such that any log event can become an SNMP trap.

DataPower appliances come with ITCAM SE for DataPower. While the primary purpose of ITCAM SE for DataPower is managing the deployment and synchronization of configuration and firmware versions across sets of multiple DataPower appliances, it can be configured to collect SNMP information. However, it's likely that your organization will already have better solutions for that purpose.

DataPower appliances can also be monitored using the supported XML Management interface (see the Web GUI guide, Network Objects\XML Management Interface) which supports sending SOAP requests to an appliance to get or set configuration or status information among other things.

ANOTHER LIST OF STATUS ITEMS TO CHECK AND HOW:

SNMP Polling
n dpStatusCPUUsagetenMinutes
■ This is a 10 minute CPU usage indicator
■ Returned value is a percentage
■ Alarm for any value over 50
n dpStatusMemoryStatusFreeMemory
■ Returned value is in kbytes
■ Alarm if returned value is less than 830012
■ Alarm value is 20% of total memory value of 4150060 kbytes.
n dpStatusEthernetInterfaceStatusStatus
■ If ok, will return status of 1
■ If no-link, will return status of 2
■ Alarm if eth0, eth1, or eth4 has value of 2
■ Ping checks of all interfaces have also been implemented by Site Scope.
n dpStatusEnvironmentalSensorscpu1Temp
■ Returns temperature in celsius
■ Alarm if returned value is m ore than 70
n dpStatusEnvironmentalSensorscpu2Temp
■ Returns temperature in celsius
■ Alarm if returned value is more than 70
n dpStatusEnvironmentalSensorssystemTemp
■ Returns temperature in celsius
■ Alarm if returned value is more than 70
n dpStatusEnvironmentalSensorspowersupply
■ If ok, will return status of 1
■ If power-1-failure, will return status of 2
■ If power-2-failure, will return status of 3
■ Alarm for any value other than 1
Optional monitoring:
n dpStatusCPUUsageoneMinute
■ This is a 1 minute CPU usage indicator
■ Returned value is percentage
■ Alarm for any value over 75

AGAIN, HERE ARE THE OPTIONS:

• Two step process:

– configure Trap and Notification Targets on device for SNMP trap receivers

– configure Log Target of type SNMP to emit SNMP traps to configured receiver
AND/OR
configure Trap Event Subscriptions to emit traps globally for specific event error codes

• drNotificationMIB.txt describes the general structure of SNMP traps thrown by DataPower. This can be imported into monitoring solutions to decipher trap structure.
   
• All DataPower traps look exactly the same at the trap receiver. Error codes and text differentiates one notification from another.

WS-Security describes enhancements to SOAP messaging to provide quality of protection through message integrity, message confidentiality, and single message authentication. These mechanisms can be used to accommodate a wide variety of security models and encryption technologies.

WS-Security also provides a general-purpose mechanism for associating security tokens with messages. No specific type of security token is required by WS-Security. It is designed to be extensible (e.g. support multiple security token formats). For example, a client might provide proof of identity and proof that they have a particular business certification.

Additionally, WS-Security describes how to encode binary security tokens. Specifically, the specification describes how to encode X.509 certificates and Kerberos tickets as well as how to include opaque encrypted keys. It also includes extensibility mechanisms that can be used to further describe the characteristics of the credentials that are included with a message.

Composable Architecture

By using the SOAP extensibility model, SOAP-based specifications are designed to be composed with each other to provide a rich messaging environment. By itself, WS-Security does not ensure security nor does it provide a complete security solution. WS-Security is a building block that is used in conjunction with other Web service and application-specific protocols to accommodate a wide variety of security models and encryption technologies. Implementing WS-Security does not mean that an application cannot be attacked or that the security cannot be compromised.

WS-Security is flexible and is designed to be used as the basis for the construction of a wide variety of security models including PKI, Kerberos, and SSL. Specifically WSSecurity provides support for multiple security tokens, multiple trust domains, multiple signature formats, and multiple encryption technologies. This specification provides three main mechanisms: security token propagation, message integrity, and message confidentiality. These mechanisms by themselves do not provide a complete security solution. Instead, WS-Security is a building block that can be used in conjunction with other Web service extensions and higher-level application-specific protocols to accommodate a wide variety of security models and encryption technologies.

These mechanisms can be used independently (e.g., to pass a security token) or in a tightly integrated manner (e.g., signing and encrypting a message and providing a security token hierarchy associated with the keys used for signing and encryption). This document supercedes existing web services security specifications from IBM and Microsoft including SOAP-SEC; Microsoft's WS-Security and WS-License; and IBM's security token and encryption documents.

The following namespaces are used in the security features of DataPower often (note the prefixes as well):

Prefix	Namespace
s	http://www.w3.org/2001/12/soap-envelope
ds	http://www.w3.org/2000/09/xmldsig#
xenc	http://www.w3.org/2001/04/xmlenc#
m	http://schemas.xmlsoap.org/rp
wsse	http://schemas.xmlsoap.org/ws/2002/04/secext
S11	http://schemas.xmlsoap.org/soap/envelope/
S12	http://www.w3.org/2003/05/soap-envelope
wsse11	http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd
wsu	http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd

 

Terminilogy

We provide basic definitions for the security terminology used in these specifications:

Claim – A claim is a statement that a client makes (e.g. name, identity, key, group, privilege, capability, etc).

Security Token – A security token represents a collection of claims.

Signed Security Token – A signed security token is a security token that is asserted and cryptographically endorsed by a specific authority (e.g. an X.509certificate or a Kerberos ticket).

Proof-of-Possession – The proof-of-possession information is data that is used in a proof process to demonstrate the sender's knowledge of information that SHOULD only be known to the claiming sender of a security token.

Integrity – Integrity is the process by which it is guaranteed that information is not modified in transit.

Confidentiality – Confidentiality is the process by which data is protected such that only authorized actors or security token owners can view the data

Digest – A digest is a cryptographic checksum of an octet stream.

Signature - A signature is a cryptographic binding of a proof-of-possession and a digest. This covers both symmetric key-based and public key-based signatures.

Consequently, non-repudiation is not always achieved.

Attachment – An attachment is a generic term referring to additional data that travels with a SOAP message, but is not part of the SOAP Envelope.

Quality of Protection

In order to secure a SOAP message, two types of threats should be considered:

• the message could be modified or read by antagonists
• an antagonist could send messages to a service that, while well-formed, lack appropriate security claims to warrant processing. To understand these threats we define a message security model.

Message Security Model

In this document we specify an abstract message security model in terms of security tokens combined with digital signatures as proof of possession of the security token (key).

Security tokens assert claims and signatures provide a mechanism for proving the sender’s knowledge of the key. As well, the signature can be used to "bind" or "associate" the signature with the claims in the security token (assuming the token is trusted). Note that such a binding is limited to those elements covered by the signature. Furthermore note that this document does not specify a particular method for authentication, it simply indicates that security tokens MAY be bound to messages.

A claim can be either endorsed or unendorsed by a trusted authority. A set of endorsed claims is usually represented as a signed security token that is digitally signed or encrypted by the authority. An X.509 certificate, claiming the binding between one's identity and public key, is an example of a signed security token. An endorsed claim can also be represented as a reference to an authority so that the receiver can "pull" the claim from the referenced authority.

An unendorsed claim can be trusted if there is a trust relationship between the sender and the receiver. For example, the unendorsed claim that the sender is Bob is sufficient for a certain receiver to believe that the sender is in fact Bob, if the sender and the receiver use a trusted connection and there is an out-of-band trust relationship between them.

One special type of unendorsed claim is Proof-of-Possession. Such a claim proves that the sender has a particular piece of knowledge that is verifiable by, appropriate actors. For example, a username/password is a security token with this type of claim.

A Proof-of-Possession claim is sometimes combined with other security tokens to prove the claims of the sender. Note that a digital signature used for message integrity can also be used as a Proof-of-Possession claim, although in this specification we do not consider such a digital signature as a type of security token. It should be noted that this security model, by itself, is subject to multiple security attacks. Refer to the Security Considerations section for additional details.

Message Protection

Protecting the message content from being intercepted (confidentiality) or illegally modified (integrity) are primary security concerns. This specification provides a means to protect a message by encrypting and/or digitally signing a body, a header, an attachment, or any combination of them (or parts of them).

Message integrity is provided by leveraging XML Signature in conjunction with security tokens to ensure that messages are transmitted without modifications.

The integrity mechanisms are designed to support multiple signatures, potentially by multiple actors, and to be extensible to support additional signature formats.

Message confidentiality leverages XML Encryption in conjunction with security tokens to keep portions of a SOAP message confidential. The encryption mechanisms are designed to support additional encryption processes and operations by multiple actors.

Missing or Inappropriate Claims

The message receiver SHOULD reject a message with invalid signature, missing or inappropriate claimsas it is an unauthorized (or malformed) message. This specification provides a flexible way for the message sender to claim the security properties by associating zero or more security tokens with the message. An example of a security claim is the identity of the sender; the sender can claim that he is Bob, known as an employee of some company, and therefore he has the right to send the message.

Message Level Security

In message-level security, security information is contained within the SOAP message and/or SOAP message attachment, which allows security information to travel along with the message or attachment. For example, a portion of the message may be signed by a sender and encrypted for a particular receiver. When the message is sent from the initial sender, it may pass through intermediate nodes before reaching its intended receiver. In this scenario, the encrypted portions continue to be opaque to any intermediate nodes and can only be decrypted by the intended receiver. For this reason, message-level security is also sometimes referred to as end-to-end security.

SOAP

SOAP is a lightweight and simple XML-based protocol designed to exchange structured and type information over the internet. Because it is XML, SOAP is language and platform-independent.

SOAP can be used to send any type of data between applications irrespective of what platform the applications are built on. Another major purpose of SOAP is to allow various components to communicate using remote functionality as if they were local, as is the case with web services. SOAP is recommended by the W3C and is often utilized with WSDL, UDDI, and the SOA request/response environment. All these technologies together make up the current standardized WS-*approach put forth by the W3C.

SOAP has become important to the Web Service model and the Internet as a whole, and has advantages over other proprietary protocols, specifically regarding how it handles and exchanges data. Since it is based on XML, SOAP inherently "understands" the simple data types noted by the W3 Schema Specification.

In general, SOAP defines a mechanism for encoding information into an XML wrapper. For Web Services, SOAP gets a bit more specific when it facilitates the mappings between method signatures and the XML document. The basic idea behind the use of the protocol is to interpret a remote method's parameter values at runtime and stuff those values into an XML document. The XML data is then transported to the remote server using the HTTP protocol (other transport protocols are also used). It is then that WSDL parameters and the web services themselves are defined.

SOAP - How and Why it is to be Implemented

An example of these parameters would be username and passwords, obvious parameters that need to be encrypted on the application layer. SOAP provides the method for doing this. This not only provides security from outside attacks but possible internal attacks as well.

Examples of attacks are SQL and LDAP injection, as well as cross-site scripting. Whether it is retrieving data that should not be retrieved or launching the data and services against themselves in a Denial of Service manner, encrypted XML messages, through the use of key validations, within a SOAP envelope, prevents this from occurring.

Often overlooked, the method of using HTTP as a transport is yet another benefit of using the SOAP protocol. The reason being that port 80 is usually left open on corporate firewalls, allowing SOAP data to pass through untouched. The other source of SOAP's power is the fact that the information transported by the HTTP protocol is actually XML. To be more specific, the content-type of the HTTP packet is text/xml.

XWS-Security

XWS-Security is an implementation of the Web Services Security (WSS) specification developed at OASIS. WSS defines a SOAP extension providing quality of protection through message integrity, message confidentiality, and message authentication. WSS mechanisms can be used to accommodate a wide variety of security models and encryption technologies.

The WSS specification defines an end to end security framework that provides support for intermediary security processing. Message integrity is provided by using XML Signature in conjunction with security tokens to ensure that messages are transmitted without modifications. Message confidentiality is granted by using XML Encryption in conjunction with security tokens to keep portions of SOAP messages confidential.

In this release, the XWS-Security framework provides the following options for securing JAX-RPC applications:

XML Digital Signature (DSig)
This implementation of XML and Web Services Security uses JSR-105 (XML Digital Signature APIs) for signing and verifying parts of a SOAP message or attachment. JSR-105 can be viewed at http://www.jcp.org/en/jsr/detail?id=105

XML Encryption (XML-Enc)
This implementation of XML and Web Services Security uses Apache's XML-Enc implementation, which is based on the XML Encryption W3C standard. This standard can be viewed athttp://www.w3.org/TR/ xmlenc-core/.

UsernameToken Verification
Username token verification specifies a process for sending UserNameTokens along with the message. Sending these tokens with a message binds the identity of the tokens (and any other claims occurring in the security token) to the message.

How XWS-Security and XML Digital Signature API Are Related

Before getting into specifics, it is important to see how XWS-Security and XML Digital Signature API are related. In this release of the Java WSDP, XWS-Security is based on non-standard XML Digital Signature APIs. XML Digital Signature API is an API that should be used by Java applications and middleware that need to create and/or process XML Signatures. It can be used by Web Services Security (the goal for a future release) and by non-Web Services technologies (for example, signing documents stored or transferred in XML). XWS-Security does not currently use the XML Digital Signature API or XML Digital Encryption APIs. XWS-Security uses the Apache libraries for XMLDSig and XML-Enc. The goal of XWS-Security is to move toward using these APIs in future releases.

Error Handling

There are many circumstances where an error can occur while processing security information. For example:

• Invalid or unsupported type of security token, signing, or encryption
• Invalid or unauthenticated or unauthenticatable security token
• Invalid signature
• Decryption failure
• Referenced security token is unavailable.

These can be grouped into two classes of errors: unsupported and failure. For the case of unsupported errors, the receiver MAY provide a response that informs the sender of supported formats, etc. For failure errors, the receiver MAY choose not to respond, as this may be a form of Denial of Service (DOS) or cryptographic attack. We combine signature and encryption failures to mitigate certain types of attacks.

If a failure is returned to a sender then the failure MUST be reported using SOAP's Fault mechanism. The following tables outline the predefined security fault codes.

Security Considerations

It is strongly RECOMMENDED that messages include digitally signed elements to allow message receivers to detect replays of the message when the messages are exchanged via an open network. These can be part of the message or of the headers defined from other SOAP extensions. Four typical approaches are:

• Timestamp
• Sequence Number
• Expirations
• Message Correlation

This specification defines the use of XML Signature and XML Encryption in SOAP headers. As one of the building blocks for securing SOAP messages, it is intended to be used in conjunction with other security techniques. Digital signatures need to be understood in the context of other security mechanisms and possible threats to an entity.

Digital signatures alone do not provide message authentication. One can record a signed message and resend it (a replay attack). To prevent this type of attack, digital signatures must be combined with an appropriate means to ensure the uniqueness of the message, such as timestamps or sequence numbers (see earlier section for additional details).

When digital signatures are used for verifying the identity of the sending party, the sender must prove the possession of the private key. One way to achieve this is to use a challenge-response type of protocol. Such a protocol is outside the scope of this document. To this end, the developers can attach timestamps, expirations, and sequences to messages.

Implementers should also be aware of all the security implications resulting from the use of digital signatures in general and XML Signature in particular. When building trust into an application based on a digital signature there are other technologies, such as certificate evaluation, that must be incorporated, but these are outside the scope of this document. Requestors should use digital signatures to sign security tokens that do not include signatures (or other protection mechanisms) to ensure that they have not been altered in transit.

Also, as described in XML Encryption, we note that the combination of signing and encryption over a common data item may introduce some cryptographic vulnerability. For example, encrypting digitally signed data, while leaving the digital signature in the clear, may allow plain text guessing attacks. Care should be taken by application designers not to introduce such vulnerabilities.