Cryptographic functions in Jitterbit Design Studio
Cryptographic functions are used to perform basic encryption and decryption using standard algorithms and functions.
Read and write files using Base-64
The Base64 functions can be used when reading and writing files, following these common scenarios:
One scenario is to read an existing file (perhaps a PDF) using the Base64EncodeFile function, and then write the contents of that file to an endpoint, such as Salesforce.
To do this, create a script that reads the file from a source and sets appropriate global variables. You would then create a transformation that takes these global variables and uses them in a mapping to write to Salesforce:
// Read a PDF File
$docName = "Test.pdf";
$fileContents = Base64EncodeFile("<TAG>Sources/PDF Files</TAG>", $docName);
$docLength = Length($fileContents);
$docType = "pdf";
$mimeType = "application/pdf";
A second scenario is to read from a file, placing the contents into a variable, and then use the Base64Encode function on the contents before saving to a new text file.
AESDecryption
Declaration
string AESDecryption(string encryptedText, string passphrase[, string salt, int keyLength, int iterations])
Syntax
AESDecryption(<encryptedText>, <passphrase>[, <salt>, <keyLength>, <iterations>])
Required parameters
encryptedText: A Base64-encoded AES encrypted valuepassphrase: Password used to encrypt the string with theAESEncryptionfunction
Optional parameters
salt: Hex string salt used to encrypt the string with theAESEncryptionfunctionkeyLength: Key length used to encrypt the string with theAESEncryptionfunctioniterations: Number of iterations used to encrypt the string with theAESEncryptionfunction
Description
This function decrypts a string encrypted with the AESEncryption function's AES algorithm.
The decrypted output is returned as a string. See AESEncryption for additional details.
Note
To decrypt text encrypted with an AES algorithm using OpenSSL 3, set jitterbit.scripting.aes.default to true upstream of this function. This variable is supported when using agent versions 11.42 or later.
Alternatively, AESDecryptionEx supports OpenSSL 3 AES decryption by default when using agent versions 11.42 or later.
Examples
// Encrypting a string
encrypted = AESEncryption("Hello world!", "password");
// Decrypted as "Hello world!"
decrypted = AESDecryption(encrypted, "password");
// Encrypting (and decrypting) a string using
// a passphrase and salt, 256-bit key, and 1024 iterations
encrypted = AESEncryption("Hello world!", "password", "00FFAE01", 256, 1024);
decrypted = AESDecryption(encrypted, "password", "00FFAE01", 256, 1024);
AESDecryptionEx
Declaration
string AESDecryptionEx(string encryptedText, string key[, string iv, int keyLength>])
Syntax
AESDecryptionEx(<encryptedText>, <key>[, <iv>, <keyLength>])
Required parameters
encryptedText: A Base64-encoded, OpenSSL 3-supported AES-encrypted stringkey: The key used to encryptencryptedText
Optional parameters
iv: The 16-byte initialization vector (IV) used to encryptencryptedTextkeyLength: The key length used to encryptencryptedText
Description
This function decrypts a string encrypted with an AES algorithm using OpenSSL 3. This includes text encrypted outside of the Jitterbit Harmony platform and text encrypted using the AESEncryptionEx function. This function is supported when using Design Studio versions 11.42 or later and agent versions 11.42 or later.
The decrypted output is returned as a string. See AESEncryptionEx for encryption.
Examples
// Encrypting (and decrypting) a string using a 128-bit key and 16-byte IV
encrypted = AESEncryptionEx("Hello world!", "123456ZYXWVUTSRQ", "12345XYZ12345XYZ", 128);
decrypted = AESDecryptionEx(encrypted, "123456ZYXWVUTSRQ", "12345XYZ12345XYZ", 128);
AESEncryption
Declaration
string AESEncryption(string plainText, string passphrase[, string salt, int keyLength, int iterations])
Syntax
AESEncryption(<plainText>, <passphrase>[, <salt>, <keyLength>, <iterations>])
Required parameters
plainText: A string to be encryptedpassphrase: Password to be used to encrypt the string
Optional parameters
salt: Hex string salt used to encrypt the string; if specified, the value must be given in hex format (such as"A034DD")keyLength: Key length to be used to encrypt the string and must be one of 128, 192, or 256; the default is 256iterations: Number of iterations used to generate the key; the default is 1
Description
This function encrypts a string using an AES algorithm that can be decrypted using the AESDecryption function. The key is generated according to Password-Based Cryptography Specification Version 2.0 (PKCS5S2).
The encrypted output is a Base64-encoded string. The output from AESEncryption can be passed directly to the AESDecryption function for decryption, using the same parameters as when the plaintext string was encrypted.
Note
To encrypt text with an AES algorithm using OpenSSL 3, set jitterbit.scripting.aes.default to true upstream of this function. This variable is supported when using agent versions 11.42 or later.
Alternatively, AESEncryptionEx supports OpenSSL 3 AES encryption by default when using agent versions 11.42 or later.
Examples
// Encrypting a string
encrypted = AESEncryption("Hello world!", "password");
// Decrypted as "Hello world!"
decrypted = AESDecryption(encrypted, "password");
// Encrypting (and decrypting) a string using
// a passphrase and salt, 256-bit key, and 1024 iterations
encrypted = AESEncryption("Hello world!", "password", "00FFAE01", 256, 1024);
decrypted = AESDecryption(encrypted, "password", "00FFAE01", 256, 1024);
AESEncryptionEx
Declaration
string AESEncryptionEx(string plainText, string key[, string iv, int keyLength])
Syntax
AESEncryptionEx(<plainText>, <key>[, <iv>, <keyLength>])
Required parameters
plainText: The string to be encryptedkey: The key to be used to encryptplainText
Optional parameters
iv: The 16-byte initialization vector (IV) used to encryptplainText; an error is thrown if the IV is not 16 byteskeyLength: The key length used to encryptplainTextand must be one of 128, 192, or 256; the default is 256
Description
This function encrypts a string using an AES algorithm using OpenSSL 3. This function is supported when using Design Studio versions 11.42 or later and agent versions 11.42 or later.
The encrypted output is an OpenSSL 3-supported, Base64-encoded string. The output from AESEncryptionEx can be passed directly to the AESDecryptionEx function or outside of the Jitterbit Harmony platform for decryption, using the same parameters as when the plaintext string was encrypted.
Examples
// Encrypting (and decrypting) a string using a 128-bit key and 16-byte IV
encrypted = AESEncryptionEx("Hello world!", "123456ZYXWVUTSRQ", "12345XYZ12345XYZ", 128);
decrypted = AESDecryptionEx(encrypted, "123456ZYXWVUTSRQ", "12345XYZ12345XYZ", 128);
Base64Decode
Declaration
binary Base64Decode(string encryptedText)
Syntax
Base64Decode(<encryptedText>)
Required parameters
encryptedText: A Base64-encoded string
Description
Decodes a Base64-encoded string, returning binary data. See also Base64Encode.
Caution
When using agent version 11.33 or earlier, the Base64Decode function may return a truncated or wrong value when the Base64-encoded string is not appended with = or ==. When using agent version 11.34 or later, Base64-encoded strings are handled as intended.
Examples
// Encrypting a string after first converting it to binary
binary = HexToBinary(StringToHex("Hello world!"));
encrypted = Base64Encode(binary);
decrypted = Base64Decode(encrypted);
result = HexToString(BinaryToHex(decrypted));
// Returns original string "Hello world!"
Base64Encode
Declaration
string Base64Encode(type arg)
Syntax
Base64Encode(<arg>)
Required parameters
arg: Value to be encoded
Description
Encodes the argument data, treating the characters in a string as binary data unless the input is already binary. If the type of the argument is not binary or a string, then the argument value is first converted to a string before encryption.
A newline character (\n) is added after every 64th character of the encoded result string. As many implementations of Base64 include newlines to limit the encoded result's maximum line length, this should be explicitly disabled only as needed. To disable this, set the jitterbit.base64.encoded.string.no.wrap Jitterbit variable to true before calling this function. This variable is supported with string data when using 10.49 agents and later, and with binary data when using 10.x agents 10.66 and later and 11.x agents 11.4 and later.
See also Base64Decode.
Examples
// Encrypting a string after first converting it to binary
binary = HexToBinary(StringToHex("Hello world!"));
encrypted = Base64Encode(binary);
decrypted = Base64Decode(encrypted);
result = HexToString(BinaryToHex(decrypted));
// Returns original string "Hello world!"
encrypted = Base64Encode(Now());
decrypted = Base64Decode(encrypted);
result = HexToString(BinaryToHex(decrypted));
// Returns a date string such as "2017-12-14 01:25:31"
// Encrypting credentials for use in an HTTP header
Base64Encode("exampleuser"+":"+"examplepassword")
Base64EncodeFile
Declaration
string Base64EncodeFile(string sourceId[, string filename])
Syntax
Base64EncodeFile(<sourceId>[, <filename>])
Required parameters
sourceId: A string source in the current project that returns a binary file. If an array of filenames is returned, the first one is used.
Optional parameters
filename: A string filename used to override the value returned by thesourceIdsource
Description
Reads a binary file from the specified source and returns the contents as a Base64-encoded string. This method is generally used for files that could be binary. To read a text file, use the function ReadFile instead.
The file-type source used in this function must be defined as a source in the current project. See the instructions on inserting project items.
This method returns the contents of the file pointed to by the specified source. If the source filter selects more than one file, the first one will be used. It is recommended to specify a source that uniquely identifies a single file.
The second parameter, filename, is optional and can be used to override the filename returned in the source definition. Alternatively, a global variable can be used to override the filename in the source definition. Global variables are referenced as [de_name] in the source definition.
If a file is not found, an error will be raised.
A newline character (\n) is added after every 64th character of the encoded result string. As many implementations of Base64 include newlines to limit the encoded result's maximum line length, this should be explicitly disabled only as needed. To disable this, set the jitterbit.base64.encoded.string.no.wrap Jitterbit variable to true before calling this function. This variable is supported with string data when using 10.49 agents and later, and with binary data when using 10.x agents 10.66 and later and 11.x agents 11.4 and later.
See also Base64Decode.
Examples
// Reads the first file found at the source "Word Documents FTP"
// and returns it as Base64-encoded string
fileContents1 = Base64EncodeFile("<TAG>Sources/Word Documents FTP</TAG>");
// Reads the binary file called "requirements.doc" from
// the FTP directory defined by the source "Word Documents FTP"
fileContents2 = Base64EncodeFile("<TAG>Sources/Word Documents FTP</TAG>",
"requirements.doc");
// Decodes the file contents; they can now be re-written
// as a binary file to another target
fileContents2Decoded = Base64Decode(fileContents2);
MD5
Declaration
string MD5(type arg)
Syntax
MD5(<arg>)
Required parameters
arg: Value to be hashed
Description
Applies the MD5 hash function to the supplied argument. The hash is returned as a 64-bit string of hex numbers. Non-string data will first be converted to a string.
Caution
When used with agents version 10.63 and earlier or 11.1 and earlier, this function does not generate the correct values for binary files such as ZIP or PDF. This behavior can be applied to later agent version using the Jitterbit variable $jitterbit.md5.hash.use.file.mode.string.only.
Examples
MD5("hello world!");
// Returns "fc3ff98e8c6a0d3087d515c0473f8677"
MD5AsTwoNumbers
Declaration
array MD5AsTwoNumbers(type arg)
Syntax
MD5AsTwoNumbers(<arg>)
Required parameters
arg: Value to be hashed
Description
Applies the MD5 hash function to an input string and returns the result as an array with two 64-bit numbers. Non-string data will first be converted to a string.
Examples
MD5AsTwoNumbers("hello world!");
// Returns "{8612640914790536583, 3462540840444444668}"
SHA256
Declaration
string SHA256(type arg)
Syntax
SHA256(<arg>)
Required parameters
arg: Value to be hashed
Description
Applies the SHA-256 hash function to an input string. The hash returned is a string of 64 hex numbers.
If the input is a string, it will first be converted to the UTF-8 byte representation. Non-string data will first be converted to a string.
Caution
When used with agents version 10.63 and earlier or 11.1 and earlier, this function does not generate the correct values for binary files such as ZIP or PDF. This behavior can be applied to later agent version using the Jitterbit variable $jitterbit.md5.hash.use.file.mode.string.only.
Examples
SHA256("hello world!");
// Returns "7509e5bda0c762d2bac7f90d758b5b2263fa01ccbc542ab5e3df163be08e6ca9"