Contact Us 1-800-596-4880

Mule Digital Signature Processor

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version.

The Mule Digital Signature Processor adds a digital signature to a message payload, or part of the payload, to prove the identity of the message’s sender. Mule can also verify a signature on a message it receives to confirm the authenticity of the message’s sender. To sign or verify the signature of a message, Mule uses one of the following two Digital Signature Strategies:

  1. JCE Signer

  2. XML Signer

As the sender of a message, use a digital signature when you want to advise the message’s receiver that you are a legitimate sender and that you vouch for all, or part, of its contents.

Use the table below to determine which type of digital signature strategy best suits your security needs.

Digital Signature Strategy Characteristics

JCE Signer

• sign a message payload, or part of a payload, using a key and algorithm

XML Signer

• sign a message payload, or part of a payload, using a keystore
• apply attributes to specify the type of algorithm, and type of signature

As the receiver of a message, use the digital signature feature when you need to verify the identity and confirm the legitimacy of its sender.

Adding a Digital JCE Signature to a Message

As Mule’s default signature strategy, the Java Cryptology Extension (JCE) signer, part of the Java Cryptography Architecture (JCA), enriches a message payload with a digital signature.

This topic introduces the idea of Global Elements; if you are unfamiliar with this functionality, access Global Elements to learn more before proceeding.

At minimum, you must explicitly define the following:

  • a Global Signature element

  • a Signature message processor in your Mule flow

Global vs. Local

To apply a digital signature to a message in Mule, you must use two elements, as described above: a Signature message processor in a Mule flow, and a Global Signature element to which the Signature message processor refers for configuration information.

The example below uses a Global Signature element to apply most of the attribute configurations of the digital signature, the three minimum configurations Mule needs to apply a digital signature: default signer, algorithm, and key. The example then uses a local Signature message processor within a Mule flow to reference the Global Signature element.

However, you can reverse the configuration so that the local Signature message processor contains most of the configuration information – including the minimum configurations – and the Global Signature element contains only the Default Signer type: JCE_SIGNER.

Either configuration is fine, though you may wish to use the former if you intend to apply the same type of signature to messages in several flows in your Mule application. In such a case, a global element saves you from coding the same configurations multiple times in one application.

Note that any configuration entered in the local message processor will further specify or override any configuration in the global element and will cause the application to refer only to the configurations in the global element which do not conflict with local configurations. For example, you could first configure a global element properties for Algorithm, Keystore Path, and Keystore Password and apply this global element multiple times within one application. Then, within each message processor that references this global element, you can configure the local attributes for Key and Key Password to specify which key within the keystore should be referenced for each specific message processor. You can also select a different Algorithm than the one you configured in the global element – this locally configured algorithm will override the algorithm specified in the global element for this message processor only.

You can define the required configurations in either the Global Signature element or the local Signature message processor. Note, however, that you can only instruct Mule to use a key in a keystore via the configurations in the Global Signature element.

The following procedure describes how to apply JCE digital signatures to messages processed in a Mule flow.

