Message Level Security (Pipelines) for Legacy Web Services Imported from CAR Files

If messaging passes through intermediate sources in the transport layer (indirect messaging), you must define message-level security. For indirect messaging, or for multiple message receivers or senders, the message needs to be secured at different levels to ensure data integrity.

A pipeline defines multiple instructions that are processed simultaneously. Except for the Custom step, each pipeline step corresponds to a system built-in procedure available at /lib/services/ in the server.

• Viewing Message Pipeline Steps
• Creating a Log Message to File Pipeline Step
• Adding a Username Token Pipeline Step
• Creating an Element Pipeline Step
• Creating a Pipeline Step to Process a Procedure
• Creating a Pipeline Step to Delete an Element
• Creating a Pipeline Step to Encrypt an Element
• Creating a Pipeline Step to Process a Security Header
• Creating a Pipeline Step to Set Environment From Node
• Creating a Pipeline Step to Set Node From Environment
• Creating a Pipeline Step to Sign an Element

Viewing Message Pipeline Steps

You can provide message-level security by defining multiple steps of well-defined pipeline processing for request-response messages sent through Studio. Specifically, you can provide message-level security at the following locations of a SOAP or WSDL data source:

• SOAP operation

Operation-level security settings override the security settings of the port.

• WSDL operation

Operation-level security settings override the security settings of the port.

The message pipeline editor has the following overall characteristics:

• The Request Message Pipeline and Response Message Pipeline sections allow you to add message processing steps to the pipeline.
• You can click the upper Add button to view a drop-down list of the pipeline steps available to process the Request Message Pipeline:

Create Element, Custom, Delete Element, Log Message To File, Process Security Header, Set Environment From Node, Set Node From Environment

• You can click the lower Add button to view a drop-down list of the available Response Message Pipeline steps:

Add Username Token, Create Element, Custom, Delete Element, Encrypt Element, Log Message To File, Set Environment From Node, Set Node From Environment, Sign Element

• You can click a Delete button to remove a step.
• You can click an Edit button to change what you specified when you added the step.
• You can change the processing order of a step by selecting it and clicking the Move up or Move down button.

To view the available pipeline steps in Studio

Open the operations folder for the Web service that is to be secured.
1. In the editor that opens on the right, the Message Pipeline panel opens.
2. Click the Add button to view the pipeline steps in a drop-down list.

Creating a Log Message to File Pipeline Step

This pipeline step writes SOAP message contents to a file in the specified path. Create this pipeline step for a request message, response message, or both. The outputs from other pipeline steps can be written to the log file created by this step.

This pipeline step corresponds to the system procedure LogMessageToFile available in /lib/services/.

To create the pipeline step named Log Message To File

Open the pipeline editor for the resource that is to be secured.
3. Click the Add buttonin the Request Message Pipeline section or the Response Message Pipeline, as needed, and select Log Message To File.
4. In the File Path field, specify a file where the messages are to be logged. The file path is relative to the TDV Server log directory. If the file or the directory does not yet exist, it is created on the local file system of the server on execution.
5. In the File Mode field, specify how the message should be logged.

APPEND—Adds new messages to the end of the log file.

OVERWRITE—Causes new messages to overwrite the log file.

6. (optional) Text entered into the Header field is added to the given text in front of the new SOAP envelope message. The text supplies a header note, which is written to the file right before the message contents. This value can be null.
7. (optional) Text entered into the Footer field is added to the end of the processed message. This value can be null.
8. In the Pretty Print drop-down list, select true (default) if you want the message to be formatted with tabbed indents, and false if you do not want the message to be formatted.

Formatting the message can make it easier to read.

9. Click OK, and save the step.

The output of this pipeline step is the modified XML document or element. For example:

Adding a Username Token Pipeline Step

You can use this pipeline step to authenticate a response message. If the server hosting the Web service requires that the message has a username token, use this pipeline step.

