EzCrypt Modules
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.
| Algorithm | The symmetric algorithm. |
| CipherMode | The cipher mode of operation. |
| IV | The initialization vector used by the CipherMode to modify the ciphertext. |
| Key | The secret key for the symmetric algorithm. |
| KeyPassword | A password used by the transformer to generate the Key and IV . |
| LogFile | The file to write logging information to at runtime. |
| LogMode | What information gets logged during component execution. |
| LogType | How information gets logged during component execution. |
| Other | Defines a set of configuration settings to be used by the transformer. |
| PaddingMode | The padding mode. |
| RuntimeLicense | Specifies the component runtime license key. |
| UseHex | Whether 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.
| Algorithm | The symmetric algorithm. |
| CipherMode | The cipher mode of operation. |
| IV | The initialization vector used by the CipherMode to modify the ciphertext. |
| Key | The secret key for the symmetric algorithm. |
| KeyPassword | A password used by the transformer to generate the Key and IV . |
| LogFile | The file to write logging information to at runtime. |
| LogMode | What information gets logged during component execution. |
| LogType | How information gets logged during component execution. |
| Other | Defines a set of configuration settings to be used by the transformer. |
| PaddingMode | The padding mode. |
| RuntimeLicense | Specifies the component runtime license key. |
| UseHex | Whether 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.
| BlockSize | The block size, in bits, of the cryptographic operation. |
| EncryptedDataEncoding | The encoding of the encrypted input or output data. |
| IncludeIV | Whether to prepend the IV to the output data and read the IV from the input data. |
| KeyPasswordAlgorithm | The hash algorithm used to derive the Key and IV from the KeyPassword property. |
| KeyPasswordIterations | The number of iterations performed when using KeyPassword to derive the Key and IV. |
| KeyPasswordSalt | The salt value used in conjunction with the KeyPassword to derive the Key and IV. |
| KeySize | The size, in bits, of secret key for the symmetric algorithm. |
| TeaAlgorithm | The 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:
| Verbose | The connector will report all information regarding the transport. |
| Info | The connector will report all major operations, as well as all warnings and errors. |
| Warning | The connector will report any conditions that could result in unpredictable behavior as well as errors. |
| Error | The connector will report all errors that prevent normal operations from completing. |
| Fatal | The 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:
| None | The connector will not report any logging information. |
| Console | The connector will report all logging information to the console. |
| File | The 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:
|
||||||
| 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:
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:
|