Table Of Contents

Basic Concepts

Planning Your Implementation

Development Steps

About Virtual Services

Basic Versus Advanced Virtual Services

About Security and the ACE XML Gateway

Overview of Required Resources

Applying Security Resources

Further Reading

Order of Processing Operations

Flex Path Request Processing

Flex Path Response Processing

Regular Expressions in the Policy

Service-First Classification of Message Traffic

Basic Concepts

---

This chapter provides an overview of concepts behind the Cisco ACE XML Gateway system. It covers these topics:

•Planning Your Implementation

•Development Steps

•About Virtual Services

•About Security and the ACE XML Gateway

•Order of Processing Operations

•Regular Expressions in the Policy

•Service-First Classification of Message Traffic

Planning Your Implementation

An ACE XML Gateway processes traffic as directed by its policy. The policy determines what backend services are available at the ACE XML Gateway, credential requirements for accessing the services, how traffic is validated or modified, and most other activities of the ACE XML Gateway.

Once the ACE XML Gateway is installed on the network, the next step is to develop its policy in the ACE XML Manager web console, the browser-based development environment for ACE XML Gateway policies.

Before you start developing the policy, it is important to collect as much information as possible on your network and how you intend to use the ACE XML system. Careful planning can result in a policy that is more effective and maintainable. While the following is not an exhaustive list of the factors that will affect your configuration, it suggests the type of information you will need to implement the policy:

•Protocols to be used for consumer- and service-side interfaces (such as HTTP, SOAP or TIB/RV)

•Connection information for the services you plan to virtualize at the ACE XML Gateway

•Access and security requirements for backend services

•The path portion of the URL at which the service will be exposed to consumers

•Port numbers on which the ACE XML Gateway will listen for consumer requests

•Authentication requirements and how they will be evaluated

•Whether to encrypt messages or channels (by port) and, if so, what certificate/key pairs to use

•Certificate Authorities to trust

•Message validation and acceleration measures to use

•How to publish service availability

Once you have addressed these and possibly other questions, setting up the policy is simply a matter of applying the configuration settings according to your plan.

Development Steps

Developing a ACE XML Gateway policy is usually an iterative process, with recurring steps required for developing, testing and deploying the policy. However, the general workflow for developing the ACE XML Gateway policy is as follows:

1. Define the services to be proxied by the ACE XML Gateway. You can jump-start this task by importing a WSDL file that describes the services to be proxied.

2. Specify how incoming requests are validated, using XML schema validation, well-formedness checking, content screening, XML signature verification, and so on.

3. Specify encryption or decryption settings for the service.

4. Create authenticators that qualify service requests. Authenticators can specify access conditions based on a variety of credential types, including passwords, X509 certificates, SAML tokens, and more.

5. Review the policy for security flaws or configuration problems. To help you with this step, the ACE XML Manager performs an automated review of each policy before deploying it.

6. When the policy is ready to be enforced, deploy it to the ACE XML Gateway. The policy is applied to traffic passed through the ACE XML Gateway.

7. Monitor system performance. Use the monitoring and diagnostic tools provided by the ACE XML Manager to ensure that your network is secure and performing as expected.

About Virtual Services

The ACE XML Gateway can virtualize various types of backend services. The services may be SOAP services, REST-based application resources, a message bus queue, or many other types of resources. Whatever the backend service type, the ACE XML Gateway policy represents the settings for the service with a policy object called a virtual service.

A virtual service contains connection settings for the backend server, processing and validation rules for traffic directed to the service, and other service-specific settings.

A virtual service usually defines a simple message path through the ACE XML Gateway. It provides a one-to-one correspondence between a consumer and a backend service interface, with settings for both the request and response branch of the transaction. This type of virtual service is called a basic virtual service, and appears in the virtual service browser as shown in Figure 2-1.

Figure 2-1 Advanced virtual service definition

Virtual services can also be defined using policy objects that separately specify the consumer and backend service interfaces. Service descriptors contain settings for a backend service, and handlers contain settings for the consumer interface. A route joins the handler to a service descriptor. This type of virtual service is called an advanced virtual service, as appears in the virtual service browser as shown in Figure 2-2.

Figure 2-2 Advanced virtual service definition

Advanced virtual services allow you to implement branched routing and protocol mediation, among other advanced configuration scenarios. In branched routing, a single handler routes messages to one of several service descriptors (as shown in Figure 2-2), or from multiple handlers to on service descriptor. The routes define the conditions that determine which backend service gets a given message.

Figure 2-3 Branched routing

