Software AG Products 10.11 | Using CentraSite | Runtime Governance | Run-Time Policy Management | Built-In Run-Time Actions Reference (CentraSite Business UI) | Built-in Actions for Run-Time Policies (CentraSite Business UI) | Require Encryption
 
Require Encryption
This action requires that a request's XML element, which is represented by an XPath expression or parts of soap request such as soap body or soap headers be encrypted.
To use this action, the following prerequisites must be met:
1. Configure Integration Server: Set up keystores and truststores in Integration Server, as described in the webMethods Integration Server Administrator’s Guide.
2. Configure Mediator: In the Integration Server Administrator, navigate to Solutions > Mediator > Administration > General and complete the IS Keystore Name, IS Truststore Name, and Alias (signing) fields, as described in the Administering webMethods Mediator guide.
When this action is configured for a proxy API, Mediator provides decryption of incoming requests and encryption of outgoing responses. Mediator can encrypt and decrypt only individual elements in the SOAP message body that are defined by the XPath expressions configured for the action. Mediator requires that requests contain the encrypted elements that match those in the XPath expression. You must encrypt the entire element, not just the data between the element tags. Mediator rejects requests if the element name is not encrypted.
Important:
Do not encrypt the entire SOAP body because a SOAP request without an element appears to Mediator as malformed.
Mediator attempts to encrypt the response elements that match the XPath expressions with those defined for the action. If the response does not have any elements that match the XPath expression, Mediator does not encrypt the response before sending. If the XPath expression resolves a portion of the response message, but Mediator cannot locate a certificate to encrypt the response, then Mediator sends a SOAP fault exception to the client and a Policy Violation event notification to CentraSite.
How Mediator Encrypts Responses
The Require Encryption action encrypts the response back to the client by dynamically setting a public key alias at run time. Mediator uses any one of the following approaches to determine the public key alias:
*If Mediator can access the X.509 certificate of the client based on the incoming request signature, it uses useReqSigCert as the public key alias.
OR
*If an Evaluate action is present in the message flow and it successfully identifies a client, then Mediator looks for a public key alias with that client name in the IS Keystore Name property. The IS Keystore Name property is specified in the Integration Server Administrator, under Solutions > Mediator > Administration > General. This property should be set to an Integration Server keystore that Mediator can use.
For an Evaluate action that allows for anonymous usage, Mediator does not require a client name in order to send encrypted responses. In this case, Mediator can use one of the following to encrypt the response in the following order, depending on what is present in the security element:
*A signing certificate.
*Client name.
*WSS username, SAML token, or X.509 certificate.
*HTTP authorized user.
OR
*If Mediator can determine the current IS user from the request (that is, if an Integration Server WS-Stack determined that Subject is present), then the first principal in that subject is used.
OR
*Mediator uses either the WS-Security username token or the HTTP Basic-Auth username value. Mediator uses this approach only if all the other approaches fail to determine the public key alias. There should be a public key entry with the same name as the identified username.
Input Parameters
Encrypt By
Requires that a request's XML be encrypted.
Value
Description
Element
Select this option to encrypt the entire element, which is represented by an XPath expression.
Part
Select this option to encrypt the part of soap request such as soap body or soap headers.
If Encrypt By Element is selected
Namespace
(String). Namespace of the element required to be signed.
Prefix
Enter the namespace prefix in the following format: xmlns:<prefix-name> . For example, xmlns:soapenv.
URI
The generated XPath element in the policy should look similar to this:
<sp:SignedElements xmlns:sp=
"http://docs.oasis-open.org/ws-sx/
ws-securitypolicy/200702">
<sp:XPath xmlns:soapenv=
"http://schemas.xmlsoap.org/soap/envelope
/">//soapenv:Body</sp:XPath>
</sp:SignedElements>
Element to be Encrypted
(String). An XPath expression that represents the XML element to be signed.
If Encrypt By Part is selected
Encrypt Part
Mark the SOAP Body checkbox to encrypt a part of the soap request.
-<sp:EncryptedParts xmlns:sp=
"http://docs.oasis-open.org/ws-sx/
ws-securitypolicy/200702">
<sp:Body/>
</sp:EncryptedParts>
Encrypt SOAP Headers
Select this option to encrypt the header of the soap request. To specify multiple headers, use the plus button to add rows and minus button to delete rows.
Name
(String). A name for the SOAP header field.
Namespace
(String). Namespace of the soap header required to be signed.

-<sp:SignedParts xmlns:sp=
"http://docs.oasis-open.org
/ws-sx/ws-securitypolicy/200702">
<sp:Body/>
<sp:Header Namespace="http://
www.w3.org/2005/08/addressing
" Name="To"/>
<sp:Header Namespace
="http://www.w3.org/2005/08/
addressing" Name="From"/>
</sp:SignedParts>
For example, for the following SOAP message:
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
</soap:Header>
<soap:Body>
<catalog xmlns="http://www.store.com">
<name>My Book</name>
<author>ABC</author>
<price>100</price>
</catalog>
</soap:Body>
</soap:Envelope>
The XPath expression appears as follows:
/soap:Envelope/soap:Body