Studio Visual Editor

  1. Add a global Signature message processor to your application, applying a unique Name for the element and keeping the default value, JCE_SIGNER, in the Default Signer field (see image below, left).

  2. Click the JceSigner tab (see image below, right), then configure the message processor’s attributes according to the table below. Note that while none of the attributes on the Jce Signer tab are required, this global element is the only place you can define a Keystore Path and Keystore Password for your Signature element.

    global_JCE_Signer_both
    Field Req’d Value

    Reference or expression

    If selected, in the Jce Signer Reference, use an expression to reference attributes you have defined elsewhere in the XML configuration of your applications, or to reference the configurations defined in a bean.

    Define attributes

    If selected, enter values in the following five fields.

    Algorithm

    Algorithm to encrypt the key, not required if using a keystore. Refer to Appendix for list of available algorithms.

    Key

    Unique key that encrypts and decrypts message; or, if using keystore, the name of the specific key within the keystore.

    Keystore Path

    Indicates the location (i.e. filepath) of the keystore file, required if using keystore.

    Keystore Password

    Password to access the keystore, required if using keystore.

    Key Password

    Password to read the key within the keystore; required only if the specific keys within the keystore have their own passwords.

    If you are using a Keystore, you must also define a Key to specify which key within the keystore the application should invoke. The key can be configured either on the Global Element Properties window or in the Pattern Properties window.

    + * If configured in the Global Element Properties window, that key will be invoked for all message processors which refer to that global element — unless there is a different key specified in the local Pattern Properties window for that building block, because local configuration overrides global configurations. * If configured in the local Pattern Properties window, that key will be invoked only for that message processor, so any other message processors in the same flow that also refer to that global element would need a key configured in their Pattern Properties windows.

  3. Add a Signature message processor to your flow.

  4. Configure the message processor’s fields according to the table below.

    signature+1
    Field Req’d Value

    Display Name

    x

    A unique name for your message processor.

    *Connector Configuration
    *

    x

    Use the name of the global element you created above.

    Operation

    x

    Sign

    Input Reference

    Identify the part of the message payload to which you want to apply the signature. This value must be in byte array format. By default, Mule signs the entire message payload.

    Variable

    Indicate the location in which Mule should store the signature which enriches the message.

    Reference or expression

    If selected, in the Jce Signer Reference, use an expression to reference attributes you have defined elsewhere in the XML configuration of your applications, or to reference the configurations defined in a bean.

    Define attributes

    If selected, enter values in the following three fields.

    Algorithm

    Define an algorithm to encrypt the key, not required if using keystore.

    Key

    x

    Unique key that encrypts and decrypts message; or, if using keystore, the name of the specific key within the keystore.

    Key Password

    Password to read the key within the keystore; required only if the specific keys within the keystore have their own passwords.

XML Editor or Standalone

  1. Add a global signature:config element to your application, set above all the flows in your application.

  2. Configure the global element’s attributes and child element according to the table below. Note that while none of the attributes on the Jce Signer tab are required, this global element is the only place you can define a keystorePath and keystorePassword for your Signature element.

    <signature:config name="Global_JCE_Signature" doc:name="Signature">
            <signature:jce-signer-config algorithm="HmacMD5" key="1@s9bl&gt;1LOJ94z4"/>
    </signature:config>
    Attribute Req’d Value

    name

    x

    A unique name for your global element.

    doc:name

    A display name for the element in Studio’s Visual Editor. Not applicable for Standalone.

    Child Element Req’d

    signature:jce-signer-config

    Child Element Attribute Req’d Value

    algorithm

    Define an algorithm to encrypt the key, not required if using keystore. Refer to Appendix for list of available algorithms.

    key

    Unique key that encrypts and decrypts message; or, if using keystore, the name of the specific key within the keystore.

    keystorePath

    Indicates the location (i.e. filepath) of the keystore file, required if using keystore.

    keystorePassword

    Password to access the keystore, required if using keystore.

    keyPassword

    Password to read the key within the keystore; required only if the specific keys within the keystore have their own passwords.

    If you are using a Keystore, you must also define a Key to specify which key within the keystore the application should invoke. The key can be configured either the global element window or in the element in your flow.

    • If configured in the global element, that key will be invoked for all message processors which refer to that global element — unless there is a different key specified in the local configuration for that element, because local configuration overrides global configurations.

    • If configured in the local element, that key will be invoked only for that element, so any other elements in the same flow that also refer to that global element would need a key configured in their local configurtions.

  3. Add a signature:sign element to your flow.

  4. Configure the element’s attributes and child element according to the tables below.

    <signature:sign config-ref="Signature" doc:name="Signature">
      <signature:jce-signer algorithm="HmacMD5" key="testing" keyPassword="passtestng"/>
    </signature:sign>
    Attribute Req’d Value

    config-ref

    x

    Use the name of the global element you created above.

    doc:name

    A display name for the element in Studio’s Visual Editor. Not applicable for Standalone.

    input-ref

    Identify the part of the message payload to which you want to apply the signature. This value must be in byte array format. By default, Mule signs the entire message payload.

    variable

    Indicate the location in which Mule should store the signature which enriches the message.

