Java
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docs Release 1.5 Feb 17, 2018
src Add common base class Aug 17, 2018
.gitignore first commit Feb 6, 2017
.travis.yml Drop java 7 Oct 29, 2017
LICENSE.txt Create LICENSE.txt Mar 19, 2017
README.md Modify docs Jun 22, 2018
pom.xml ISSUE-14: Add the possibility to sign based on an elementID Jun 14, 2018

README.md

jmeter-wssecurity travis

Overview

Apache JMeter plugin for signing, encrypting and decrypting SOAP messages (WS-Security).

The plugin provides

  • Pre-Processors for adding digital signature or encryption to a sampler's payload (based on a certificate from a given keystore),
  • a Pre-Processor for adding a Username Token to a sampler's payload,
  • a Pre-Processor for adding a Timestamp to a sampler's payload,
  • a Post-Processor for decrypting a sampler's response.

Supported are HTTP Request, JMS Publisher and JMS Point-to-Point samplers, as well as third party samplers that expose the payload via a pair of getter/setter methods.

Installation

Via PluginsManager

Under tab "Available Plugins", select "WS Security for SOAP", then click "Apply Changes and Restart JMeter".

Via Package from JMeter-Plugins.org

Extract the zip package into JMeter's lib directory, then restart JMeter.

Via Manual Download

  1. Copy the jmeter-wssecurity jar file into JMeter's lib/ext directory.
  2. Copy the following dependencies into JMeter's lib directory:
  3. Restart JMeter.

Usage

From the context menu, select "Add" / "Pre Processors" / "SOAP Message Signer", "SOAP Message Encrypter" or "SOAP Message UsernameToken".

The message to be signed or encrypted must be a valid SOAP message and must be in one of the following locations:

Note that the plugin does not assist with composing the message nor does it do any XML schema validation. Only the WS-Security header element will be inserted or modified. It is recommended to exclude the WS-Security header from the SOAP request.

Users familiar with SoapUI will find similarities to the outgoing WS-Security configuration.

SOAP Message Signer

SOAP Message Signer

SOAP Message Encrypter

SOAP Message Encrypter

SOAP Message Username Token

SOAP Message Username Token

SOAP Message Decrypter

SOAP Message Decrypter

Configuration

Pre-Processors

The dropdown fields are initialized with WSS default values, and allow the customization of most signature and encryption settings, depending on what the endpoint's WSDL defines.

The "Parts to Sign"/"Parts to Encrypt" are empty by default, however, that results in the SOAP Body content to be signed or encrypted.

Suppose the Timestamp element was to be included in the signature or encryption in addition to the Body element, both would have to be listed as follows:

ID Name Namespace Encode
Body http://schemas.xmlsoap.org/soap/envelope/
Timestamp http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd

If there are multiple XML elements with the same name and namespace, the element's ID attribute can be used to determine which element is to be signed/encrypted. If the ID is specified, the Name and Namespace are not necessary and will not be used.

Example:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <element ID="e1">this should be encrypted</element>
        <element ID="e2">this is not to be encrypted</element>
        <element>another one</element>
	</soap:Body>
</soap:Envelope>
ID Name Namespace Encode
e1

Encode is only relevant for encryption and can be one of the following:

  • "Element" (default): The entire XML element is encrypted.
  • "Content": Only child nodes of the XML element are encrypted (i.e. the element name and its attributes will remain in clear text).
  • "Header": Encloses the XML element in an EncryptedHeader element ("http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd"), but only if it is an immediate child node of the SOAP Header.

Post-Processor

Any WS-Security related exception encountered by the SOAP Message Decrypter while trying to decrypt a response message will cause the sampler to fail and will create an assertion result, effectively behaving like an implicit assertion.

If this behaviour is not desired, it may be turned off via setting the JMeter property jmeter.wssecurity.failSamplerOnWSSException=false.

Support for 3rd party samplers

Samplers that are not JMeter core functionality, such as JMeter-Plugins, can also be used if they provide a getter/setter pair to access a String property that contains the sampler's payload that is to be signed or encrypted.

In that case, the JMeter property jmeter.wssecurity.samplerPayloadAccessors can be used to specify the class and member name (without the get/set prefix) which the Pre-Processor will access at run time via Reflection.

Suppose a sampler like the following:

package some.package;
public class SomeSampler extends AbstractSampler {
	public String getPayload() 
	// ...
	public void setPayload(String content)
	// ...
}

Then the JMeter property should be set like so: jmeter.wssecurity.samplerPayloadAccessors=some.package.SomeSampler.payload

More than one of these can be comma separated (if really required).

Troubleshooting

The signed or encrypted message payload can be inspected via "View Results Tree".

To avoid common problems, make sure that:

  • the Keystore contains an entry for the specified certificate alias,
  • the certificate and signature/encryption algorithms match,
  • the SOAP message is correctly formed and can be parsed,
  • Unlimited Strength JCE is installed to support all key lengths, etc.

It may be useful to increase the logging level in order to investigate any keystore or encryption related issues, for example by adding --loglevel=org.apache.wss4j=DEBUG to the JMeter command line.

It may also be helpful to inspect server side logs, especially for HTTP 500 type responses, unspecific SOAP Fault messages etc.