The encrypt and decrypt functions have been enhanced to accept optional arguments that were not in the original ColdFusion MX 7 documentation. The online documentation for ColdFusion MX 7 Security Functions contains usage information about these cryptographic functions, and this TechNote contains extended information about how to use them.

The arguments to the encrypt anddecrypt functions are changed as follows:

Encrypt(string, key, [algorithm ,encoding ,IVorSalt ,iterations])

Decrypt(string, key, [algorithm ,encoding ,IVorSalt ,iterations])

  • string String to encrypt or decrypt. This is always interpreted as a UTF-8 string for ColdFusion encryption.
  • key Encryption key or password.
    • For the CFMX_COMPAT algorithm, a string used as a seed to generate a 32-bit encryption key.
    • For Block Encryption algorithms, a key in the format used by the algorithm.

      For these algorithms, use the GenerateSecretKey function to generate the key.
    • For Password Based Encryption algorithms (names starting with PBE) - the password or passphrase
  • algorithm (Optional) The algorithm to use to encrypt or decrypt the string.

    ColdFusion MX includes both a backwards-compatible algorithm and the default algorithms provided by the Java Runtime:
    • Compatibility Algorithm
      • CFMX_COMPAT: The algorithm used in ColdFusion MX and prior releases. This algorithm is the least secure option. (default)
    • Block Encryption Algorithms
      • AES: The Advanced Encryption Standard specified by U.S. Nation Institute of Standards and Technology (NIST) FIPS-197.
      • BLOWFISH: The Blowfish algorithm defined by Bruce Schneier.
      • DES: The Data Encryption Standard algorithm defined by NIST FIPS-46-3.
      • DESEDE: The "Triple DES" algorithm defined by NIST FIPS-46-3.
    • Password Based Encryption Algorithms
      • PBEWithMD5AndDES: A password-based version of the DES algorithm that uses the MD5 hash to change your password into an encryption key
      • If you install the Sun Unlimited Strength Jurisdiction Policy Files for Java 1.4.2, the following Password Based algorithm is added:

        PBEWithMD5AndTripleDES: A password-based version of the DESEDE algorithm that uses the MD5 hash to change your password into an encryption key

      If you install a Java Cryptology Extension (JCE) security provider, you can use the additional encryption and decryption algorithms it provides.

  • encoding (Optional; if you specify this parameter, you must also specify the algorithm parameter)

    The binary encoding in which to represent the encrypted data as a string.
    • Base64: Use the Base64 algorithm, as specified by IETF RFC 2045
    • Hex: Use the characters A-F and 0-9 to represent the hexadecimal byte values
    • UU: (Default) Use the UUEncode algorithm
  • IVorSalt (Optional; if you specify this parameter, you must also specify the algorithm parameter)

    You may specify this optional parameter to adjust ColdFusion encryption to match the details of other encryption software.
    • For Block Encryption Algorithms - This is the binary Initialization Vector value to use with the algorithm. The algorithm must contain a Feedback Mode (see below) other than ECB. This must be a binary value that is exactly the same size as the algorithm block size (see below) The same value must be passed to Decrypt to successfully decrypt the data.
    • For Password Based Encryption Algorithms - This is the binary Salt value to transform the password into a key. The same value must be used to decrypt the data.
  • iterations (Optional; if you specify this parameter, you must also specify algorithm parameter with a Password Based Encryption (PBE) algorithm)

    You may specify this optional parameter to adjust ColdFusion encryption to match the details of other encryption software. This is the number of iterations to transform the password into a binary key. Do not specify this parameter for Block Encryption Algorithms. The same value must be used to decrypt the data.

ColdFusion MX 7.0.1 adds two additional encryption functions that encrypt binary values (bytes) and return binary values:

EncryptBinary(bytes, key, [algorithm ,IVorSalt ,iterations])

DecryptBinary(bytes, key, [algorithm ,IVorSalt ,iterations])

  • bytes binary data to encrypt or decrypt.
  • key Encryption key or password. See Encrypt and Decrypt functions for details.
  • algorithm (Optional) The algorithm to use to encrypt or decrypt the string. See Encrypt and Decrypt functions for details.
  • IVorSalt (Optional; if you specify this parameter, you must also specify the algorithm parameter) See Encrypt and Decrypt functions for details.
  • iterations (Optional; if you specify this parameter, you must also specify algorithm parameter with a Password Based Encryption (PBE) algorithm) See Encrypt and Decrypt functions for details.