Child Element Req’d

signature:jce-signer

x

Child Element Attribute Req’d Value

algorithm

Define an algorithm to encrypt the key, not required if using keystore.

key

x

Unique key that encrypts and decrypts message; or, if using keystore, the name of the specific key within the keystore.

keyPassword

Password to read the key within the keystore; required only if the specific keys within the keystore have their own passwords.

Adding a Digital XML Signature to a Message

The XML signer enriches a message payload with a digital signature.

This topic introduces the idea of Global Elements; if you are unfamiliar with this functionality, access Global Elements to learn more before proceeding.

At minimum, you must explicitly define the following:

  • a Global Signature element

  • a Signature message processor in your Mule flow

You can define the required configurations in either the Global Signature element or the local Signature message processor. Refer to the Global vs. Local tip above for more information on how to apply configurations. Note, however, that you can only instruct Mule to use a key in a keystore via the configurations in the Global Signature element.

The following procedure describes how to apply XML digital signatures to messages processed in a Mule flow.

Studio Visual Editor

  1. Add a global Signature message processor to your application, applying a unique Name for the element and change the default value, JCE_SIGNER, in the Default Signer field to XML_SIGNER (see image below, left).

  2. Click the XML Signer tab (see image below, right), then configure the message processor’s attributes according to the table below. Note that while the Keystore Path and Keystore Password are optional, this global element is the only place you can define a them for your Signature element.

    global_XML_Signer_Both
    Field Req’d Value

    Name

    x

    A unique name for your global element.

    Default Signer

    x

    XML_SIGNER

    Reference or Expression

    If selected, in the Jce Signer Reference, use an expression to reference attributes you have defined elsewhere in the XML configuration of your applications, or to reference the configurations defined in a bean.

    Define Attributes

    If selected, enter values in the following nine fields.

    Digest Method Algorithm

    x

    The algorithm Mule uses to encrypt the digest:
    RIPEMD160
    SHA1
    SHA256 (Default)
    SHA512

    Canonicalization Algorithm

    x

    The algorithm Mule uses for XML canonicalization:
    EXCLUSIVE (Default)
    EXCLUSIVE WITH COMMENTS
    INCLUSIVE
    INCLUSIVE WITH COMMENTS

    Signature Method Algorithm

    x

    The algorithm Mule uses to protect the message from tampering:
    RSA_SHA1 (Default)
    DSA_SHA1
    HMAC_SHA1

    Signature Type

    x

    Defines whether the signature applies to:
    • data outside its containing document (DETACHED)
    • a part of its containing document (ENVELOPED) (Default)
    • data it contains within itself (ENVELOPING)

    Reference Uri

    External URI reference for messages with a Detached signature type.

    Key

    Unique key that encrypts and decrypts message; or, if using keystore, the name of the specific key within the keystore.

    Keystore Path

    Indicates the location (i.e. filepath) of the keystore file, required if using keystore.

    Keystore Password

    Defines the password to read the key stored in the keystore, required if using keystore.

    Key Password

    Password to read the key within the keystore; required only if the specific keys within the keystore have their own passwords.

    If you are using a Keystore, you must also define a Key to specify which key within the keystore the application should invoke. The key can be configured either on the Global Element Properties window or in the Pattern Properties window.

    + * If configured in the Global Element Properties window, that key will be invoked for all building blocks which refer to that global element — unless there is a different key specified in the local Pattern Properties window for that building block, because local configuration overrides global configurations. * If configured in the local Pattern Properties window, that key will be invoked only for that building block, so any other building blocks in the same flow that also refer to that global element would need a key configured in their Pattern Properties windows.

  3. Add a Signature message processor to your flow.

  4. Configure the message processor’s fields according to the table below.

    signature+1
    Field Req’d Value

    Display Name

    x

    A unique name for your message processor.

    Config Reference

    x

    Use the name of the global element you created above.

    Operation

    x

    Sign xml

    Input

    Identify the part of the message payload to which you want to apply the signature. This value must be in byte array format. By default, Mule signs the entire message payload.

    Key

    x

    Unique key that encrypts and decrypts message; or, if using keystore, the name of the specific key within the keystore.

    Key Password

    Password to read the key within the keystore; required only if the specific keys within the keystore have their own passwords.

    Reference Uri

    External URI reference for messages with a Detached signature type.

    Canonicalization Algorithm

    The algorithm Mule uses for XML canonicalization:
    EXCLUSIVE
    EXCLUSIVE WITH COMMENTS
    INCLUSIVE
    INCLUSIVE WITH COMMENTS

    Digest Method Algorithm

    The algorithm Mule uses to encrypt the digest:
    RIPEMD160
    SHA1
    SHA256
    SHA512

    Signature Method Algorithm

    The algorithm Mule uses to protect the message from tampering:
    RSA_SHA1
    DSA_SHA1
    HMAC_SHA1

    Signature Type

    Defines whether the signature applies to:
    • data outside its containing document (DETACHED)
    • a part of its containing document (ENVELOPED)
    • data it contains within itself (ENVELOPING)

