README.md

jmeter-wssecurity

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),
• Pre-Processors for adding a Username Token or 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, SMTP and TCP sampler, as well as third party samplers that expose the payload via a JMeter StringProperty or 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

1. Remove wss4j-*.jar and xmlsec-*.jar from JMeter's lib directory (if applicable).
2. Download and extract the zip package into JMeter's lib directory.
3. 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:
   • org.apache.wss4j / wss4j-ws-security-dom
   • org.apache.wss4j / wss4j-ws-security-common
   • org.apache.santuario / xmlsec
3. Make sure to remove older versions of the above dependencies from the JMeter lib directory.
4. Restart JMeter.

Usage

From the context menu, add the appropriate Pre or Post Processor to the test plan scope with the sampler containing the SOAP message.

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

• For HTTP request: Tab "Body Data" (not "Parameters")
• For JMS Point-to-Point: Text area "Content"
• For JMS Publisher: Text area "Text Message..." with "Message source": Textarea (from files is not supported)
• For SMTP Sampler: Text area "Message" ("Send .eml" unchecked)
• For TCP Sampler: Text area "Text to send"

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 and let the plugin generate it.

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

SOAP Message Signer

SOAP Message Encrypter

SOAP Message Username Token

SOAP Message Timestamp

SOAP Message Decrypter

Configuration

Keystore Settings

The keystore file is expected to contain all keys referenced in the SOAP message headers that are required for signing and/or encrypting/decrypting.

The default keystore type is JCEKS (since v1.7, before Java platform default). Other keystore types can be used by defining the JMeter property jmeter.wssecurity.keystoreType (since v1.8), e.g. PKCS12, JKS, JCEKS.

Pre-Processors

The dropdown fields allow for the customization of most signature and encryption settings, depending on what the endpoint's WSDL defines.

⚠️ Not all setting combinations are valid, and JMeter does not enforce a valid combination to be entered. Instead, invalid ones will cause errors to be logged during runtime.

Example: Key Identifier Type "Encrypted Key SHA1" is only valid for symmetric Signature Algorithms (HMAC).

Parts to Sign/Parts to Encrypt

These lists 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 (or attachments, see below) 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

The SOAP Message Decrypter takes a sampler's response data as input, expecting a SOAP message with WS-Security header, and decrypts the payload based on the content of a given keystore. This requires the private key password of the encryption certificate.

Until plugin version 1.6 this password is expected in the field "Private Key Password". As of version 1.7 it needs to be provided in the table Credentials for WSS Processing, along with the alias of the keystore entry.

Note: Due to the way the underlying wss4j library is implemented, any other, not encryption related security tokens in the response message will also be processed, for example signature tokens. Any such processing will fail if key information is not present. For example, should the response message include a symmetric signature token, the SOAP Message Decrypter needs the secret key that was used to generate the token.

The key(s) may be provided in the configured keystore, and the secret key password(s) can be listed in the table Credentials for WSS Processing. Likewise, if a response were to contain a Username Token, the password(s) for the expected username(s) can be listed in that table, so that the Post-Processor is able to validate the token.

Any WS-Security related exception encountered by the SOAP Message Decrypter while trying to decrypt or validate 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 either a JMeter StringProperty or a public String getter/setter to access the sampler's payload with the SOAP message.

In that case, the JMeter property jmeter.wssecurity.samplerPayloadAccessors can be set to specify the class name and property name as in the following examples.

The SMTP Sampler stores the payload in the TestElement property "SMTPSampler.message". So, it would be configured for this plugin via jmeter.wssecurity.samplerPayloadAccessors=org.apache.jmeter.protocol.smtp.sampler.SmtpSampler."SMTPSampler.message". Note the quotes around the property name if it contains a dot.

Alternatively, if there is no such JMeter property, a Bean property can be used (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).

Support for Attachments

SOAP Message Attachments can be digitally secured or validated/decrypted by the plugin. However, the attachment data must be explicitely provided and must match the attachment(s) transmitted by the sampler, i.e. the plugin is unable to automatically access samplers' attachments. To do this, the below lists (Attachments to Sign/Encrypt/Decrypt) have to be filled in with one row for each attachment.

