Adding Security Elements Manually
This topic describes generally how to add security elements manually to messages sent by InterSystems IRIS web services and InterSystems IRIS web clients.
The following topics provide details on specific security tasks.
Adding Security Header Elements
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() or CreateX509(), depending on the class. The instance represents one of the WS-Security header elements such as <Username> or <EncryptedKey>.
-
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() method.
-
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.
-
Order of Header Elements
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- elements.
As you add header elements, InterSystems IRIS prepends each element to the previously added elements, with the following exceptions:
-
If you include the <Timestamp> element, it is forced to be first.
-
If you include any <BinarySecurityToken> elements, they are forced to follow the <Timestamp> element (if included) or are forced to be first.
-
When you use AddSecurityElement() to add an encrypted version of a security header element, you specify a second argument to force the inserted <EncryptedData> element to follow the associated <EncryptedKey>.
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.