Integrity XML-Signature Verification

Contents

Overview

In addition to validating XML Signatures for authentication purposes, the Enterprise Gateway can also use XML Signatures to prove message integrity. By signing an XML message, a client can be sure that any changes made to the message will not go unnoticed by the Enterprise Gateway. Therefore by validating the XML Signature on a message, the Enterprise Gateway can guarantee the integrity of the message.

Before configuring the XML Signature Verification filter, enter a name for this filter in the Name field.

Signature Verification

The following sections are available on the Signature Verification tab:

Signature Location:
Because there may be multiple signatures contained within the message, it is necessary to specify which signature the Enterprise Gateway should use to verify the integrity of the message. The signature can be extracted from one of three places:

  • From the SOAP header
  • Using WS-Security Actors
  • Using XPath

Select the appropriate option from the dropdown.

Find Signing Key
The public key to use to verify the signature can be taken from the following locations:

  • Via KeyInfo in Message:
    Typically, a <KeyInfo> block is used within an XML Signature to reference the key that was used to sign the message. For example, it is common for a <KeyInfo> block to reference a <BinarySecurityToken> that contains the certificate associated with the public key to use to verify the signature.
  • Via Message Attribute:
    The certificate to use to verify the signature can be extracted from a message attribute. For example, it is possible that a previous filter (e.g. a Find Certificate filter) has already located a certificate and populated the certificate message attribute. If you wish to use this certificate to verify the signature, you should specify this attribute in the field provided.
  • Via Certificate in LDAP:
    Clients may not always want to include their public keys in their signatures. In such cases, the public key can be retrieved from a specified LDAP directory. To do this, select the Via Certificate in LDAP radio button and then click on the Add/Edit button. A previously configured LDAP directory can be selected by choosing one from the dropdown.
  • Via Certificate in Store:
    Similarly, you can retrieve a certificate from the Certificate Store by selecting this option and then clicking on the Select button. Check the box next to the certificate that contains the public key that you want to use to verify the signature and click the OK button.

What Must Be Signed

This section defines the content that must be signed in order for a SOAP message to pass the filter. This ensures that the client has signed something meaningful (i.e. part of the SOAP message) as opposed to some arbitrary data that would pass a "blind" signature validation. This further strengthens the integrity verification process.

The nodeset that must be signed can be identified by a combination of XPath expressions, node locations, and/or the contents of a message attribute.

Note that if all attachments are required to be signed, you can check the All attachments checkbox to enforce this.

Advanced

The following advanced configuration options are available:

Signature Confirmation:
If this filter is configured as part of an Initiator circuit, whereby the Enterprise Gateway is acting as the client in a Web Services transaction, you can select Initiator here. This means that the filter will keep a record of the Signature that it has verirified and will check the <SignatureConfirmation> returned by the Recipient.

On the other hand, if the Enterprise Gateway is acting as the Recipient in the transaction, you should select the Recipient option here. In this case, the Enterprise Gateway will return the <SignatureConfirmation> elements in the response to the Initiator.

Default Derived Key Label:
If the Enterprise Gateway consumes a <DerivedKeyToken>, the default value entered here is used to recreate the derived key.

Algorithm Suite:
Select the WS-Security Policy Algorithm Suite that must have been used when signing the message. This check will ensure that the appropriate algorithms were used to sign the message.

Fail if No Signatures to Verify:
Check this option if you want to configure the filter to fail if no XML Signatures are present in the incoming message.

Verify Signature for Authentication Purposes:
The Integrity XML-Signature Verification filter can be used to authenticate an end-user. If the message can be successfully validated, it proves that only the private key associated with the public key used to verify the signature could have been used to sign the message. Because the private key is only accessible to its owner, a successful verification can be used to effectively authenticate the message signer.

Message Attribute Containing DOM:
This field can be configured to verify the response from a SAML PDP. When the Enterprise Gateway receives a response from the SAML PDP, it stores the signature on the response in a message attribute. You can select this attribute from the dropdown in order to verify this signature.