Additionally, for SwA attachments, the special ID cid:Attachments needs to be added to the "Parts to Sign"/"Parts to Encrypt" (without Name or Namespace). The Encode column can be either:

• "Element": The attachment content will be signed/encrypted as well as the MIME headers Content-Description, Content-Disposition, Content-ID, Content-Location, Content-Type.
• "Content" (default): Only the attachment content will be signed/encrypted.

Attachments to Sign

An attachment is identified by its Content-ID (cid:) and consists of a sequence of bytes and (optionally) some headers. The following columns need to be populated accordingly:

• Content-ID: The identifier attribute the attachment will be referenced by in the SOAP message.
• Bytes: Base64-encoded content. This may come from anywhere, e.g. a file or a JMeter variable, and will typically be using some custom code snippet via the __groovy() function, such as ${__groovy(new File('secret.xml').bytes.encodeBase64())}
• Headers: Newline-separated headers. Note: JMeter GUI fields do not allow newlines. Use ${__char(13)}.

Attachments to Encrypt

The Content-ID, Bytes and Headers columns have the same semantics as above.

After encrypting an attachment, the plugin can make the encrypted data available to the sampler for transmission. This can be done is a few different ways. The following columns determine how the plugin stores the output:

• Output Mode: Defines how the encrypted attachment will be handed over to the sampler, and can be one of the following:
  • "File": Store encrypted bytes in a file (name and path as per "Output Destination" column)
  • "Variable": Assign encrypted bytes to JMeter object variable of type byte[] (variable name as per "Output Destination" column)
  • "Context": Store encrypted bytes in sampler context as object byte[] (context map key as per "Output Destination" column)
  • "Property": Assign encrypted bytes to a sampler ObjectProperty (property name as per "Output Destination" column)
  • "Base64": Assign encrypted bytes to JMeter variable as a base64-encoded String (variable name as per "Output Destination" column)
• Output Destination: Name of the file/variable/property that will hold the encrypted attachment data.

Notes:

• For Encode="Element" (Attachment-Complete as above), headers will be contained within the encrypted data. However, this plugin cannot modify the headers sent by the sampler, so the user needs to ensure that sensitive headers are removed from the attachment part.
• The Content-Type header value may be required for the <xenc:EncryptedData> MimeType attribute as per processing rules, so the user needs to provide it in the Headers column.

Attachments to Decrypt

The plugin can also decrypt response attachments. They need to be listed as follows:

• Content-ID: The Content-ID to tie the attachment back to a reference in the WSS header.
• Bytes: Base64-encoded encrypted data from the sample response. This will most likely be retrieved by some custom code snippet via __groovy() accessing ctx.previousResult.subResults, depending on how the sampler handles response attachments. Example: ${__groovy(ctx.previousResult.subResults[0].responseData.encodeBase64())}

Note: If an attachment is referenced in the response's WSS header but not included in the "Attachments to Decrypt" list, response validation will fail.

The decrypted attachment content (and possibly headers) will be stored as a sub-sample of the main sample. The plugin will try to find a sub-sample that matches the attachment's Content-ID and if a match is found replace the sub-sample, or otherwise create a new sub-sample and add it to the main sample.

The search is done via recursively traversing all sub-samples (depth-first), and looking at either the sub-sample's Content-ID response header or the sub-sample's label. This can be configured via the JMeter property jmeter.wssecurity.findAttachmentsBySampleLabel:

1. If undefined/empty, use the Content-ID response header for matching the attachment's cid.
2. If defined/non-empty, use this regular expression's first capture group for matching the attachment's cid.

Example:

Suppose a sampler generates a main sample with an attachment sub-sample "somecontentid (text/xml)" but does not set the Content-ID header. Using the property value jmeter.wssecurity.findAttachmentsBySampleLabel=(.*) \(.*\) this sub-sample will be identified based on the first matcher group "somecontentid".

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.