The binary functions are useful for interchange with other software in two circumstances:

  1. When a character set other than UTF-8 is required.

    For example, to encrypt data for interchange with another system per these specifications:
    • the encrypted string must be Shift-JIS (rather than UTF-8)
    • the algorithm is DES
    • the feedback mode is Cipher-Feedback (CFB)
    • no padding is used
    • a fixed key with hex value: C01dF00dBaadCafe
    • a fixed IV value with hex value: 8e9682f08fd089ee

    use:

    <cfset myKey = ToBase64(BinaryDecode("C01dF00dBaadCafe", "HEX"))><cfset myIV = BinaryDecode("8e9682f08fd089ee", "HEX")><cfset cipher = EncryptBinary(CharsetDecode(mySJIStext, "SHIFT_JIS"), myKey, "DES/CFB/NoPadding", myIV)>


  2. When binary data, rather than string data, must be encrypted or decrypted. For example, data returned by

    <cffile action="READBINARY"> or<cfhttp getAsBinary="YES">.

Advanced Encryption Information (does not apply to CFMX_COMPAT encryption)

Algorithm characteristics, for algorithms included with ColdFusion

  • DES (Data Encryption Standard)

    A widely used encryption algorithm. It has been proven possible for a determined and well-equipped adversary to crack this 30-year old algorithm using brute-force methods.
  • DESEDE (Triple-DES)

    A stronger version of DES. This algorithm takes advantage of the fact that DES, unlike other algorithms, can be strengthened by using multiple encryptions and decryptions with different keys. The 24-byte key is used internally as three 8-byte DES keys. You can use the name TripleDES instead of DESEDE.
  • AES (Advanced Encryption Standard)

    A strong algorithm with the default (16-byte) length key. AES is faster than the DES and DESEDE algorithms for large data. AES is also known as Rijndael (pronounced like 'Rain doll'), which was the algorithm chosen by NIST to replace DES for new applications. You can use the name Rijndael instead of AES.
  • BlowFish

    A strong algorithm with the default (16-byte) length key. A wide range of key lengths is supported. BlowFish is faster than the DES and DESEDE algorithms for large data.
  • PBEWithMD5AndDES

    A password-based algorithm that uses the DES algorithm internally. The short (56-bit) key length makes this algorithm no stronger than a good, random, 11-character password, such as "n4i*OFS@bS3". If greater security is needed, use both a stronger algorithm and a longer password.
  • PBEWithMD5AndTripleDES

    A strong password-based algorithm that uses the DESEDE algorithm internally.

Creating keys manually

When you use the GenerateSecretKey function to generate a key for block encryption, a secure random key of the appropriate size for your algorithm is created and returned. This is usually the best way to create a key to use with ColdFusion Block Encryption and Decryption.

GenerateSecretKey works by first creating a binary key of the default key length for your algorithm using a secure random number generator. This key is then Base64 encoded before it is returned.

You may want to generate your own key for two reasons:

  1. You want to match the details of other encryption software.
  2. You want to increase the resistance to cracking of your encrypted data by pattern-oriented cryptanalysis techniques.

For example, to create a 32-byte key to use with the AES algorithm with the hex value:

8738fed68e7677d374e0946c8f7bd3bb4f50f23717f9f3667b2419483959039c

you would use the ColdFusion functions BinaryDecode and ToBase64 to create the key:

