Contact Us 1-800-596-4880

Mule Message Encryption Processor

Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version.

Encrypting a Message Payload

Add a Mule Message Encryption Processor to a flow to change the content of a message so that it becomes unreadable by unauthorized entities. Mule can encrypt the entire payload of a message or specific parts of the payload, according to security requirements, using one of the following three Encryption Strategies:

Encryption Strategy Characteristics

JCE Encrypter

• encrypts stream, byte[] or string

XML Encrypter

• encrypts string
• encrypts individual fields using xpath expressions

PGP Encrypter

• encrypts stream, byte[] or string
• applies tighter security (relative to JCE and XML)
• increases processing load (relative to JCE and XML)

JCE Encrypter

As Mule’s default encryption strategy, the Java Cryptography Extension (JCE), as part of the Java Cryptography Architecture (JCA) encodes a message payload, or part of a payload.

Studio Visual Editor

  1. Create an global Encryption element, specifying a name for the element if you wish; keep the default value for the Default Encrypter:` JCE_ENCRYPTER`.

    global_encryption
  2. Set an Encryption message processor in the flow in which you wish to encrypt data in the message payload.

  3. Configure the message processor according the table below.

    encrypt
    Field Req’d Value

    Display Name

    A unique name for your message processor.

    Config Reference

    x

    Use the drop down to select the global Encryption element you created.

    Operation

    x

    Encrypt

    Input reference

    Enter a Mule expression to define the part(s) of the message Mule should encrypt. If no value is entered, Mule encrypts the entire message payload.

    Select encrypter

    x

    JCE_ECRYPTER

    Reference or expression

    If selected, in the Jce Encrypter 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 four fields.

    Key †

    x

    The key (i.e. password) to decrypt the encrypted data. It must be 16 bytes long

    Key Password †

    If the key is stored in a keystore, enter the passwoard to the keystore.

    Algorithm

    Select an algorithm to use to encrypt the data. Refer to Appendix below for list of available algorithms.

    Encryption Mode

    Select an encryption code for Mule to use to encrypt the data.

    † mutually exclusive

XML Editor or Standalone

  1. Create an global encryption:config element, set above all the flows in your config file.

  2. Configure the attributes of the element according to the table below.

    <encryption:config name="Encryption" defaultEncrypter="JCE_ENCRYPTER" doc:name="Encryption"/>
    Attribute Req’d Value

    name

    x

    A unique name for your global element.

    defaultEncrypter

    JCE_ENCRYPTER

    doc:name

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

  3. Add an encryption:encrypt element to the flow in which you wish to encrypt data in the message payload.

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

    <encryption:encrypt config-ref="Encryption" doc:name="Encryption" using="JCE_ENCRYPTER" input-ref="#[message.payload]">
            <encryption:jce-encrypter key="test" algorithm="Blowfish" encryptionMode="CFB"/>
    </encryption:encrypt>
    Attribute Req’d Value

    config-ref

    x

    Use the name of the global Encryption element you created.

    doc:name

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

    using

    x

    JCE_ENCRYPTER

    input-ref

    Enter a Mule expression to define the part(s) of the message Mule should encrypt. If no value is entered, Mule encrypts the entire message payload.

    Child Attribute Req’d

    encryption:jce-encrypter

    x

    Child Element Attributes Req’d Value

    key†

    x

    Specify the key (i.e. password) to decrypt the encrypted data.

    algorithm

    Specify the algorithm to use to encrypt the data. Refer to Appendix below for list of available algorithms.

    encryption Mode

    Specify an encryption code for Mule to use to encrypt the data.

    keyPassword†

    If the key is stored in a keystore, specify the passwoard to the keystore.

    †mutually exclusive

XML Encrypter

The XML encrypter encodes XML string content in a message payload.

Studio Visual Editor

  1. Create an global Encryption element, specifying a name for the element if you wish; change the default value for the Default Encrypter to XML_ENCRYPTER.

    global_Xml
  2. Set an Encryption message processor in the flow in which you wish to encrypt data in the message payload.

  3. Configure the message processor according the table below.

    xml_encrypter
    Field Req’d Value

    Display Name

    A unique name for your message processor.

    Config Reference

    x

    Use the drop down to select the global Encryption element you created.

    Operation

    x

    Encrypt

    Input reference

    Enter a Mule expression to define the part(s) of the message Mule should encrypt. If no value is entered, Mule encrypts the entire message payload.

    Select encrypter

    x

    XML_ECRYPTER

    Reference or expression

    If selected, in the Xml Encrypter 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 four fields.

    Key †

    x

    The key (i.e. password) to decrypt the encrypted data.

    Key Password †

    If the key is stored in a keystore, enter the passwoard to the keystore.

    Algorithm

    Select an algorithm to use to encrypt the data. Refer to Appendix below for list of available algorithms.

    Encryption Mode

    Select an encryption code for Mule to use to encrypt the data.

    † mutually exclusive

XML Editor or Standalone

  1. Create an global encryption:config element, set above all the flows in your config file.

  2. Configure the attributes of the element according to the table below.

    <encryption:config name="Encryption" defaultEncrypter="XML_ENCRYPTER" doc:name="Encryption"/>
    Attribute Req’d Value

    name

    x

    A unique name for your global element.

    defaultEncrypter

    XML_ENCRYPTER

    doc:name

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

  3. Add an encryption:encrypt element to the flow in which you wish to encrypt data in the message payload.

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

    <encryption:encrypt config-ref="Encryption" doc:name="Encryption" using="XML_ENCRYPTER" input-ref="#[message.payload]">
            <encryption:jce-encrypter key="test" algorithm="Blowfish" encryptionMode="CFB"/>
    </encryption:encrypt>
    Attribute Req’d Value

    config-ref

    x

    Use the name of the global Encryption element you created.

    doc:name

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

    using

    x

    XML_ENCRYPTER

    input-ref

    Enter a Mule expression to define the part(s) of the message Mule should encrypt. If no value is entered, Mule encrypts the entire message payload.

    Child Element Req’d

    encryption:xml-encrypter

    x

    Child Element Attributes Req’d Value

    key†

    x

    Specify the key (i.e. password) to decrypt the encrypted data.

    algorithm

    Specify the algorithm to use to encrypt the data. Refer to Appendix below for list of available algorithms.

    encryption Mode

    Specify an encryption code for Mule to use to encrypt the data.

    keyPassword†

    If the key is stored in a keystore, specify the passwoard to the keystore.

    †mutually exclusive

PGP Encrypter

Mule has the ability to encrypt a message payload, or part of a payload, using Pretty Good Privacy (PGP).

Because of its increased complexity, the topic has earned its own page: refer to the PGP Encrypter document.

Encrypting Part of a Message Payload

For details on message encryption in Mule, refer to the Encrypt a Message Payload section above.

By default, when you apply an encrypter, Mule encrypts the entire message payload. However, you can use a Mule Expression to encrypt a specific part of a message rather than the whole payload. Configure the Input Reference to define the specific part(s) of the payload you wish to encrypt.

Studio Visual Editor

EngcryptionPayloadtoString3

XML Editor or Standalone

<encryption:encrypt config-ref="Encryption_PGP" doc:name="Encryption" using="PGP_ENCRYPTER" input-ref="#[payload.toString()]">

Additionally, you can add an Xpath expression attribute to the XML encrypter to define specific field(s) to encrypt — credit card number or SSN, for example (see below).

Studio Visual Editor

xpath_XML

XML Editor or Standalone

<encryption:encrypt  doc:name="Encrypt CC" using="XML_ENCRYPTER" config-ref="plainXML" input-ref="#[payload.toString()]">
            <encryption:xml-encrypter xpath="/users/cc"/>
</encryption:encrypt>

Decrypting a Message Payload

Add a Mule Message Encryption Processor to decrypt the content of a message so that it becomes readable by the message processors in your Mule application. Mule can decrypt the entire payload of a message or specific parts of the payload using one of the following three Encryption Strategies:

  1. JCE Decrypter

  2. PGP Decrypter

  3. XML Decrypter

Refer to Encrypt a Message Payload document for details on the Encryption strategies.

The type of encryption strategy you use to decrypt a message depends entirely upon the type of encryption employed by the message sender.

Further, you must configure a decrypter’s attributes to address the type of encryption the message’s sender applied. For example, if the message uses a keystore for encryption, your decrypter must use the keystore to decrypt the message.

Decrypting Part of a Message Payload

Refer to the Decrypting a Message Payload section for details on message decryption in Mule.

By default, Mule decrypts the entire message payload when you apply a decrypter. However, you can use a Mule Expression to decrypt a specific part of a message payload rather than the whole payload. Configure the Input Expression to define the specific part(s) of the payload you wish to decrypt.

Additionally, you can add an Xpath expression attribute to the XML decrypter to define specific field(s) to decrypt — credit card number or SSN, for example (refer to the encryption screenshot and code in Encrypt Part of a Message Payload).

Appendix

Algorithms Available in JCE Minimum Key Size Maximum
Key Size

AES

16

16

Blowfish

1

Unlimited

DES

8

8

DESede

16

24

Camellia

16

16

CAST5

1

16

CAST6

1

Unlimited

Noekeon

16

Unlimited

Rijndael

16

16

SEED

16

Unlimited

Serpent

16

16

Skipjack

16

Unlimited

TEA

16

Unlimited

Twofish

8

Unlimited

XTEA

16

Unlimited

RC2

1

Unlimited

RC5

1

Unlimited

RC6

1

Unlimited

RSA

16

Unlimited