This pipeline step adds a WS-Security UsernameToken to a SOAP envelope. The UsernameToken is added to the SOAP header that is identified by the Actor and Must Understand arguments. If the SOAP message does not contain a SOAP header with the specified Actor and Must Understand values, a header is created with those values.

This pipeline step corresponds to the system procedure AddUsernameToken, which is available in /lib/services/.

To create the pipeline step named Add Username Token

Open the pipeline editor for the resource that is to be secured.
10. Click the Add button in the Request Message Pipeline section, and select Add Username Token.
11. Values for the following fields need to be supplied in the Add Username Token window:

Field

Description of values

Example

Actor

Type a Uniform Resource Identifier (URI) used to specify the recipient of a header element.

Specifies the SOAP Actor attribute. If it is null, the recipient is the ultimate destination of the SOAP message.

The SOAP actor attribute can be used to address the Header element to a particular endpoint. A SOAP message can travel from a sender to a receiver by passing different endpoints along the message path. Not all parts of the SOAP message are intended for the ultimate endpoint of the SOAP message but, instead, are intended for one or more of the endpoints on the message path.

http://www.w3schools.com/appml

 

 

Actor1

Must Understand

Select true or false.

Indicates whether a header entry is mandatory or optional for the recipient to process.

If you specify Must Understand=true to a child element of the Header element, it indicates that the receiver processing the Header must recognize the element. If the receiver does not recognize the element it must fail when processing the Header.

If you specify Must Understand=false to a child element of the Header element, it indicates that the receiver processing the Header need not recognize the element.

true

Username

Valid user name to access the Web service server.

joeuser

Password

Valid password associated with Username.

password

Password Type

Specify the password type, to determine how the password is encoded in the Username Token:

DIGEST—Password is rendered in a digested text in the message

TEXT—Password is rendered in clear text in the message

DIGEST
12. Click OK after supplying all the required information, and save the step.

The UsernameToken is added to the SOAP header that is identified by the entry supplied in the Actor field and Must Understand field. If the SOAP message does not contain a SOAP header with the specified Actor and Must Understand values, a header is created with those values.

The following shows sample output:

The digested password is rendered as follows:

            <wsse:Password
        
            Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">APy0l8XZkRsJH7qiAwC6W11D+gs=</wsse:Password>

Creating an Element Pipeline Step

This pipeline step creates a child element in an XML document or within another element.

This pipeline step corresponds to the system procedure CreateElement, which is available in

            /lib/services/

To create the pipeline step named Create Element

Open the pipeline editor for the resource that is to be secured.
13. Click the Add buttonin the Request Message Pipeline section, and select Create Element.
14. Supply the fully qualified name of the element in the Element Name field.

This value cannot be null.

15. Specify the position of the element in the Element Position field.

This position is relative to the element’s siblings. The default value is 0 (zero). A value of zero indicates that the element should be created before any existing children. A value of -1 (negative one) indicates that the element should be created after all existing children.

16. Type the path to the parent of the element in the Parent XPath field.

The Parent XPath value is used to select the parent element, relative to the root of the element to be created. This entry cannot be null.

17. In the Prefix field, specify the namespace prefix used in the Parent XPath field.
18. In the Namespace field, specify the namespace URIs used in the Parent XPath expression.
19. Optionally, click the Add button next to Declare namespaces used in XPath expressions to define an additional prefix-namespace pair.
20. Optionally, click the Delete button next to a prefix-namespace pair to delete the pair.
21. Click OK.

Creating a Pipeline Step to Process a Procedure

This pipeline step processes a custom procedure supplied to it. The signature of a custom procedure supplied to a message pipeline should follow these rules:

• It must not have any OUT parameters.
• It must have only IN or INOUT parameter. There can be more than one IN or INOUT parameter in the signature.
• The first parameter must be of type XML, which can be defined as an IN or INOUT parameter.

The example here uses the following custom procedure (CustomPipelineStep) which calls the system procedure /lib/debug/Log:

