Mule Digital Signature Processor

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:

JCE Signer
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

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 Cryptography 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.

Adding a Digital JCE Signature to a Message (Studio Visual Editor)

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).

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.

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.

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 processor, 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.

Add a Signature message processor to your flow.

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

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.

Field

Req’d

Value

Display Name

A unique name for your message processor.

*Connector Configuration
*

Use the name of the global element you created above.

Operation

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

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

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.

Adding a Digital JCE Signature to a Message (XML Editor or Standalone)

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

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.

Attribute

Req’d

Value

name

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

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.

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 configurations.

Add a signature:sign element to your flow.

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="passtesting"/>
</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.

Attribute

Req’d

Value

config-ref

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

Req’d

signature:jce-signer

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.

Child Element Attribute

Req’d

Value

algorithm

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

key

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 PGP Signature to a Message

The PGP Signer enriches a message payload with a digital signature.

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.

Adding a PGP Signature to a Message (Studio Visual Editor)

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 PGP_SIGNER.

Click the PGP_SIGNER tab, then configure the message processor’s attributes according to the table below.

Option	Description
Reference or Expression	If selected, in the PGP 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, configure the values according to the table below

Option

Description

Reference or Expression

If selected, in the PGP 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, configure the values according to the table below

Option Description Required

Option	Description	Required
Algorithm	The signature Algorithm for PGP signature. Possible values are: SHA256 (Default) SHA384 SHA512 SHA224 MD5 SHA1 RIPEMD160 DOUBLE_SHA TIGER_192 HAVAL_5_160	Yes
Public Key Ring File Name	The path to your public key ring file. This binary key ring holds the message receiver’s public key.	Yes
Secret Key Ring File Name	The path to your secret key ring file. This binary key ring holds the message sender’s private key.	Yes
Secret Alias Id	The 64 bit (16 characters) Key ID of the secret key used to sign the message.	Yes
Secret Passphrase	The passphrase you provided while generating your PGP certificate.	Yes
Output Mode	The PGP encryption output mode. Possible values are: Armor (default) Produces an ASCII-armor signed output. The result of this output is an `.asc` file extension. This PGP armored file is used with email systems that only allow ASCII printable characters. Binary Produces a binary signed output. The result of this output is an `.gpg` file extension.	Yes

Algorithm

The signature Algorithm for PGP signature. Possible values are:

SHA256 (Default)
SHA384
SHA512
SHA224
MD5
SHA1
RIPEMD160
DOUBLE_SHA
TIGER_192
HAVAL_5_160

Yes

Public Key Ring File Name

The path to your public key ring file.
This binary key ring holds the message receiver’s public key.

Yes

Secret Key Ring File Name

The path to your secret key ring file.
This binary key ring holds the message sender’s private key.

Yes

Secret Alias Id

The 64 bit (16 characters) Key ID of the secret key used to sign the message.

Yes

Secret Passphrase

The passphrase you provided while generating your PGP certificate.

Yes

Output Mode

The PGP encryption output mode. Possible values are:

Armor (default)
Produces an ASCII-armor signed output. The result of this output is an .asc file extension.
This PGP armored file is used with email systems that only allow ASCII printable characters.
Binary
Produces a binary signed output. The result of this output is an .gpg file extension.

Yes

Adding a PGP Signature to a Message (XML Editor or Standalone)

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

Configure the global element’s attributes and child element according to the table below.

Option Description Required

Option	Description	Required
algorithm	The signature Algorithm for PGP signature. Possible values are: SHA256 (Default) SHA384 SHA512 SHA224 MD5 SHA1 RIPEMD160 DOUBLE_SHA TIGER_192 HAVAL_5_160	Yes
publicKeyRingFileName	The path to your public key ring file. This binary key ring holds the message receiver’s public key.	Yes
secretKeyRingFileName	The path to your secret key ring file. This binary key ring holds the message sender’s private key.	Yes
secretAliasId	The 64 bit (16 characters) Key ID of the secret key used to sign the message.	Yes
secretPassphrase	The passphrase you provided while generating your PGP certificate.	Yes
outputMode	The PGP encryption output mode. Possible values are: Armor (default) Produces an ASCII-armor signed output. The result of this output is an `.asc` file extension. This PGP armored file is used with email systems that only allow ASCII printable characters. Binary Produces a binary signed output. The result of this output is an `.gpg` file extension.	Yes