XML Editor or Standalone

  1. Add a global signature:config element to your application, set above all the flows in your application.

  2. Configure the global element’s attributes and child element according to the table below. Note that while the keystorePath and keystorePassword are optional, this global element is the only place you can define a them for your Signature element.

    <signature:config name="Global_XML_Signature" doc:name="Signature" defaultSigner="XML_SIGNER">
        <signature:xml-signer-config digestMethodAlgorithm="SHA512" key="1@s9bl&gt;1LOJ94z4"/>
    </signature:config>
    Attribute Req’d Value

    name

    x

    A unique name for your global element.

    defaultSigner

    x

    XML_SIGNER

    doc:name

    A display name for the element in Studio’s Visual Editor. Not applicable for Standalone.

    Child Element Req’d

    signature:xml-signer-config

    x

    Child Element Attributes Req’d Value

    digestMethodAlgorithm

    x

    The algorithm Mule uses to encrypt the digest:
    RIPEMD160
    SHA1
    SHA256
    SHA512

    canonicalizationAlgorithm

    x

    The algorithm Mule uses for XML canonicalization:
    EXCLUSIVE
    EXCLUSIVE WITH COMMENTS
    INCLUSIVE
    INCLUSIVE WITH COMMENTS

    signatureMethodAlgorithm

    x

    The algorithm Mule uses to protect the message from tampering:
    RSA_SHA1
    DSA_SHA1
    HMAC_SHA1

    signatureType

    x

    Defines whether the signature applies to:
    • data outside its containing document (DETACHED)
    • a part of its containing document (ENVELOPED)
    • data it contains within itself (ENVELOPING)

    referenceUri

    External URI reference for messages with a Detached signature type.

    key

    Unique key that encrypts and decrypts message; or, if using keystore, the name of the specific key within the keystore.

    keystorePath

    Indicates the location (i.e. filepath) of the keystore file, required if using keystore.

    keystorePassword

    Defines the password to read the key stored in the keystore, required if using keystore.

    keyPassword

    Password to read the key within the keystore; required only if the specific keys within the keystore have their own passwords.

  3. Add a signature:sign element to your flow.

  4. Configure the element’s attributes according to the tables below.

    <signature:sign-xml config-ref="Global_XML_Signature" doc:name="XML_Signature"/>
    Attribute Req’d Value

    config-ref

    x

    Use the name of the global element you created above.

    doc:name

    A display name for the element in Studio’s Visual Editor. Not applicable for Standalone.

    canonicalizationAlgorithm

    The algorithm Mule uses for XML canonicalization:
    EXCLUSIVE
    EXCLUSIVE WITH COMMENTS
    INCLUSIVE
    INCLUSIVE WITH COMMENTS

    digestMethodAlgorithm

    The algorithm Mule uses to encrypt the digest:
    RIPEMD160
    SHA1
    SHA256
    SHA512

    input

    Identify the part of the message payload to which you want to apply the signature. This value must be in byte array format. By default, Mule signs the entire message payload.

    key

    x

    Unique key that encrypts and decrypts message; or, if using keystore, the name of the specific key within the keystore.

    keyPassword

    Password to read the key within the keystore; required only if the specific keys within the keystore have their own passwords.

    referenceUri

    External URI reference for messages with a Detached signature type.

    signatureMethodAlgorithm

    The algorithm Mule uses to protect the message from tampering:
    RSA_SHA1
    DSA_SHA1
    HMAC_SHA1

    signatureType

    Defines whether the signature applies to:
    • data outside its containing document (DETACHED)
    • a part of its containing document (ENVELOPED)
    • data it contains within itself (ENVELOPING)