PROCEDURE CustomPipelineStep(IN document XML, IN param1 INT)
    BEGIN
        CALL /lib/debug/Log(CAST(document AS VARCHAR(4096)));
    END

The first parameter is an input parameter of type XML.

To create the pipeline step named Custom

Open the pipeline editor for the resource that is to be secured.
22. Click the Add button in the Request Message Pipeline or Response Message Pipeline section, and select Custom.
23. Use the Browse button to locate and select the custom pipeline procedure.
24. Supply the input parameter value in the Parameter Values field.
25. Optionally, select a parameter value and click Edit to change the value.
26. Click OK.

The following shows a sample log message:

Creating a Pipeline Step to Delete an Element

This pipeline step deletes one or more nodes from an XML document or element.

The example used here deletes the Header element named MyCustomHeader which was created in the section Creating an Element Pipeline Step.

This pipeline step corresponds to the system procedure DeleteElement, which is available in /lib/services/.

To delete one or more nodes from an XML document or element

Open the pipeline editor for the resource that is to be secured.
27. Click the Add button in the Request Message Pipeline or Response Message Pipeline section, and select Delete Element.Type the path to the parent of the element in the Parent XPath field.

This path is used to select the nodes to be deleted. The path is evaluated against the root node. All resulting nodes are deleted. This entry should not contain any namespaces.

28. Optionally, click the Add button next to Declare namespaces used in XPath expressions to define an additional prefix-namespace pair.
29. Optionally, click the Delete button next to a prefix-namespace pair to delete the pair.
30. In the Prefix field, specify the namespace prefix used in the XPath field.
31. In the Namespace field, specify the namespace URIs used in the XPath field.
32. Click OK and save the step.

Creating a Pipeline Step to Encrypt an Element

This pipeline step is used to encrypt the BODY element in the specified SOAP envelope using a symmetric key that is encrypted by a certificate or public key.

This pipeline step corresponds to the system procedure EncryptElement, which is available in /lib/services/.

To create the pipeline step named Encrypt Element

Open the pipeline editor for the resource that is to be secured.
33. Click the Add button in the Response Message Pipeline section, and select Encrypt Element.

UI Element

Description

Procedure path

The path to the pipeline step procedure (by default, /lib/services/EncryptElement).

Actor

Type a URI. See To create the pipeline step named Add Username Token .

Must Understand

Select true or false.

Element Name

The default value of the Element Name field specifies the schema of the SOAP message that is encrypted. This procedure can be used to encrypt the SOAP message body.

The Element Name field can be null, but the default value of