algorithm

The signature Algorithm for PGP signature. Possible values are:

SHA256 (Default)
SHA384
SHA512
SHA224
MD5
SHA1
RIPEMD160
DOUBLE_SHA
TIGER_192
HAVAL_5_160

Yes

publicKeyRingFileName

The path to your public key ring file.
This binary key ring holds the message receiver’s public key.

Yes

secretKeyRingFileName

The path to your secret key ring file.
This binary key ring holds the message sender’s private key.

Yes

secretAliasId

The 64 bit (16 characters) Key ID of the secret key used to sign the message.

Yes

secretPassphrase

The passphrase you provided while generating your PGP certificate.

Yes

outputMode

The PGP encryption output mode. Possible values are:

Armor (default)
Produces an ASCII-armor signed output. The result of this output is an .asc file extension.
This PGP armored file is used with email systems that only allow ASCII printable characters.
Binary
Produces a binary signed output. The result of this output is an .gpg file extension.

Yes

<signature:config name="Signature" defaultSigner="PGP_SIGNER" doc:name="Signature">
  <signature:pgp-signer-config
  algorithm="SHA256"
  publicKeyRingFileName="./src/main/resources/keys/public.gpg"
  secretKeyRingFileName="./src/main/resources/keys/private.gpg"
  secretAliasId="11EF69338FE375AF"
  secretPassphrase="thisismule"
  outputMode="ARMOR"/>
</signature:config>

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

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

Adding a Digital XML Signature to a Message (Studio Visual Editor)

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).

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.

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.

Field

Req’d

Value

Name

A unique name for your global element.

Default Signer

XML_SIGNER

Reference or Expression

Define Attributes

If selected, enter values in the following nine fields.

Digest Method Algorithm

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

Canonicalization Algorithm

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

Signature Method Algorithm

The algorithm Mule uses to protect the message from tampering:
RSA_SHA1 (Default)
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) (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 configured in the Global Element Properties window, that key will be invoked for all processors which refer to that global element — unless there is a different key specified in the local Pattern Properties window for that processor, because local configuration overrides global configurations. * If configured in the local Pattern Properties window, that key will be invoked only for that processor, so any other processors in the same flow that also refer to that global element would need a key configured in their Pattern Properties windows.

Add a Signature message processor to your flow.

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

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)

Field

Req’d

Value

Display Name

A unique name for your message processor.

Config Reference

Use the name of the global element you created above.

Operation

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

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)

Adding a Digital XML Signature to a Message (XML Editor or Standalone)

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

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.

Attribute

Req’d

Value

name

A unique name for your global element.

defaultSigner

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

Req’d

signature:xml-signer-config

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.

Child Element Attributes

Req’d

Value

digestMethodAlgorithm

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

canonicalizationAlgorithm

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

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)

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.

Add a signature:sign element to your flow.

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)

Attribute

Req’d

Value

config-ref

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

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

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

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.

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.
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"/>
```
Use the Using field (or using attribute in XML) to indicate the type of signature:` JCE_SIGNER` or XML_SIGNER.
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.
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.
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.
Configure any other attributes of a Global Signature element. Again, refer to the JCE Signer and XML Signer sections above for attribute configuration details.

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

JCE Signer Available Algorithms

HmacMD5

HmacSHA1

HmacSHA256

HmacSHA384

HmacSHA512

MD2WithRSAEncryption

MD4WithRSAEncryption

MD5WithRSAEncryption

RIPEMD128WithRSAEncryption

RIPEMD160WithRSAEncryption

RIPEMD256WithRSAEncryption

SHA1WithRSAEncryption

SHA224WithRSAEncryption

SHA256WithRSAEncryption