Example of a Signed Payload

What follows are examples of a message payloads: one without a digital signature (below, top), and one with an XML digital signature (below, bottom).

View the XML Without Digital Signature
<PurchaseOrder>
 <Item number="130046593231">
  <Description>Video Game</Description>
  <Price>10.29</Price>
 </Item>
 <Buyer id="8492340">
  <Name>My Name</Name>
  <Address>
   <Street>One Network Drive</Street>
   <Town>Burlington</Town>
   <State>MA</State>
   <Country>United States</Country>
   <PostalCode>01803</PostalCode>
  </Address>
 </Buyer>
</PurchaseOrder>
View the XML With Digital Signature
<PurchaseOrder>
 <Item number="130046593231">
  <Description>Video Game</Description>
  <Price>10.29</Price>
 </Item>
 <Buyer id="8492340">
  <Name>My Name</Name>
  <Address>
   <Street>One Network Drive</Street>
   <Town>Burlington</Town>
   <State>MA</State>
   <Country>United States</Country>
   <PostalCode>01803</PostalCode>
  </Address>
 </Buyer>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><Reference URI=""><Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/></Transforms><DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/><DigestValue>tkrLEansVMTKqAOuW6b8Dx+OUNWk9bVpW6RFvfuEmM8=</DigestValue></Reference></SignedInfo><SignatureValue>PeeHVw+XvZkkhhPlEopRp1PBDfTcR9U2IBimTTo1gOMF5cWq1tFqZ0B4ScNBiZVtd0yS4j06xl3W
B2Q87oobwA==</SignatureValue><KeyInfo><KeyValue><RSAKeyValue><Modulus>i8OP+VX/EORWwHiHiqLmMgpXz4IubPv2y+gHdiSCUzKoFfUYD6wFGBwi6vVmRSrmNbNZvZ9DFvST
PZJEyUhn5w==</Modulus><Exponent>AQAB</Exponent></RSAKeyValue></KeyValue></KeyInfo></Signature></PurchaseOrder>

Signing Part of a Message Payload

By default, Mule signs the entire message payload when you apply a signature. However, you can use a Mule Expression to sign a specific part of a message payload rather than the whole payload. Enter a Mule expression in the Input Reference field of a JCE or XML Signature message processor to define the specific part(s) of the payload you wish to sign.

Applying a Signature Using MEL

As described above, to apply a digital signature to a message in Mule, you normally need two ingredients:

  • A Global Signature element which defines all, or some, of the signature attributes

  • A Signature message processor in a Mule flow which defines all, or some, of the signature attributes

However, you can also add a signature to a message without adding a Signature message processor to a Mule flow. To do so, you need:

  • A Global Signature element which defines all of the signature attributes

  • A Mule expression appended to a message processor as message attribute, which references the Global Signature element to apply a signature to the message

To reference a Global Signature element via Mule expression in another element, you must first set the Global Signature element’s Enable Language attribute to true (below, left), then apply all the Global Signature attributes (below, right).

Studio Visual Editor

enable_language3

XML Editor or Standalone

<signature:config name="hmacPlain" enableLanguage="true">
        <signature:jce-signer-config algorithm="HmacMD5" key="JLfl5sER3kt4oVkzP2d39UQrUxrEK63LjmXAO45b6cU="/>
</signature:config>

Then, add a message attribute to an element in your flow, a Logger, for example, to apply a digital signature according to the configurations in the Global Signature element.

Studio Visual Editor

