This chapter describes generally how to add security elements manually to messages sent by Caché web services and Caché web clients. It discusses the following topics:
The following chapters provide details on specific security tasks.
To add a security element to the WS-Security header element, you use the following general procedure in your web client or web service:
Create an instance of the applicable class or classes. To do so, you use a method named Create()
, depending on the class. The instance represents one of the WS-Security header elements such as <Username>
Add each instance to the WS-Security header element by updating the SecurityOut
property of your web client or web service. To do so, call the AddSecurityElement()
Send the SOAP message. The WS-Security header is included in the message and contains the elements that you added to it.
For subsequent outbound messages:
For a web client, the SecurityOut
property is left unchanged, so that subsequent outbound messages from this instance include the security header you added. If this is undesirable, set the SecurityOut
property to null.
For a web service, the SecurityOut
property is automatically set to null after the first outbound SOAP message.
When you add multiple security elements to the header, it is important to add security header elements in the appropriate order. When you perform both encryption and signing of the same message element, this is especially important: that is, add them in the same order that you perform the encryption and signing operations.
The order of header elements indicates the order in which the processing of the message occurred. The WS-Security 1.1 specification says this:
As elements are added to a <wsse:Security> header block, they SHOULD be prepended to
the existing elements. As such, the <wsse:Security> header block represents the signing and
encryption steps the message producer took to create the message. This prepending rule
ensures that the receiving application can process sub-elements in the order they appear in the
<wsse:Security> header block, because there will be no forward dependency among the sub-
As you add header elements, Caché prepends each element to the previously added elements, with the following exceptions:
When you perform both encryption and signing of the same message element, it is especially important to add security header elements in the appropriate order: that is, add them in the same order that you perform the encryption and signing operations.