When creating SOAP service definitions by WSDL import, you can choose to have the ACE XML Manager generate a basic or advanced virtual service.

For SOAP Document services, you have the additional option of creating a virtual service object per operation or a basic virtual service for each service element in the WSDL, in which case the virtual service contains multiple operations. If all operations in the service require the same settings, using a multiple-operation virtual service is usually more convenient. If needed, you can override an operation in the service to specialize its configuration.

Basic Versus Advanced Virtual Services

A basic virtual service (that is, one made up of single policy object) is usually easier to work with. However, in some cases, it's necessary or more practical to develop virtual services made up of multiple objects. How do you decide which approach to use for a given service? The following table lists factors that should inform your decision.

Table 2-1 Basic versus advanced services

Use a basic virtual service object if...	Use an advanced virtual service if...
You want the convenience of configuring settings for multiple SOAP operations in a single service definition.	Settings for each operation need to be configured separately, or for any reason it's not inconvenient to work with operations separately.
Mediation is not required between protocols, that is, HTTP requests are routed to backend HTTP services, for example.	You want to mediate between protocols, passing HTTP requests to message servers, for example.
The backend service is HTTP- or SOAP-based.	The protocol of the service or consumer interface is either TIB/RV, MQSeries, JMS, ebXML over SMTP, or ebXML over HTTP.
Passthrough mapping of message header or body values is sufficient	Custom value mappings and replacements are required for message header or body values between the consumer and service interface.
Content caching is not important	You want to cache responses passed to the consumer.

You can create a new virtual service as either a single or multiple objects. If you create a virtual service as a single object, however, it can later be split into its component parts. (However, since it contains additional configurable settings, a virtual service made up of component parts cannot be reassembled into a single object.) The button in the web console for this operation is labeled Convert to Advanced.

About Security and the ACE XML Gateway

The security technologies behind many ACE XML Gateway features, such as PKI and cryptography, are familiar and well-established. Implementing security in the ACE XML Gateway requires at least familiarity with these technologies and, preferably, hands-on experience.

Even to experienced professionals, however, implementing security in the context of an ACE XML Gateway likely involves new tasks. As advertised, an SOA diminishes the distinction between network operation and application development, while most practical experience with security is likely focused on one realm or the other.

The following sections provide an overview of the tasks needed to secure network traffic. Keep in mind that securing data communications always comes at some cost, most notably in performance. Encryption and decryption, message validation, and message screening rules can all improve security, but also affect the overall performance of the system. Implementing the system often involves balancing the concerns of security and performance.

Overview of Required Resources

There are two types of security resources used in an ACE XML Gateway implementation:

•Resources needed to secure the internal operations of the system (such as communication between the ACE XML Manager and Gateways and administration access to the ACE XML Manager).

•Resources needed to secure service traffic at the Gateway (such as to establish SSL channels or encrypt and decrypt traffic).

Internal resources are typically set up upon initial installation of the appliance. External resources, on the other hand, usually need to be added and maintained on an ongoing basis, as new service providers, clients, or services are brought online.

These types of resources include:

•A public/private keypair for the ACE XML Gateway. the ACE XML Gateway will usually need to have its own public/private keypair. (You can use just one, however, for multiple Gateways in a cluster, as long as they are addressed by a single externally resolvable hostname.) A public/private keypair is used for SSL, XML Encryption and XML Signature.

•Partner Public key certificates. A certificate contains the public key of a subject, a signature certifying its validity, along with other information. You will need to acquire public certificates for partners for whom you want to verify signatures and encrypt content.

•Certificate Authority certificates. The ACE XML Gateway, by default, is not configured with any trusted Certificate Authorities. Uploading a CA certificate enables the ACE XML Gateway to trust consumer certificates issued by that CA.

After installing the ACE XML Gateway system, you typically need to acquire a public/private keypair resource for it. To get a keypair, you start by generating a temporary keypair in the ACE XML Manager. You then submit the generated public key to a certificate authority (CA) for certification. Alternatively, if the system is for use internally within your organization only, a self-signed certificate may be sufficient. (For information on generating a certificate and CSR from the ACE XML Manager console, see "Generating a CSR" section on page 28-280.)

Once certified by the CA, the public key and signature are wrapped in a resource called an X.509 certificate. The public key is conveyed to partners within the certificate, which allows them to verify the public key by the CA signature. Partners will need your public key to encrypt content or verify signatures generated by the ACE XML Gateway.

The following section provides more information on how to apply the resources to use ACE XML Gateway features.

Applying Security Resources