logger1

XML Editor or Standalone

<flow name="testHmacPlain">
        <logger level="ERROR" message="##"/>
 </flow>

Verifying a Digital Signature

In addition to signing a message, Mule also uses a Signature message processor to verify the identity of a message’s sender as legitimate. Where Mule discovers an invalid signature, it discards the message, processing it no further.

Mule verifies the signature on the message payload according to the configurations of any of the optional attributes if explicitly defined (see lists above for JCE- and XML-specific attributes).

This topic introduces the idea of Global Elements; if you are unfamiliar with this functionality, access Global Elements to learn more before proceeding.

To verify JCE or XML signatures on messages in a Mule flow, you must, at minimum, create:

  • A Global Signature element

  • A Signature message processor in your Mule flow

The following procedure describes how to verify digital signatures on messages a Mule flow receives.

  1. In your Mule flow, add a Signature message processor early in your flow in Studio to verify signatures on messages that arrive to be processed.

  2. In the Operations field, select Verify Signature. Alternatively, add a Signature element to your flow, configured to verify signatures (see code, below).

    <signature:verify-signature config-ref="" doc:name="Signature"/>
  3. Use the Using field (or using attribute in XML) to indicate the type of signature:` JCE_SIGNER` or XML_SIGNER.

  4. Optionally, enter a Mule expression in the Input Reference field to indicate the part of the message payload to which the signature applies. In other words, a signature may apply to only part of the message payload.

  5. In the Expected Signature field, enter a Mule expression that Mule can use to compare and verify that the signature on a message it received is authentic.

  6. Configure any other attributes of the local Signature message processor. Refer to the JCE Signer and XML Signer sections above for attribute configuration details. Also, refer to the Global vs. Local tip to decide which attributes to configure locally, on the Signature message processor, and which attributes to configure in the Global Signature element.

  7. Configure any other attributes of a Global Signature element. Again, refer to the JCE Signer and XML Signer sections above for attribute configuration details.

  8. Configure the Signature message processor to reference the Global Signature element.

    <signature:config name="Signature"  enableLanguage="true" doc:name="Signature">
        <signature:jce-signer-config algorithm="HmacMD5" key="JLfl5sER3kt4oVkzP2d39UQrUxrEK63LjmXAO45b6cU="/>
    </signature:config>
    <http:listener-config name="HttpListenerConfiguration" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
    
     <flow name="Get_CC_information" doc:name="Get_CC_information">
            <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP Connector"/>
            <signature:verify-signature config-ref="Signature" input-ref="#[message.inboundProperties.'http.query.params'.user]" expectedSignature="#[message.inboundProperties.'http.query.params'.token.]" doc:name="Verify User Signature" doc:description="Verify if the Signature is correct, so we can validate the User"/>
            <set-payload value="#[new String(&quot;&lt;user&gt;&lt;name&gt;Royal Bank of Canada&lt;/name&gt;&lt;id&gt;Royal_Bank_Of_Canada&lt;/id&gt;&lt;cc&gt;&lt;company&gt;Visa&lt;/company&gt;&lt;number&gt;1234567890&lt;/number&gt;&lt;secret&gt;123&lt;/secret&gt;&lt;/cc&gt;&lt;/user&gt;&quot;)]" doc:name="Set Payload"/>
            <encryption:encrypt config-ref="plainXml" doc:name="Encrypt the XML (only th CC Info)" using="XML_ENCRYPTER" input-ref="#[payload.toString()]"/>
      </flow>

Next Steps

Examine the Anypoint Enterprise Security Example Application which illustrates how to verify the digital signature of a message.

Appendix

JCE Signer Available Algorithms

HmacMD5

HmacSHA1

HmacSHA256

HmacSHA384

HmacSHA512

MD2WithRSAEncryption

MD4WithRSAEncryption

MD5WithRSAEncryption

RIPEMD128WithRSAEncryption

RIPEMD160WithRSAEncryption

RIPEMD256WithRSAEncryption

SHA1WithRSAEncryption

SHA224WithRSAEncryption

SHA256WithRSAEncryption