<cfset myKey = ToBase64(BinaryDecode("8738fed68e7677d374e0946c8f7bd3bb4f50f23717f9f3667b2419483959039c", "Hex")><cfset encrypted = Encrypt(myString, myKey, "AES")>

When you create your own keys, you must be careful that the key length is an allowable length for the algorithm. The table below lists the allowable key lengths for the algorithms included with ColdFusion.

Feedback modes

When you specify a simple algorithm name, like DES, the default Feedback Mode (ECB) and default method of padding your data (PKCS5Padding) are used. You can optionally specify an algorithm name that describes exactly which Feedback Mode and Padding method to use.

For example: DES/CBC/PKCS5Padding

Either specify a simple name (like DES) or specify all three parts (like DES/CBC/PKCS5Padding). You should specify the same name when decrypting the data.

You must always specify just a simple name (like DES) for the GenerateSecretKey function. Names that include a Feedback Mode and a Padding Method are only used with the Encrypt and Decrypt functions.

There are two reasons you might want to specify a Feedback Mode:

  1. You want to match the details of other encryption software
  2. You want to increase the resistance of your encrypted data to cracking by pattern-oriented cryptanalysis techniques.

Block Encryption algorithms encrypt your strings in "blocks" of characters. The table below lists the block sizes for the algorithms supplied with ColdFusion. If several different strings happen to have the same characters in the same block, they will encrypt to the same value. This might make your selected algorithm easier to crack. This is especially noticeable if your string has repeating characters that exactly match the algorithm's block size. For example, DES has a block size of 8 characters.

If you encrypt a repeating group of 8 characters using:

Encrypt("RepeatedRepeatedRepeatedRepeated", myKey, "DES", "Hex")

the result might be:

951ffe9dd9170c0d951ffe9dd9170c0d951ffe9dd9170c0d951ffe9dd9170c0d8af4677083478a00

Note that most of the encrypted value also repeats four times like the word "Repeated". If your data to be encrypted might contain such patterns, this problem can be avoided by using one of the Feedback Modes.

The available Feedback modes included with ColdFusion are:

  • ECB: Electronic Code Book. This is the default mode that does not use any feedback to encrypt the data. This mode encrypts whole blocks, so a padding method like PKCS5Padding must also be used. ECB is fine for encrypting short strings of data, or for strings that do not contain any predictable or repeating groups of characters.
  • CBC: Cipher Block Chaining. This mode feeds back whole blocks of encrypted bytes into the encryption calculation. This mode encrypts whole blocks, so a padding method like PKCS5Padding must also be used. CBC is considered the fastest and most secure feedback mode.
  • CFB: Cipher FeedBack. This mode feeds back individual bytes (8 bits) of the encrypted data into the encryption calculation. A padding method must be specified, but because this mode can work with individual bytes of data, the padding method NoPadding is an acceptable padding method with this mode.
  • OFB: Output Feedback. This mode produces an encrypted stream of bytes and performs a bitwise Exclusive-OR of each byte of your data with this stream. A padding method must be specified, but because this mode can work with individual bytes of data, the padding method NoPadding is an acceptable padding method. This mode has the characteristic that a 1-bit transmission error will only produce a 1-bit error in the decrypted value. Once useful, this characteristic is seldom an advantage with modern equipment.

The two "byte-oriented" Feedback modes can also be specified as CFB8 or OFB8 to indicate 8-bit feedback. Pairs of bytes can be fed back by specifying CFB16 or OFB16. Groups of four bytes can likewise be specified by CFB32 or OFB32. If more than single bytes are specified, then padding may necessary and the NoPadding method should not be used unless you are sure that your data will never require any padding.

Padding methods

Padding may be required when no feedback is used (feedback mode is omitted or is ECB), or when a feedback mode is used that works with multiple bytes (CBC, CFB16, etc.). If your data is certain to be an exact multiple of the algorithm's block size, you can use the NoPadding method. If your data is not always a multiple of the block size, the data to be encrypted must be padded to a full block size before it is encrypted. This padding is removed when the data is decrypted.

The available padding methods included with ColdFusion are:

  • PKCS5Padding

    The padding method described in Public-Key Cryptography Standard #5. This is the default method.
  • NoPadding

    No padding. This method is only useful with feedback modes that allow encrypting individual bytes of data, like CFB and OFB, or if your data will always be an exact multiple of the encryption block size.

Block size table

Algorithm Allowable Key Lengths

(bytes)
Default Key Length

(bytes)
Block Size

(bytes)
DES 8 * 8 8
DESEDE 24 * 24 8
AES 16, 24 **, or 32 ** 16 16
Blowfish 1 to 56 ** 16 8

* For DES, the key length must be 8 bytes (64 bits), but only 56 of the 64 bits are actually used by the algorithm. For DESEDE, only 168 of the 192 bits are actually used by the algorithm.

** The long key sizes are only available if the Sun Unlimited Strength Jurisdiction Policy Files for Java 1.4.2 are installed.

Initialization vectors (for interoperating with other encryption software)

Block Encryption Feedback modes (other than ECB, the default) require a binary value called an "Initialization Vector" to be created so that some feedback bytes are available when encryption is started. Normally, this is handled automatically by ColdFusion if it is needed, and requires no action on your part.

In order to interoperate with other encryption software, you may want to create the IV yourself.

When ColdFusion creates an IV automatically, it generates a secure, random IV and prepends this to the encrypted data. When ColdFusion decrypts the data, this IV is recovered and used. It is cryptologically important that the IV varies between encryptions. This is why the encrypted value changes when you repeatedly encrypt the same string with an algorithm that uses an IV, like DES/CBC/PKCS5Padding. Unlike the encryption key, it is not necessary for the IV to be kept secret.

You can create your own binary IV and pass it as the optional parameter IVorSalt. You must create an IV that is exactly the block size for your algorithm. When you create your own IV for encryption, ColdFusion does not include it with the encrypted data. In this case, your application must ensure that the same IV is used to encrypt and decrypt the data.

For example; To create an 8 byte IV for use with the DES/CBC/PKCS5Padding algorithm with the hex value 7fe8585328e9ac7b

<cfset myIV = BinaryDecode("7fe8585328e9ac7b")><cfset encrypted = Encrypt(myString, myKey, "DES/CBC/PKCS5Padding", "Base64", myIV)>

Salt and iterations (for interoperating with other encryption software)

Password Based Encryption (PBE algorithms) use a binary value called a "Salt" and repeated hashing to change a password or a pass phrase into an encryption key. Normally this is handled automatically by ColdFusion and requires no action on your part. It is never necessary to use the GenerateSecretKey function with PBE algorithms. The steps to convert a password into a key are built into the PBE algorithm.

In order to interoperate with other encryption software, you may want to create the Salt and specify the iteration count yourself.

When ColdFusion creates a Salt automatically, it generates a secure, random, 8 byte Salt and prepends this to the encrypted data. In this case, ColdFusion iterates the hash function 1,000 times.

Security is improved if the Salt (like the IV for Block Encryption algorithms) varies for each encryption. Unlike the password, it is not necessary for the Salt to be kept secret.

You can create your own binary Salt and pass it as the optional parameter IVorSalt. You can pass an iteration count as the optional parameter iterations. The iteration count can be any non-zero integer value. If you specify zero, ColdFusion will use 1,000 iterations (the default value).

For example, to create an 8 byte Salt with the hex value 28e9ac7b748194b0 to use with the PBEWithMD5AndDES algorithm, and also specify 200 iterations

<cfset mySalt = BinaryDecode("28e9ac7b748194b0")><cfset encrypted = Encrypt(myString, "TopSecretPassword123, "PBEWithMD5AndDES", "Base64", mySalt, 200)>

Installing the Sun Unlimited Strength Jurisdiction Policy Files for Java 1.4.2

The Java Runtime Environment included with ColdFusion contains strong, but not unlimited encryption capabilities. In countries where export regulations allow unlimited strength cryptography (most countries), you can download the Sun Unlimited Strength Jurisdiction Policy Files for Java 1.4.2 to increase your available encryption options.

  1. Download the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 1.4.2 from http://java.sun.com/j2se/1.4.2/download.html.
  2. Backup the current contents of your {jre}/lib/security/ directory.
  3. Unzip the file jce_policy-1_4_2-1.zip into your {jre}/lib/security/ directory replacing existing files. Do not preserve directory names when you unzip jce_policy-1_4_2-1.zip.
  4. Restart ColdFusion MX 7.

Installing additional security providers

In addition to the algorithms supplied with ColdFusion, you can install 3rd-party Java Security Providers to use additional algorithms, Feedback Modes, and Padding Methods, as well as additional algorithms for the ColdFusion hash function.

Typically, you place the provider .jar file(s) in {jre}/lib/ext and edit the file {jre}/lib/security/java.security to add the additional provider to the list.

For example, to install the Bouncy Castle Crypto package version 1.26 to a ColdFusion MX 7 Server installed on Windows drive C:

  1. Download the file bcprov-jdk14-126.jar from http://www.bouncycastle.org/latest_releases.html
  2. Place the file bcprov-jdk14-126.jar in C:\CFusionMX7\runtime\jre\lib\ext\
  3. Edit the file C:\CFusionMX7\runtime\jre\lib\security\java.security and add a sixth security provider to the list of five Sun security providers:
    security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider
  4. Restart ColdFusion MX 7.

These additional Block Encryption algorithms will be available:

Algorithm Allowable Key Lengths

(bytes)
Default Key Length

(bytes)
Block Size

(bytes)
CAST5 1 to 16 16 8
CAST6 1 to 32 32 16
IDEA 16 16 8
RC2 1 to 128 16 8
RC4 5 to 256 16 N/A
RC5 1 to 16 16 8
RC6 1 to 32 16 16
Skipjack 1 to 16 16 8
Twofish 16, 24, 32 32 16
Serpent 16, 24, 32 32 16

These additional Feedback Modes will be available:

  • CTR
  • OpenPGPCFB

These additional Padding Methods will be available:

  • ISO10126Padding (or ISO10126-2Padding)
  • X9.23Padding (or X923Padding)
  • TBCPadding

These additional Password Based Encryption algorithms will be available:

  • PBEWithMD5AndRC2
  • PBEWithSHA1AndRC2
  • PBEWithSHA1AndDES
  • PBEWithSHAAnd2-KeyTripleDES-CBC
  • PBEWithSHAAnd3-KeyTripleDES-CBC
  • PBEWithSHAAnd128BitRC2-CBC
  • PBEWithSHAAnd40BitRC2-CBC
  • PBEWithSHAAnd128BitRC4
  • PBEWithSHAAnd40BitRC4
  • PBEWithSHAAndTwofish-CBC
  • PBEWithSHAAndIDEA-CBC

These additional names will be available to use with the ColdFusion hash function:

  • MD2
  • MD4
  • RipeMD128
  • RipeMD160
  • RipeMD256
  • RipeMD320
  • SHA-224
  • Tiger

Note that if you did not previously install the Sun Unlimited Strength Jurisdiction Policy Files for Java 1.4.2, some of the added capabilities will be limited.

For other third-party Java Security Providers, the provider's documentation will list the details of the available algorithms and the class name to be added to java.security.

The following list contains some of the third-party Java Security Providers that are available at the time of this publication:

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy