EzCrypt Modules

Properties   Config Settings  

The EzCrypt Transformer can be used to encrypt and decrypt data for regular transport.

Remarks

The EzCrypt Module contains an encoder and a decoder that receive Mule Messages from the Mule Project and perform cryptographic operations on the data. The encoder will produce an encrypted file that the decoder can then decrypt, making it possible to add secure storage to your business process.

Configuration

To use the EzCrypt Module, first select an Algorithm. Only symmetric algorithms are supported in the EzCrypt Module.

Next, set the KeyPassword to allow the module to generate the cryptographic Key and IV. Alternatively, you may set the Key and IV properties directly. Note that the same password may be used for the encoder and decoder to generate the same key and IV.

You can control the size of the key by setting the KeySize configuration setting. You can change how the cryptography is performed by setting the CipherMode and PaddingMode properties.

Encrypt Example

Add a File Read connector in front of the EzCrypt Encode Module and configure it to read a target file. Add the EzCrypt Encode Module behind it and configure it with a KeyPassword. That is all that is required to begin encrypting data.

The module will write the encrypted bytes to the payload of the Mule Message. You can specify a File Write connector behind EzCrypt Encode to write the encrypted bytes to disk or perform your own further processing.

Decrypt Example

Add a File Read connector in front of the EzCrypt Decode Module and configure it to read encrypted bytes. Add the EzCrypt Decode Module behind it specify the same KeyPassword. That is all that is required to begin decrypting the data.

The module will write the decrypted bytes to the payload of the Mule Message. You can specify a File Write connector behind EzCrypt Decode to write the plaintext bytes to disk or perform your own further processing.

Encoder Property List


The following is the full list of the properties of the encoder Module with short descriptions. Click on the links for further details.

AlgorithmThe symmetric algorithm.
CipherModeThe cipher mode of operation.
IVThe initialization vector used by the CipherMode to modify the ciphertext.
KeyThe secret key for the symmetric algorithm.
KeyPasswordA password used by the transformer to generate the Key and IV .
LogFileThe file to write logging information to at runtime.
LogModeWhat information gets logged during component execution.
LogTypeHow information gets logged during component execution.
OtherDefines a set of configuration settings to be used by the transformer.
PaddingModeThe padding mode.
RuntimeLicenseSpecifies the component runtime license key.
UseHexWhether input or output is hex encoded.

Decoder Property List


The following is the full list of the properties of the decoder Module with short descriptions. Click on the links for further details.

AlgorithmThe symmetric algorithm.
CipherModeThe cipher mode of operation.
IVThe initialization vector used by the CipherMode to modify the ciphertext.
KeyThe secret key for the symmetric algorithm.
KeyPasswordA password used by the transformer to generate the Key and IV .
LogFileThe file to write logging information to at runtime.
LogModeWhat information gets logged during component execution.
LogTypeHow information gets logged during component execution.
OtherDefines a set of configuration settings to be used by the transformer.
PaddingModeThe padding mode.
RuntimeLicenseSpecifies the component runtime license key.
UseHexWhether input or output is hex encoded.

Config Settings


The following is a list of config settings for the Module with short descriptions. Click on the links for further details.

BlockSizeThe block size, in bits, of the cryptographic operation.
EncryptedDataEncodingThe encoding of the encrypted input or output data.
IncludeIVWhether to prepend the IV to the output data and read the IV from the input data.
KeyPasswordAlgorithmThe hash algorithm used to derive the Key and IV from the KeyPassword property.
KeyPasswordIterationsThe number of iterations performed when using KeyPassword to derive the Key and IV.
KeyPasswordSaltThe salt value used in conjunction with the KeyPassword to derive the Key and IV.
KeySizeThe size, in bits, of secret key for the symmetric algorithm.
TeaAlgorithmThe TEA algorithm.

Algorithm Property (EzCrypt Module)

The symmetric algorithm.

Data Type

Enumeration

Possible Values

AES (0)
Blowfish (1)
CAST (2)
DES (3)
IDEA (4)
RC2 (5)
RC4 (6)
TEA (7)
Triple DES (8)
Twofish (9)
Rijndael (10)


Default Value

0

Remarks

This property specifies the symmetric algorithm to use. Possible values are:

  • 0 (AES - default)
  • 1 (Blowfish)
  • 2 (CAST)
  • 3 (DES)
  • 4 (IDEA)
  • 5 (RC2)
  • 6 (RC4)
  • 7 (TEA)
  • 8 (TripleDES)
  • 9 (Twofish)
  • 10 (Rijndael)
  • 11 (ChaCha)
  • 12 (XSalsa20)

CipherMode Property (EzCrypt Module)

The cipher mode of operation.

Data Type

Enumeration

Possible Values

CBC (0)
ECB (1)
OFB (2)
CFB (3)
CTS (4)


Default Value

0

Remarks

The cipher mode of operation.

Possible values are:

0 (cmCBC - default) The Cipher Block Chaining (CBC) is a mode of operation for a block cipher, one in which a sequence of bits is encrypted as a single unit or block with a cipher key applied to the entire block.
1 (cmECB) The Electronic Codebook (ECB) mode encrypts each block separately. Important: It is not recommend to use this model when encrypting more than one block because it may introduce security risks.
2 (cmOFB) The Output Feedback (n-bit, NOFB) mode makes a block cipher into a synchronous stream cipher. It has some similarities to CFB mode in that it permits encryption of differing block sizes, but has the key difference that the output of the encryption block function is the feedback (instead of the ciphertext).
3 (cmCFB) The Cipher Feedback (CFB) mode processes a small amount of incremental text into ciphertext, rather than processing a whole block at one time.
4 (cmCTS) The Cipher Text Stealing (CTS) mode handles any length of plain text and produces cipher text whose length matches the plain text length. This mode behaves like the CBC mode for all but the last two blocks of the plain text.
5 (cm8OFB) 8-bit Output Feedback (OFB) cipher mode.
7 (cm8CFB) 8-bit Cipher Feedback (CFB) cipher mode.

IV Property (EzCrypt Module)

The initialization vector used by the CipherMode to modify the ciphertext.

Data Type

String

Default Value

""

Remarks

The IV is an initialization vector used by the CipherMode to modify the ciphertext output by the module. This can add several degrees of security to the cipher.

Key Property (EzCrypt Module)

The secret key for the symmetric algorithm.

Data Type

String

Default Value

""

Remarks

This secret key is used both for encryption and decryption. The secret key should be known only to the sender and the receiver. The legal key size varies depending on the algorithm.

If this property is left empty it will be set to a random value by the connector as necessary.

Legal Key and Block Sizes (in bits)

AES Rijndael CAST DES IDEA RC2 RC4 TripleDES Blowfish Twofish TEA
Minimum Key Size 128 128 112 64 128 112 112 128 112 128 128
Maximum Key Size 256 256 128 64 128 128 2048 192 448 256 128
Key Size Step 64 64 8 0 0 8 8 64 1 8 0
Block Size 128 128/192/256 64 64 64 64 N/A 64 64 128 64*

Note: When using TEA if Algorithm is set to XXTEA valid block sizes are 64 + n * 32. Where n is any positive integer.

The default KeySize is the Maximum Key Size.

KeyPassword Property (EzCrypt Module)

A password used by the transformer to generate the Key and IV .

Data Type

Password

Default Value

""

Remarks

The module can use the KeyPassword to fill in the values of Key and IV using the PKCS5 password digest algorithm. The size of the Key generated is dependent on the value of KeySize.

LogFile Property (EzCrypt Module)

The file to write logging information to at runtime.

Data Type

String

Default Value

""

Remarks

To write logging information to a file instead of using the connector's logging API, set this property to a valid file on disk and set the LogType property to "File".

LogMode Property (EzCrypt Module)

What information gets logged during component execution.

Data Type

Enumeration

Possible Values

Verbose (0)
Info (1)
Warning (2)
Error (3)
Fatal (4)


Default Value

3

Remarks

This property controls what information the connector logs. The possible values have the following affect on the connector's behavior:

VerboseThe connector will report all information regarding the transport.
InfoThe connector will report all major operations, as well as all warnings and errors.
WarningThe connector will report any conditions that could result in unpredictable behavior as well as errors.
ErrorThe connector will report all errors that prevent normal operations from completing.
FatalThe connector will report only serious errors that cause the connector to completely stop functioning.

LogType Property (EzCrypt Module)

How information gets logged during component execution.

Data Type

Enumeration

Possible Values

None (0)
Console (1)
File (2)


Default Value

1

Remarks

This property controls where the connector will log the information. The possible values have the following affect on the connector's behavior:

NoneThe connector will not report any logging information.
ConsoleThe connector will report all logging information to the console.
FileThe connector will report all logging information to a file. The desired file must be specified in the LogFile when this type has been selected.

Other Property (EzCrypt Module)

Defines a set of configuration settings to be used by the transformer.

Data Type

String

Default Value

""

Remarks

The module accepts one or more configuration settings. These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the module, access to these internal properties is provided through the Other property.

The Other property may be set to one or more configuration settings (name/value pairs). Set one setting per line. For example: configname1=value1 configname2=value2

PaddingMode Property (EzCrypt Module)

The padding mode.

Data Type

Enumeration

Possible Values

PKCS7 (0)
Zeros (1)
None (2)
ANSIX923 (3)
ISO10126 (4)


Default Value

0

Remarks

PaddingMode is used to pad the final input block to guarantee that it is the correct size required for the selected CipherMode. Each mode pads the data differently. Possible values are:

0 (pmPKCS7 - default) The data is padded with a series of bytes that are each equal to the number of bytes used. For instance, in the example below the data must be padded with 3 additional bytes, so each byte value will be 3.

Raw Data: AA AA AA AA AA PKCS7 Padded Data: AA AA AA AA AA 03 03 03
1 (pmZeros) The data is padded with null bytes.
2 (pmNone) No padding will be performed.
3 (pmANSIX923) The ANSIX923 padding string consists of a sequence of bytes filled with zeros before the length. For instance, in the example below the data must be padded with 3 additional bytes, so last byte value will be 3.

Raw Data: AA AA AA AA AA ANSIX923 padding Data: AA AA AA AA AA 00 00 03
4 (pmISO10126) The ISO10126 padding string consists of random data before the length. For instance, in the example below the data must be padded with 3 additional bytes, so last byte value will be 3.

Raw Data: AA AA AA AA AA ISO10126 padding Data: AA AA AA AA AA F8 EF 03

When decrypting the PaddingMode must match the value used when the data was encrypted.

Note: When using a value of 2 (pmNone), unless the length of input is an exact multiple of the cipher's input BlockSize, the final block of plaintext may be lost.

RuntimeLicense Property (EzCrypt Module)

Specifies the component runtime license key.

Data Type

String

Default Value

""

Remarks

You can use the RuntimeLicense property to set the runtime key for the connector license.

UseHex Property (EzCrypt Module)

Whether input or output is hex encoded.

Data Type

Boolean

Default Value

false

Remarks

This property specifies whether the encrypted data is hex encoded.

If set to True, when encrypting the connector will perform the encryption as normal and then hex encode the output.

If set to True, when decrypting the connector will expect the input to hold hex encoded data. The connector will then hex decode the data and perform decryption as normal.

Config Settings (EzCrypt Module)

The connector accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the connector, access to these internal properties is provided through the Other property.

EzCrypt Config Settings

BlockSize:   The block size, in bits, of the cryptographic operation.

The block size is a basic data unit in the operation of encrypt or decrypt. Messages longer than the block size are seen as successive blocks. If the message is shorter than the block size, the message will be padded with extra bits to reach the block size according to PaddingMode. Different symmetric algorithm has different valid block sizes.

The following algorithms have a fixed block size: AES, CAST, DES, IDEA, RC2, TripleDES, Blowfish, and Twofish.

EncryptedDataEncoding:   The encoding of the encrypted input or output data.

This configuration setting specifies how the encrypted data is encoded (if at all).

When Encrypt is called the connector will perform the encryption as normal and then encode the output as specified here. OutputMessage or OutputFile will hold the encoded data.

When Decrypt is called the connector will expect InputMessage or InputFile to hold the encoded data as specified here. The connector will then decode the data and perform decryption as normal.

Possible values are:

  • 0 (none - default)
  • 1 (Base64)
  • 2 (Hex)
  • 3 (Base64URL)

IncludeIV:   Whether to prepend the IV to the output data and read the IV from the input data.

If this config is true, the IV will be automatically prepended to the output data when encrypting. When decyrpting and this setting is True, the IV is automatically extracted form the ciphertext. The default value is False.

KeyPasswordAlgorithm:   The hash algorithm used to derive the Key and IV from the KeyPassword property.

This configuration setting specifies which hash algorithm will be used when deriving the Key and IV from KeyPassword. The default value is "MD5". Possible values are:

  • "SHA1"
  • "MD2"
  • "MD5" (default)
  • "HMAC-SHA1"
  • "HMAC-SHA224"
  • "HMAC-SHA256"
  • "HMAC-SHA384"
  • "HMAC-SHA512"
  • "HMAC-MD5"
  • "HMAC-RIPEMD160"

When using any HMAC algorithm the PBKDF#2 method from RFC 2898 is used. Any other algorithm uses PBKDF#1 from the same RFC.

KeyPasswordIterations:   The number of iterations performed when using KeyPassword to derive the Key and IV.

This configuration setting specifies the number of iterations performed when using KeyPassword to calculate values for Key and IV. When using PBKDF#2 the default number of iterations is 10,000. When using PBKDF#1 the default number is 10.

KeyPasswordSalt:   The salt value used in conjunction with the KeyPassword to derive the Key and IV.

This configuration setting specifies the hex encoded salt value to be used along with the KeyPassword when calculating values for Key and IV.

KeySize:   The size, in bits, of secret key for the symmetric algorithm.

The legal key sizes vary depending on the algorithm. The KeySize and BlockSize configuration settings may be set to specify the key and block size (in bits).

This setting is only applicable when KeyPassword is specified.

Note that when using the EzCrypt connector, KeySize should be set after setting the Algorithm property.

TeaAlgorithm:   The TEA algorithm.

This property specifies the TEA algorithm to use. It is recommended to use the XXTEA (Corrected Block TEA) algorithm for security reasons. Possible values are:

0 (taXXTEA - default) Correct Block TEA
1 (taXTEA) eXtended TEA
2 (taTEA) TEA (Tiny Encryption Algorithm)