Securing Caché Web Services
Validating and Decrypting Inbound Messages
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter describes how to validate security elements in messages received by a Caché web service or web client (and automatically decrypt any encrypted content). It discusses the following topics:

Overview
Caché web services and web clients can validate the WS-Security header element for inbound SOAP messages, as well as automatically decrypt the inbound messages.
Caché web services and web clients can also process a signed SAML assertion token and validate its signature. However, it is the responsibility of your application to validate the details of the SAML assertion.
All the preceding activities are automatic if you use a security policy.
In all scenarios, Caché uses its collection of root authority certificates; see the chapter Setup and Other Common Activities.”
Validating WS-Security Headers
To validate the WS-Security header elements contained in any inbound SOAP messages, do the following:
  1. In the web service or the web client, set the SECURITYIN parameter. Use one of the following values:
    In both cases, the web service or the web client validates the <Timestamp>, <UsernameToken>, <BinarySecurityToken>, <Signature>, and <EncryptedKey> header elements. It also validates the WS-Security signature in the SAML assertion in the header, if any. The message is also decrypted, if appropriate.
    If validation fails, an error is returned.
    There are two additional possible values for SECURITYIN parameter, for use in testing and troubleshooting:
For an example, see Message Encryption Example,” earlier in this book.
Note:
The SECURITYIN parameter is ignored if there is a security policy in an associated (and compiled) configuration class.
Accessing a SAML Assertion in the WS-Security Header
If the WS-Security header element includes an <Assertion> element, a Caché web service or web client automatically validates the signature of that SAML assertion, if it is signed.
Caché does not, however, automatically validate the assertion. Your code should retrieve the assertion and validate it.
To access the SAML assertion, find the <Assertion> element of the security header element. To do so, use the FindElement() method of the SecurityIn property of the service or client, as follows:
 Set assertion=..SecurityIn.FindElement("Assertion") 
This returns an instance of %SAML.Assertion. Examine properties of this object as needed.
CSP Authentication and WS-Security
It is useful to understand that with a Caché web service, two separate mechanisms are in effect: the CSP engine and the web service.
These mechanisms work together as follows:
  1. Upon receiving a message, a Caché web service checks for the presence of a header element called <Security>, without examining the contents of that element.
  2. If no <Security> header element is present and if the SECURITYIN parameter equals REQUIRE, the web service issues a fault and quits.
  3. If the <Security> header element contains a <UsernameToken> element:
Note:
The SECURITYIN parameter is ignored if there is a security policy in an associated (and compiled) configuration class.
Retrieving a Security Header Element
In some cases, you might want to add custom processing for WS-Security header elements. To do this, use the SecurityIn property of the web service or client. If a service or client receives WS-Security header elements, this property is an instance of %SOAP.Security.Header that contains the header elements. For example:
 Set secheader=myservice.SecurityIn
Then use one of the following methods of that instance to retrieve a header element:
FindByEncryptedKeySHA1()
method FindByEncryptedKeySHA1(encryptedKeySHA1 As %Binary) as %SOAP.Security.Element
Returns the key from an <EncryptedKey> element that corresponds to the given EncryptedKeySHA1 argument. Or returns the empty string if there is no match.
FindElement()
method FindElement(type As %String, ByRef pos As %String) as %SOAP.Security.Element
Returns the first security element of the specified type after position pos. If there is no match, the method returns the empty string (and returns pos as 0).
For type, specify "Timestamp", "BinarySecurityToken", "UsernameToken", "Signature", or "EncryptedKey".
FindLastElement()
method FindLastElement(type As %String, ByRef pos As %String) as %SOAP.Security.Element
Returns the last security element of the specified type. If there is no match, the method returns the empty string (and returns pos as 0).
For information on type, see the entry for FindElement().
All these methods return either an instance of %SOAP.Security.Element or an instance of one the following subclasses, depending upon the element type:
Element Type Subclass Used
"Timestamp" %SOAP.Security.Timestamp
"BinarySecurityToken" %SOAP.Security.BinarySecurityToken
"UsernameToken" %SOAP.Security.UsernameToken
"Signature" %XML.Security.Signature
For details, see the class reference.
Checking the Signature Confirmation
The WS-Security 1.1 <SignatureConfirmation> feature enables a web client to ensure that a received SOAP message was generated in response to the original request sent by the web client. The client request is typically signed but does not have to be. In this mechanism, the web service adds a <SignatureConfirmation>element to the security header element, and the web client can check that <SignatureConfirmation> element.
For a web client, to validate the <SignatureConfirmation> elements in a response received from a web service, call the WSCheckSignatureConfirmation() method of the web client. This method returns true if the <SignatureConfirmation> elements are valid, or false otherwise.
For information on adding signature confirmation to messages sent by a web service, see Adding Signature Confirmation,” earlier in this book.