Which security resources you need and how they are applied depend on the intended operation of your system. For the typical SOAP application, SSL is used to secure the channel with some combination of XML Signature and XML Encryption used to ensure the validity and security of the message.

The following table describes resources required by feature.

Table 2-2 Resource required by feature

To...	You will need to...
SSL for the client connection	Configure a secure port using the ACE XML Gateway's public/private keypair. The keypair is used for the asymmetric cryptography portion of the exchange, in which SSL negotiation occurs to exchange a session key. Once exchanged, the session key is used to encrypt traffic (symmetric cryptography).
Decrypt content secured with XML Encryption	Use the ACE XML Gateway's private key (that is, the private key portion of the public/private keypair resource generated for the ACE XML Gateway). The consumer or server that encrypts the information will need to have the ACE XML Gateway's public key, which it uses to encrypt the content.
Encrypt content with XML Encryption	Encrypt the content with the public key of the intended recipient of the content. The public key can be manually loaded into the policy or captured by the Gateway when authenticating the request.
Verify XML Signatures	An XML signature is verified using the public key corresponding to the private key used to create the signature. If a signature in an incoming message can be verified with the key, the receiver can be sure that the source of the message is the holder of the private key and that the message has not been modified since the signature was generated. In the ACE XML Gateway, the key used for this purpose can be: •Loaded into the policy and specified in the service description. In this case, the key must first be acquired from the source organization and uploaded into the ACE XML Gateway policy. •Extracted from the signature itself. The key must be issued by one of the certificate authorities the ACE XML Gateway is configured to trust.
Generate XML Signature	Recipients will need your certificate (or more specifically, the public key within the certificate) to verify the signature, which is generated in the ACE XML Gateway using the ACE XML Gateway's private key.
Authenticate clients by x.509 certificate	Upload the consumer certificate (for verification by certificate match) or the certificate of the CA for whom you want to specify trust. That is, if a valid consumer certificate is signed by a CA for which you have specified a trust relationship by uploading its certificate, the consumer certificate will be accepted.

Further Reading

For more information on the general concepts surrounding PKI and XML security, we recommend the following resources:

•For SSL overview, "SSL and TLS" by Eric Rescorla

•For WS-Security, "Securing Web Services with WS-Security" by Rosenberg and Remy

•Public key cryptography on Wikipedia: http://en.wikipedia.org/wiki/Public_key_cryptography

Order of Processing Operations

In processing a request at a virtual service interface, the ACE XML Gateway can apply a wide range of processing and validation operations to the message. When developing or troubleshooting a policy, it is often useful to know the order in which the operations are performed by the ACE XML Gateway.

Order of operations information is most relevant for advanced features of the policy, such as XSL Transforms or SDK transformation extensions. Since these features involve modifying the message directly, it is helpful to understand where in the processing chain the transformation sees the message, and what validation or transformation operations have already been applied to the message.

An important point to understand about Gateway processing is that, within certain parameters, the order of operations is not guaranteed. The primary reason for this variability is that, depending on what features are enabled for a service definition, the ACE XML Gateway may change the order of operations to optimize message processing for best performance.

While the exact order of certain operations cannot be guaranteed, the variation is limited so that it can only occur within certain well-defined phases of the ACE XML Gateway's processing activities. The phases are described in the following sections.

Flex Path Request Processing

Figure 2-4 shows the general steps in which message are processed by the ACE XML Gateway. This description applies to HTTP requests, although the processing order for other types of messages is similar.

Figure 2-4 Flex Path request processing

The following steps provide details on each processing phase:

1. Read/parse the message.

2. Classify the request initially based on request URL path and headers. For SOAP requests, the ACE XML Gateway also uses the SOAPAction header, if present, to associate the request to a handler.

3. Evaluate envelope-level credentials. Envelope-level credentials are made up of any credential type that is not SOAP-specific:

–Check Basic Auth header.

–Invoke a Security Token credential check (in this type of credential, a value from the request is evaluated by an external web service).

–Check source IP address.

–Check XPath password.

–Check SSL certificate.

–Invoke SDK standalone extension authorizer.

4. Assign message to a handler based on the request URL and results of envelope-level credential check. Notice that envelope-level credential types can be used to disambiguate handler destinations for requests that otherwise match multiple handlers.

5. Evaluate body-level credentials. The body level credentials are SOAP specific. They are evaluated only after the request is assigned to a SOAP service definition.

–Process WSS Username/Password.

–Process SAML.

