Require Encryption
This action requires that a request's XML element (which is represented by an XPath expression) 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 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 Administering webMethods Mediator.
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 will appear to Mediator to be 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 will 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 determines the public key alias as follows:
If
Mediator can access the X.509 certificate of the client (based on the incoming request signature), it will use “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 will look 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 will 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
If the above steps all fail, then
Mediator will use either the WS-Security username token or the HTTP Basic-Auth username value. There should be a public key entry with the same name as the identified username.
Input Parameters
Namespace | String. Mandatory. Namespace of the element required to be encrypted. Note: | Enter the namespace prefix in the following format: xmlns:<prefix-name> . For example: xmlns:soapenv. |
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. Mandatory. An XPath expression that represents the XML element that is required to be encrypted. See the sample below. |
Let's take a look at an example. For the following SOAP message:
The XPath expression appears as follows:
/soap:Envelope/soap:Body