{http://schemas.xmlsoap.org/soap/envelope/}Body

is used to specify the message body for encryption:

{http://schemas.xmlsoap.org/soap/envelope/}Body

Encryption Algorithm

Accept the default algorithm AES_128 or select a different one if you have installed an unrestricted Java Cryptography Extension (JCE) policy file in the server’s JVM.

Determines the method of encryption. The default value of AES_128 is sufficient for most purposes. Stronger encryption algorithms such as AES_192 or AES_256 require that an unrestricted Java Cryptography Extension (JCE) policy file be installed in the server’s JVM.

Certificate Alias

Select or type an appropriate certificate alias.

If the WSDL data source or Web service has a list of certificates associated with it, the aliases of those certificates are listed here.

The alias of a certificate or public key in the key store that is used to encrypt the symmetric key that is used to encrypt the element. It cannot be null.

Certificates are associated with a data source using the Data Source connection properties. To access the certificates, open the editor for the WSDL data source and click the Advanced tab in the Connection Information section. Any Alias listed in the Certificates table can be used as the Certificate Alias in a pipeline step.

34. Supply all required values and click OK.

Creating a Pipeline Step to Process a Security Header

This pipeline step is used to process a WS Security SOAP header in a SOAP envelope, as follows:

• If the envelope contains a WS Security header with the specified actor, the header is processed.
• All security elements in the header are evaluated.
• If any header security element indicates that the envelope contains signed elements, the signatures of those elements are verified.
• If any header security element indicates that the envelope contains encrypted elements, those encrypted elements are decrypted.

This pipeline step corresponds to the system procedure ProcessSecurityHeader, which is available in /lib/services/.

To create the pipeline step named Process Security Header

Open the pipeline editor for the resource that is to be secured.
35. Click the Add buttonin the Request Message Pipeline section, and select Process Security Header.
36. Supply the path to the pipeline step procedure if it is different from /lib/services/ProcessSecurityHeader.
37. Supply a value in the Actor field, if necessary.

The Actor determines which WS Security header to process. It can be null.

38. Click OK to save the step.

Creating a Pipeline Step to Set Environment From Node

This pipeline step saves an element or attribute value as an environment variable. It evaluates the given xpath expression against the envelope, and stores the result in the environment in a variable with the specified name. The result of the xpath expression is interpreted as a single string.

This pipeline step corresponds to the system procedure SetEnvironmentFromNodeValue, which is available in /lib/services/.

To create the pipeline step named Set Environment From Node

In the pipeline editor for the resource that is to be secured, click the Add button in the Request Message Pipeline or Response Message Pipeline section and select Set Environment From Node.
39. Type the path and step name in the Procedure Path field if it is different from /lib/services/SetEnvironmentFromNodeValue.
40. Type the XPath value in the XPath field.

The XPath entry is evaluated to some text which is stored in the variable name provided in the Variable Name field.

41. Type the variable name in the Variable Name field, without any spaces in the name string.

Variable Name is the name of an environment variable. It is an arbitrary string, and it is not case-sensitive. (Both sample and SAMPLE are considered the same.)

42. In the Prefix field, specify the namespace prefix used in the XPath field.
43. In the Namespace field, specify the namespace URIs used in the XPath expression.
44. Optionally, click the Add button next to Declare namespaces used in XPath expressions to define an additional prefix-namespace pair.
45. Optionally, click the Delete button next to a prefix-namespace pair to delete the pair.
46. Click OK.

Creating a Pipeline Step to Set Node From Environment

This pipeline step sets an element or attribute value from an environment variable. The given xpath expression is used to select a node from the envelope. The node value is then set to the value of the specified environment variable.

This pipeline step corresponds to the system procedure SetNodeValueFromEnvironment, which is available in /lib/services/.

To create the pipeline step named Set Node From Environment

In the pipeline editor for the resource that is to be secured, click the Add buttonin the Request Message Pipeline or Response Message Pipeline section and select Set Node From Environment.
47. Type the path and step name in the Procedure Path field if it is different from /lib/services/SetNodeValueFromEnvironment.
48. Type the XPath value in the XPath field.

The XPath expression is evaluated to an element.

49. Type the name of an environment variable in the Variable Name field, without a space in the name string.

Variable Name is an arbitrary string, and is not case-sensitive. (Both sample and SAMPLE are considered the same.)

50. In the Attribute Name field, specify the attribute whose value is to be set from the environment variable.
51. In the Prefix field, specify the namespace prefix used in the XPath field.
52. In the Namespace field, specify the namespace URIs used in the XPath expression.
53. Optionally, click the Add button next to Declare namespaces used in XPath expressions to define an additional prefix-namespace pair.
54. Optionally, click the Delete button next to a prefix-namespace pair to delete the pair.
55. Click OK, and save the step.

Creating a Pipeline Step to Sign an Element

This pipeline step is the simplified version of Encrypt Element, and is used to sign an element in the specified SOAP envelope using a private key.

This pipeline step corresponds to the system procedure SignElement which is available in /lib/services/.

To create the pipeline step named Sign Element

In the pipeline editor for the resource that is to be secured, click the Add button in the Response Message Pipeline section and select Sign Element.
56. Type the path and step name in the Procedure Path field if it is different from /lib/services/SignElement.
57. For details on Actor, Must Understand, Element Name, and Certificate Alias, see To create the pipeline step named Encrypt Element.
58. Supply all required values and click OK.