6. Determine routing (that is, which service definition will receive the message). If the virtual service maps the consumer interface to a single service, a decision is not required. However, for handlers that route to multiple service definitions, the ACE XML Gateway makes a decision based on the routing criterion. (Note that the effect of XSLT processing on the message content that is done as part of request processing does not affect the routing decision.)

7. Perform incoming request processing in this general order:

–Apply pre-processing XSLT.

–Invoke SDK transform extension.

–Process SOAP headers. The ACE XML Gateway performs the tasks imposed by the SOAP headers in the order in which the headers appear in the incoming message. Tasks include decrypt XML Encrypted content, Validate XML Signature, process any other SOAP headers, such as a timestamp.

–Check for SOAP attachments.

–Check well-formedness or XML schema conformance.

8. Perform route processing:

–Apply XSLT.

–Map arguments.

–Map headers.

9. Perform outgoing request processing:

–Check well-formedness or XML schema conformance. Message validity is rechecked here to ensure that XSLT or extension processing has not broken message structure.

–Invoke SDK transform extension.

–Generate timestamp.

–Generate signature.

–Perform content encryption.

Note that the ACE XML Gateway always performs XML signing and encryption in this order, first generating the signature and then encrypting the signed content.

–Apply post-processing XSLT to message.

10. Send message to destination.

Flex Path Response Processing

Processing of the corresponding response is performed as shown in Figure 2-5.

Figure 2-5 Flex Path response processing

The processing steps follow:

1. Read/parse response from destination.

2. Check for exception content in response and, if found, apply exception mapping.

3. Perform incoming response processing:

–Apply pre-processing XSLT.

–Invoke SDK transform extension.

–Process SOAP headers in the order in which they appear in the message. Header processing may involve decrypting content, validating digital signatures, and validating any other SOAP headers, such as timestamps.

–Check for SOAP attachments.

4. Perform route processing:

–Apply route XSLT.

–Map arguments.

–Map headers.

5. Perform outgoing response processing:

–Invoke SDK transform extension.

–Add timestamp.

–Generate signature.

–Encrypt content.

–Apply post-processing XSLT.

6. Send message to client.

Regular Expressions in the Policy

Certain policy features allow you to use regular expressions in their configuration settings. For example, regular expressions can be used in content screening, request URL matching, credential authentication, and elsewhere.

For virtual service features, the ACE XML Gateway implements POSIX 1003.2 regular expressions. The ACE XML Gateway uses a strict implementation of the standard. Regular expressions are compiled with new line-sensitivity enabled. This means that the caret (^) character will match line starts. (This may be especially useful for matching LDIF-formatted properties returned by LDAP look-ups, since each property occupies its own line.) Other effects of new line sensitivity is that the any-character operator (.) will not match a new line, and match-end-of-line operator ($) matches the empty string immediately before a new line.

For features related to virtual web applications, the ACE XML Gateway employ PERL-style regular expressions.

Service-First Classification of Message Traffic

Each message directed at version 6.0 and later of the Cisco ACE XML Gateway is processed either by a virtual web application interface or a virtual service interface, but never by both.

The Gateway classifies incoming messages according to HTTP request and response attributes, such as host, port, HTTP method, URL path, request GET parameter values, request POST parameter values, and request header values. If a Gateway service proxy and a virtual web application configure these message-classification settings identically, then the ACE XML Gateway web service interface gets the message, and the WAF does not process the message at all. That is, if an incoming message is an exact protocol/port/path match to both a web application and a virtual service consumer interface, with no additional matching parameters involved, the ACE XML Gateway proxy processes the message and the WAF proxy does not.

When classifying incoming message traffic, the Gateway considers a literal match to be more specific than a regular expression match, with the result that a literal message classifier takes precedence over an equivalent regular-expression-based classifier.

For example, consider a policy that provides both a virtual web application and virtual service handler shown in Table 2-3:

Table 2-3 Message classification example

	Virtual Service	Virtual Web Application
Protocol	HTTP	HTTP
Hostname	reactivity.com	reactivity.com
Port	80	80
Request URL	hello*	helloworld

An incoming request to http://reactivity.com:80/helloworld/ would match both interfaces. However, because the literal match that the virtual web application performs is considered more specific than the regular expression match that the virtual service performs, the virtual web application processes the message.

Unprovisioned handlers do not participate in or affect classification of incoming message traffic. That is, an unprovisioned virtual service does not block requests to a specific path that a virtual web application accepts.

---

Note The Manager Dashboard does not display a list of requests that matched no handler. Information on unmatched requests is available in the Web App Incident report and Event Log.

---