cfx encrypt aes

CFX_ENCRYPT_AES ™

A Serious Encryption Solution For ColdFusion ®

Users

Installation & User Guide

For Windows, Linux & Solaris

Software Version 5.0 Document cfxaes05.pdf Published 06/01/2003

CFXWorks, Inc. 5365 Chelsen Wood Drive, Duluth, Georgia 30097

Email: [email protected] http://www.CFXWorks.com

Printed in the United States of America.

© 2000 CFXWorks, Inc. All Rights Reserved 1

mailto:[email protected]

http://www.cfxworks.com/

1. INTRODUCTION................................................................................................................................3

1.1. THANK YOU..............................................................................................................................3 1.2. ALERT - UPGRADING FROM PREVIOUS VERSIONS? ...................................................................3 1.3. OVERVIEW ................................................................................................................................3 1.4. COMMON USES FOR ENCRYPTION.............................................................................................4

2. DISCUSSION .......................................................................................................................................5

2.1. WHY USE RIJNDAEL?................................................................................................................5 2.2. HOW SECURE IS RIJNDAEL? ......................................................................................................5 2.3. WHAT IF MY SERVER GETS HACKED? ........................................................................................6 2.4. WHAT IF I FORGET MY ENCRYPTION KEY?.................................................................................8 2.5. WHO USES ENCRYPTION? ..........................................................................................................9 2.6. HOW DO I KNOW THAT CFX_ENCRYPT_AES WORKS? .......................................................9 2.7. IS THERE CONSISTENCY ACROSS VENDORS? ............................................................................9 2.8. CAN DATA BE EXCHANGED BETWEEN WINDOWS, LINUX AND SOLARIS VERSIONS OF THE TAG? 10

3. TECHNICAL ISSUES .......................................................................................................................11

3.1. TAG SPECIFICATION................................................................................................................11 3.2. INSTALLATION ........................................................................................................................12 3.3. ENCRYPTION MODES SUPPORTED ...........................................................................................14 3.4. CFX_ENCRYPT_AES COMPATABILITY ACROSS PLATFORMS .............................................14 3.5. LENGTH OF ENCRYPTED DATA...............................................................................................15 3.6. PERFORMANCE ISSUES ............................................................................................................16 3.7. MESSAGE DIGESTS..................................................................................................................17 3.8. BEST PRACTICES .....................................................................................................................17 3.9. ENCRYPTION KEYS .................................................................................................................18 3.10. MINIMUM SYSTEM REQUIREMENTS ........................................................................................18

4. OTHER STUFF..................................................................................................................................19

4.1. SOFTWARE LICENSE................................................................................................................19 4.2. TECHNICAL LIMITATIONS .......................................................................................................19 4.3. EXPORT LIMITATIONS .............................................................................................................19 4.4. FUTURE POSSIBLE EXTENSIONS ..............................................................................................20 4.5. SUPPORT .................................................................................................................................20 4.6. COPYRIGHT.............................................................................................................................20 4.7. WARRANTY ............................................................................................................................20

APPENDIX A. TAG PARAMETERS .......................................................................................................21

APPENDIX B. ERROR CODES ................................................................................................................24

APPENDIX C. LOG ....................................................................................................................................26

APPENDIX D. SAMPLES ..........................................................................................................................27


1. INTRODUCTION

1.1. Thank You Thank you for purchasing this product. As the author of CFX_ENCRYPT_AES, it is my intent to develop an offering that adds value to your ColdFusion efforts by improving your ability to develop secure solutions. If you feel a need to contact me directly, please send an email to [email protected]. A companion product to CFX_ENCRYPT_AES is CFXAES. CFXAES is a Windows DLL that has been compiled using the using the __stdcall calling convention. Therefore, it should be callable from any programming language capable of calling DLLs using this calling convention. This includes C, C++, VB, Access, Pascal and Fortran. A shared object version of CFXAES is also available for Linux and Solaris.

1.2. Alert - Upgrading From Previous Versions? New users of CFX_ENCRYPT_AES may ignore this alert. Users upgrading from Versions 1-4 of the CFX_ENCRYPT_AES tag, should read Section 3.4 of this document. Section 3.4 is relevant only to users encrypting files. It is not relevant to uses encrypting data.

1.3. Overview CFX_ENCRYPT_AES is a ColdFusion CFX tag that encrypts and decrypts text and files (ASCII and binary) using the Rijndael encryption algorithm. Rijndael is a block cipher (symmetric key) encryption algorithm that supports 128-bit, 192-bit and 256-bit key sizes. This algorithm was selected (10/02/2000) by the National Institute of Standards and Technology (NIST) as the new Federal Information Processing Standard (FIPS) for encryption. Effective 12/04/2001, Rijndael replaced DES as the new FIPs standard. For a detailed discussion of Rijndael, and the Advanced Encryption Standard (AES) selection process, please visit web site http://csrc.nist.gov/encryption/aes/ CFXWorks supports 128-bit, 192-bit and 256-bit key sizes. The size of the key impacts the level of security and the performance of the algorithm. For a discussion of security issues please review Section 2.2. For a discussion of performance please review Section 3.6.



http://csrc.nist.gov/encryption/aes/

1.4. Common Uses For Encryption Encryption is commonly used where it is necessary to transmit or store sensitive information. The following includes examples of data that is commonly encrypted. Credit Card Information Personal Information Card number Address information Name on credit card Phone numbers CVV2 data on card Service numbers Card expiration date Social security numbers Employee Data Medical information Contact information Age Salary data Medical history Performance data Medication


2. DISCUSSION

2.1. Why use Rijndael? The federal government has a new standard for encrypting electronic documents and messages, a code so secure that federal officials predict that its encoded material will remain uncrackable for 20 to 30 years. The Advanced Encryption Standard (AES) received formal approval from Commerce Secretary Donald Evans on December 4, 2001. Rijndael replaces the Data Encryption Standard (DES), which was adopted in 1977. DES can be deciphered with modern computers and decryption methodologies. The Federal Government is expected to require that all agencies within, suppliers to, and contractors and sub-contractors to the federal government use the Rijndael encryption algorithm. The performance characteristics, and form factor (code size), of Rijndael is superior to most other 128-bit algorithms. The security level of Rijndael is thought to be superior to most other currently available 128-bit encryption algorithms. Most of the more secure encryption algorithms have historically been patented technologies. Therefore, they tend to be very expensive. License fees in excess of over $20,000 per system are not uncommon. Contracts for use of this technology also tend to be near impossible to negotiate. The Rijndael encryption technology is not patented. Therefore, Rijndael opens the door to very cost-effective solutions and ease-of-doing-business with the vendor community.

2.2. How secure is Rijndael? To put this issue in perspective, here are some statistics presented by the National Institute of Standards and Technology (NIST) relative to the possibility that someone could crack a 128-bit Rijndael encryption key. http://www.nist.gov/public_affairs/releases/aesq&a.htm "In the late 1990s, specialized "DES Cracker" machines were built that could recover a DES key after a few hours. In other words, by trying possible key values, the hardware could determine which key was used to encrypt a message. Assuming that one could build a machine that could recover a DES key in a second (i.e., try 255 keys per second), then it would take that machine approximately 149 thousand billion (149 trillion)


http://www.nist.gov/public_affairs/releases/aesq&a.htm

years to crack a 128-bit AES key. To put that into perspective, the universe is believed to be less than 20 billion years old."

2.3. What if my server gets hacked? If your server gets hacked, the perpetrator may gain access to your ColdFusion source code. How do you prevent this individual from reading your encryption key from the source code and then using the key to compromise the integrity of your data? Or how would you prevent the hacker from stealing a copy of your tag and a copy of your data, exporting it to another system, and then decoding your data at their leisure? The issue of the securing encryption keys has plagued programmers for many years. It is especially troublesome to programmers who code in languages whose code is stored in source code format on servers, and interpreted at run time. ColdFusion, Visual Basic, ASP, and nearly all script languages have this exposure in common. Even Java, to some extent, has this exposure because it can be reverse compiled to source code. As such, you should assume that any professional criminal, who penetrates your server security, would gain access to your ColdFusion source code. CFX_ENCRYPT_AES provides a solution that hides your encryption key from perpetrators who gain access to your source code. We provide users the ability to embed the encryption key in the tag’s dll. We first provided this capability in a special DOD level version of the tag. The solution appears to be near impossible to hack. Our DOD clients seem to be satisfied with this approach. CFX_ENCRYPT_AES also provides a solution that prevents someone from copying your tag to another system and then using it to decode your data. We also added to the tag, the ability for users to lock their tag to a specific system using the MAC address of one of the Ethernet cards installed in their system. With this feature enabled, the tag will execute only on the system that has your Ethernet card installed in it. Since every Ethernet card has a unique MAC address, and the MAC address cannot be modified, this prevents someone from stealing a copy of your tag and using it elsewhere to decode your data. These two optional features of the tag are enabled as follows. We distribute with our tag, a utility program that has the ability to read and modify the “cfx_encrypt_aes” executable. For Windows this utility is “atouch.exe”. For Linux and Solaris, this utility is “atouch”. The atouch utility program has four parameters:


• /kkeyword - where “keyword” is the keyword used to generate the default encryption key to be embedded in the tag.

• /mmac - where “mac” is the MAC address exactly as displayed when you enter the command “ipconfig /all” at a DOS prompt. This field is case sensitive.

• /ifilein - where “filein” is the name of the dll being modified. By default this is “cfx_encrypt_aes.dll”

• /ofileout - where “fileout” is the name of the output file. By default this is cfx_encrypt_aes.dll.

The /k field is required. All other fields are optional. The /m parameter is currently supported only on the Windows platform. It will be added to the other platforms we support in the near future. If your system has more than one Ethernet card, you can use the MAC address of any of the Ethernet cards as the /m parameter. The /m parameter is currently supported only on Windows platforms. This is because on Linux and Solaris, only programs executing under Super User can access the MAC address information. In many instances, ColdFusion is not run under Super User. We are working this issue and hope to find a work around. MAC addresses are case sensitive. Therefore it is important to enter the MAC address exactly as it is recorded. If more than one Ethernet card is installed on your system, you can use the MAC address of any of the cards installed. The atouch utility takes the user provided keyword, digests it using MD5 to create an encryption key, then encodes it and adds it to the tag’s executable file. It also takes a user provided MAC address and adds it to the tag. Then it calculates and adds a new digital signature to the executable. The purpose of the digital signature is that if a perpetrator modifies the executable, the embedded digital signature will be different than that calculated at run time, and any attempt to use the tag will be aborted. The key added to the cfx_encrypt_aes tag is used only if the KEY parameter is not coded in the call to the executable. Therefore, it functions as a default KEY value. The effect of using this technique is that your KEY is never visible in your ColdFusion source code. Also, it is not visible in the executable. Therefore, the integrity of your KEY value is protected.


To use the “atouch” utility, perform the following steps.

1. Copy the “atouch” utility to the directory where the cfx_encrypt_aes executable resides.

2. Execute the command “atouch /kyourpassword /myourmacaddress /ifilein /ofileout”. For example, to add 123456 as your keyword, and 08-65-43-0F-12-98 as your MAC address, enter the command “atouch /k123456 /m08-65-43-0F-12-98 /icfx_encrypt_aes.dll /ocfx_encrypt_aes.dll”. For Linux, and Solaris the command would be “atouch /k123456 /m08-65-43-0F-12-98 /icfx_encrypt_aes.so /ocfx_encrypt_aes.so”.

3. The command would respond similar to the following: aTouch Utility Release 2.0 12/15/2002 Copyright 2002 CFXWorks, Inc. Input Parameters Keyword - 123456 Encryption Key - e10adc3949ba59abbe56e057f20f883e MAC - 08-65-43-0F-12-98 Filein - cfx_encrypt_aes.dll Fileout - cfx_encrypt_aes.dll Password and MAC address successfully added to DLL!

4. Erase the “atouch” utility from your system. Note the subtle difference displayed for the values for “Keyword” and “Encryption Key”. You entered the “Keyword” value. The utility calculated the “Encryption Key” value. You need to remenber both values for future reference. Write down both values and don’t forget them! The keyword can’t be reversed engineered. You can cross check the results of using, or not using, the KEY parameter in your call to the tag. If you code the encryption key displayed above in a KEY parameter, and pass it to the tag, you will get the same encryption/decryption results as you would if you didn’t code the KEY when calling the tag. If you need to reset the keyword or MAC address, you can rerun the atouch utility.

2.4. What if I forget my encryption key? Rijndael is a very serious encryption algorithm. Hackers are not likely in our lifetime, to be able to compromise this algorithm unless of course, they guess your encryption key. That, is good news to white hatters (the good guys). Also, there are no known back doors to this algorithm. The bad news is that if you forget your encryption key, there is absolutely no way


that CFXWorks, or any other organization known to exist, can bail you out! If you forget you encryption key, you should assume that your data is lost forever!

2.5. Who uses encryption? An article published in the October 15th issue of InformationWeek reported that according to the 2001 Global Information Security Survey conducted by Pricewaterhouse-Coopers, 24% of companies worldwide and 27% in the United States are encrypting data for transmission and storage. A separate survey fielded by InformationWeek Research with the President’s Export Council Subcommittee on Encryption surveyed 500 sites. Two-thirds reported using encryption to protect company data. 43% used encryption on both stored and transmitted data.

2.6. How do I know that CFX_ENCRYPT_AES works? FIPS 197 is very precise in defining precisely how the Rijndael algorithm must function. This document also defines several example test vectors to be used to validate correct implementation of the 128-bit, 192-bit and 256-bit standard. CFX_ENCRYPT_AES has been validated using these test vectors. Our test suite includes over 600 test cases that we use to validate our results.

2.7. Is there consistency across vendors? The original reference documentation for Rijndael allowed for multiple key sizes, multiple block sizes, and multiple block ordering techniques. The result was that there are many, approximately 100, “valid” ways that the Rijndael algorithm can be applied to encrypting/decrypting data. Different choices produce different results. Therefore, it is possible that one vendor’s implementation of Rijndael may yield different results than another vendor’s implementation based on the assumptions made relative to these parameters. For implementation of CFX_ENCRYPT_AES, I choose the blocksize (16 byte), key size (128-bit, 192-bit and 256-bit) and byte ordering technique (Little-Endian) defined in the FIPS 197 publication for use with the reference test vectors. I also decided not to include in the encrypted data, the trailing ‘\0’ character that terminates character strings in many programming languages, including ColdFusion. This also appears to be the


practice in the validation suites. It also appears to be the practice in ColdFusion Release 5 in the Hash() and Base64() functions supported in this release. The results obtained from different vendors should be consistent if the same assumptions are made and the algorithm is working properly.

2.8. Can data be exchanged between Windows, Linux and Solaris versions of the tag? The Windows, Linux and Solaris versions of the tag produce identical results for both data and files, if the input is identical. Therefore, CFX_ENCRYPT_AES encrypted data or files that are identical in content can be exchanged between Windows, Linux and Solaris when using this tag. Note that files created by user applications, are generally not compatible on a cross platform basis. In particular, ASCII files created under Windows are not compatible with ASCII files created under Linux or Solaris. ASCII files are generally compatible across Linux and Solaris. Binary files may or may not be compatible across these platforms depending on machine architecture and a number of variables.


3. TECHNICAL ISSUES

3.1. Tag specification The programming specification for the CFX_ENCRYPT_AES tag is as follows:

<CFX_ENCRYPT_AESDefault

ACTION="et" encrypt text et"dt" decrypt text"etx" encrpt text (hex)"dtx" decrypt text (hex)"ef" encrypt file"df" decrypt file"etf" encrypt text to file"dft" decrypt text from file"key0" generate a numeric key"key1" generate a lower case alpha key"key2" generate an upper case alpha key"key3" generate a key using numeric, lower case alpha and upper case alpha"key4" generate a key using numeric, lower case alpha, upper case alpha and special characters

KEY="encryption key" 16 byte key fro 128-bit encryption none 24 byte key fro 192-bit encryption none 32 byte key fro 256-bit encryption none

DIGEST="yes or no" result contains a MD5 message no digest.

TEXT="text" input if action = et,dt,etf or df none

NAME="RESULT" output if action = et,dt,dft "TEXT"

FILEIN="filein" input file if action = ef,df, or dft "filein.txt"

FILEOUT="fileout" output file if action = ef,d or etf "fileout.txt"

CBC="yes" yes - use CBC encryption mode "no" no - use ECB encryption mode

IV="546789" initialization vector for CBC mode "9762852146286582"

COMP="yes or no" file format for encrypted files yes yes - big endian (Windows, Linux and Solaris) no - little endian (Windows and Linux only)

DISPLAY=0,1 or 2 0 - Display nothing 0 1 - Display Log 2 - Write lof to disk file "aes.log"

>

Reply:RESPONSE see Appendix BRC= see Appendix B

0 -Zero length input n - Length of output data or file

- 1 Invalid ACTION - 2 Invalid KEY- 3 FILEIN error - 4 FILEOUT error- 5 Memory error - 6 Data integrity error- 7 NAME error - 8 Invalid value in KEY attribute

- 9 Invalid value in - 99 License error TEXT attribute

Figure 1 - ColdFusion Tag


For a detailed discussion of CFX_ENCRYPT_AES parameters, please see Appendix A. Tag Parameters. For a detailed discussion of CFX_ENCRYPT_AES error codes please see Appendix B. Error Codes. For a discussion of the contents of the log if “DISPLAY=2” is specified, please see Appendix C. Log. For specific examples of how to deploy this tag, please see Appendix D. Samples.

3.2. Installation The CFX_ENCRYPT_AES installation process is a simple three-step process:

1. CFX_ENCRYPT_AES is distributed as zip file (filename.zip). The actual filename is specific to each licensee. You will need a “password” to unzip this file. The password is sent to the licensee by email when the tag is ordered. The command you must enter at a command line is as follows:

Windows: pkunzip filename –s[password] Linux: unzip –j filename Solaris unzip –j filename

Note that commands and filenames in Linux and Solaris are case sensitive. The “-j” in the above Linux and Solaris commands stand for ”junk“, or do not make directories. Without this parameter, the unzip command will create subdirectories within the current working directory. On Linux and Solaris, after you have unzipped the zip file, you will have to use the “chmod u+x cfx_encrypt_aes.so” command to make this file executable. When you unzip this file, the code and documentation is extracted to the current working directory. The zip file contains the following files:

• CFX_ENCRYPT_AES.dll (Windows) or “cfx_encrypt_aes.so”

(Linux and Solaris) – the tag’s executable. • AES0.cfm – sample program text-2-text encryption. • AES1.cfm – sample program file-2-file encryption. • AES2.cfm – sample program text-2-file encryption. • AES3.cfm – sample program that generates a random key. • LICENSE_AES.pdf – a copy of the software license. • ATOUCH.exe (Windows) or “atouch” for Linux and Solaris –

utility described in section 2.3. • CFXAES05.pdf – this document.

2. On versions of Coldfusion prior to MX, ColdFusion recommends that you copy the CFX_ENCRYPT_AES executable to the \CFUSION\CFX directory for execution. This wasn’t absolutely necessary, but it was best practices. On Windows versions of MX, this directory would be


\CFusionMX\CustomTags\cfx. On Linux and Solaris, this directory would be /opt/coldfusionmx/cfx.

3. ColdFusion also requires you to register the tag using the ColdFusion

Administrator. The registration dialog will look similar to the following:

Figure 2- Registering CFX_ENCRYPT_AES

You should name the tag as shown in the Figure 2. You must tell ColdFusion where the executable is stored. For performance reasons you should select “Keep library loaded” however this is not required if the tag will not be in heavy use. You can enter a description as shown above. For Windows, if you do not check the “Keep library loaded” checkbox, the dll is reloaded each time the tag is executed. Therefore, if you install a new version of the dll, it is automatically refreshed at runtime. On Linux and Solaris, if you install a new version of the executable, you must stop and start the Coldfusion server to refresh the executable. That’s it! The entire installation process should take only a few minutes to complete.


3.3. Encryption modes supported This tag supports two modes of encryption. The default mode is ECB (Electronic Block Mode). With this mode the cipher takes a single block of plaintext and produces a single block of ciphertext. Data streams are broken into blocks that are individually processed. Each block is 16 bytes long. The cipher pads short blocks. Padding is added when the data is encrypted. Padding is removed when the data is decrypted. The tag also supports the CBC (Cipher Block Chaining) mode of encryption. The CBC mode is considered more secure than the ECB mode for encrypting messages over one block long (16 bytes). In CBC mode the plaintext is XORed with the previous ciphertext block before it is encrypted. After a plaintext block is encrypted, the resulting ciphertext is stored in a feedback register. Before the next plaintext block is encrypted, it is XORed with the feedback register to become the next input to the encrypting routine. The resulting ciphertext is again stored in the feedback register, to be XORed with the next plaintext block, and so on until the end of the message. The encryption of each block depends on all previous blocks. Each block is 16 bytes long. The cipher pads short blocks. Padding is added when the data is encrypted. Padding is removed when the data is decrypted. In CBC mode, for encrypting the first block of data, the feedback register is seeded with a value called the IV (initialization vector). The IV has no meaning; it is just there to make each message unique. The IV value must be supplied to both the encryption and decryption routine. The IV need not be secret, however, you must remember the IV value, just as you must remember you encryption key. To use the CBC mode just code the CBC=”yes” parameter when calling the tag. If you elect to use CBC to encode, you must also elect CBC to decode. If you do not code an IV, the tag will provide a default IV value, 9762852146286582, for you. You can provide your own IV value by coding the parameter IV=”value”. Technically, the value can be 1-16 alphanumeric characters long. We suggest that you provide a value 16 bytes long. Remember that if you provide an IV value to encode, you must provide the same IV value to decode.

3.4. CFX_ENCRYPT_AES compatibility across platforms

We have found that many users have multiple systems running ColdFusion and want to share encrypted files and data across Windows, Linux and Solaris platforms.


Sharing data across platforms is an issue because the internal architecture of some systems may be different causing them to store data in different formats. Specifically, Sun’s SPARC processors store numerical data in a format referred to as “big endian”. Intel stores numerical data in a format referred to as “little endian”. With the addition of Solaris support in Version 5 of the tag, we added a new tag parameter “COMP”. This new parameter gave us the ability to continue support for Windows and Linux users with the current file format (little-endian), but give Windows and Linux users the ability to create Solaris compatible (big endian) encrypted files. Starting in Version 5 of this tag, we elected to make the default file format big endian because it is most suited for cross platform sharing. Therefore, users wanting to access encrypted files from Version 1-4 of the CFX_ENCRYPT_AES tag, must code the parameter COMP=”no”. The default value for this parameter, “COMP=”yes”, will read and write files using the big endian format. We apologize for the inconvenience that this may cause some users, but we thought that now was the best time to implement this change.

3.5. Length of encrypted data The Rijndael encryption algorithm generally increases the length of encrypted data as compared to the length of the original input data. In particular, you need to be aware of this if you are using the encrypt text option (ACTION=”et”). Why? If the encrypted data is to be stored in a database, the column within the database must support the length of the encrypted data. Length For ACTION=”et” The length of the encrypted data can be calculated as follows:

• With Rijndael generally the length of encrypted text (output) is longer

than the length of clear text (input). Rijndael always rounds upward, to a 16-byte boundary. For example, a 3-byte character string is rounded up to 16 bytes. A 16-byte character string remains 16 bytes. A 23-byte character string is rounded up to 32 bytes.

• If the parameter “DIGEST” is specified, 16 characters are added to the

length of the input data string.

• Encrypted data strings may contain non-ASCII characters and reserved characters that ColdFusion may misinterpret. Therefore, CFX_ENCRYPT_AES translates encrypted data strings to hex to


protect their integrity. This translation doubles the length of the resulting data. The following formulas apply: Encryption Without Message Digest length of result = (length of input data)(rounded upward) * 2 Encryption With Message Digest length of result = (length of input data + 16)(rounded upward) * 2 Example (128-bit encryption):

Length Input Data

Length of Digest

Length Encrypted

Output W/O

Digest

Length Encrypted

Output With

Digest1-16 16 32 64 17-32 16 64 96 33-48 16 96 128 49-64 16 128 160 65-80 16 160 192 81-96 16 192 224

Length For ACTION=”ef” and “etf” There is no need to translate as described above, encrypted data that is stored in files. Therefore, encrypting a file “ef”, or encrypting text and storing it in a file “etf”, results in a file only slightly larger than the original data. The length is simply rounded up to a 16-byte boundary as described above.

3.6. Performance issues One of the major issues with all encryption algorithms relates to performance. CFXWorks has performed extensive performance measurements on many encryption algorithms with varying message lengths, key sizes, and block sizes. We also tested across several development platforms and environments. We believe that in a ColdFusion environment, the following issues should be considered relative to performance:

• The primary issue impacting performance will be the selection of the installation option “Keep library loaded”, see Figure 2. If this option is not selected, the CFX_ENCRYPT_AES dll is loaded each time the tag is


referenced. Therefore, the major issue impacting performance of the tag will be I/O speed.

• The next issue impacting performance will be the length of data being

encrypted. The longer the data string or file, the more CPU cycles will be consumed performing encryption and decryption.

• Our tests show only minor differences in performance between 128-bit,

192-bit, and 256-bit implementations of this tag on a given system.

• Our tests show that the ECB mode of encryption is 5-10% faster than the CBC mode.

3.7. Message Digests Encryption is intended to protect the confidentiality of data. However, how do you determine if a black hat (bad guy) has changed the contents of an encrypted data string or data file? Changing data content relates to data integrity, not data confidentiality. The solution to this issue is what cryptologist call message digests. CFX_ENCRYPT_AES uses MD5, a best of breed message digest algorithm, to calculate message digests. If “DIGEST=YES” is coded, a message digest is calculated and concatenated to the data string. Then, the total string is encrypted. This forms a digital envelope. When the data is decrypted, the message digest is recalculated and compared to the original value. If even a single bit within the encrypted string or file has been modified, the comparison fails and CFX_ENCRYPT_AES returns an error code (–6 data integrity error). Please see Appendix B. Error Codes.

3.8. Best Practices The probability that anyone would be capable of directly compromising the integrity of the Rijndael algorithm is thought to be next to zero. Please refer to the comments in Section 2.2 of this document. However, the integrity of any encryption algorithm relies on the user to protect the confidentially of the encryption key and to select keys that are not easily guessed. For example, if user “John Doe” selects as his encryption key “john”, it isn’t going to take long to guess the password. As a rule of thumb, select a key that is the maximum length allowed. For example, for 128-bit encryption, select a key that is 16 characters long. A key comprising of only a single type of character is sufficient for most purposes. The safest key would be a key containing a mix of upper case alpha, lower case alpha, numeric


and special characters. This combination would make the key more difficult to guess.

3.9. Encryption Keys Encryption keys vary in length depending on the level of encryption used:

For 128-bit encryption 16 byte key For 192-bit encryption 24 byte key For 256-bit encryption 32 byte key

The CFX_ENCRYPT_AES tag provides a key generation routine that is based on one of the better random number generation routines. Calling the tag using the ACTION=”key0-key4” parameter will randomly generate a key of the proper length. The result is returned in the “KEY” parameter. The example “aes3.cfm” demonstrates the use of the CFX_ENCRYPT_AES tag to generate a key. Special rules that apply to key values:

1. If a KEY value is not supplied, or is blank (“”), the tag uses a key filled with hex “00”s.

2. KEYs must contain only valid ASCII characters. The exception is for ACTION=”etx or dtx”.

3. If ACTION=”etx or dtx” is used, the supplied KEY and TEXT fields must contain valid hex encoded data. If not, the tag will return an error code and abort the requested action.

4. If ACTION=”etx or dtx” is used, SIGNATURE=”NO” is assumed.

3.10. Minimum System Requirements The tag has been tested on Windows 2000, Linux (Red Hat), and Solaris 8.0 platforms. The Windows version should function properly on all Win32 platforms. The Linux version should function on all Intel versions of Linux. The Solaris version of the tag should function on Solaris 8 and 9 running on SPARC processors. The tag requires that it be installed on a system using a properly configured copy of ColdFusion 4.0, 4.5, 5.0 or MX.


4. OTHER STUFF

4.1. Software License Demonstration tags contain expiration dates that expire in 30 days. Purchased tags have no expiration date. The tag is licensed on a per system basis. The license agreement is contained in the product distribution zip file. Please read this pdf file for detailed license information. Encryption will not be performed and a message digest will not be created on demo versions of the tag whose license has expired. In other words, if the license has expired, the output of the tag will be an image of the input. If the input is in clear text, the output will be in clear text.

4.2. Technical Limitations The Rijndael algorithm has not been modified in any way from the algorithm published on the NIST web site. Considerable work has been performed to package and test this code as a ColdFusion tag. CFX_ENCRYPT_AES has been tested extensively on message strings from 0-65536 characters in length and for file sizes up to 2 Mbytes in size. There is no technical reason we know of, that messages or files exceeding these values will not function properly however, we do not test beyond these limitations.

4.3. Export Limitations This tag software contains encryption technology that is subject to the U.S. Export Administration Regulations and other U.S. law, and may not be exported or re-exported to certain countries (currently Afghanistan (Taliban-controlled areas), Cuba, Iran, Iraq, Libya, North Korea, Serbia (except Kosovo), Sudan and Syria) or to persons or entities prohibited from receiving U.S. exports (including Denied Parties, entities on the Bureau of Export Administration Entity List, and Specially Designated Nationals). For more information on the U.S. Export Administration Regulations http://www.bxa.doc.gov/Encryption/regs.htm, 15 C.F.R. Parts 730-774, and the Bureau of Export Administration U. S. Department of Commerce. Please see the home page www.bxa.doc.gov


http://www.bxa.doc.gov/Encryption/regs.htm

http://www.bxa.doc.gov/

4.4. Future Possible Extensions Please send us your suggestions. We are particularly interested in your feedback as to creative ways to use the CFX_ENCRYPT_AES capability.

4.5. Support Support is provided for this offering via the CFXWorks web site www.CFXWorks.com. A Q&A forum is maintained and CFXWorks will attempt to respond to emails addressed to [email protected] on this forum.

4.6. Copyright Some of the code used in CFX_ENCRYPT_AES to implement the Rijndael algorithm, includes the following copyright notice: Copyright (c) 2001, Dr Brian Gladman <[email protected]>, Worcester, UK.

All rights reserved.

4.7. Warranty Please read the license file “license.pdf” in the distribution zip file.


http://www.cfxworks.com/


APPENDIX A. TAG PARAMETERS Parameter Default Value Requred DescriptionACTION = “et” “et” optional Encrypt text. “dt” Decrypt text.

“etx” Encrypt text supplied (1) in hex format using a key supplied in hex format.

“dtx” Decrypt text encrypted (1) using “etx” using a key supplied in hex format.

“ef” Encrypt file. “df” Decrypt file. “etf” Encrypt text to file. “dft” Decrypt file to text. “key0” Generate numeric key. “key1” Generate lower case

alpha key. “key2” Generate upper case alpha key. “key3” Generate a key with

numeric, lower case alpha and upper case alpha

“key4” Generate a key with numeric, lower case alpha, upper case alpha and special characters

KEY = “key” none required 16 character for 128-bit

24 character for 192-bit 32 character for 256 bit

DIGEST = “yes” or “no” “no” optional Yes – add message digest. No – Don’t add digest. TEXT = “Text to be encrypted” none required for Null terminated text string. “et” & “etf” NAME = “RESULT” “TEXT” optional Null terminated text string. FILEIN = “filename” “filein.txt” required for Fully qualified file name (2). “ef”, “df”

& “dft”


FILEOUT = “filename” “fileout.txt” required for Fully qualified file name(2). “ef”, “df”

& “etf” CBC = “yes” “no” optional yes – use CBC encryption mode. no – use EBC encryption mode. IV=”456345” "9762852146286582" optional initialization vector for

CBC mode. 1-16 alpha numeric characters

COMP="yes or no" “yes” optional file format for encrypted files “yes” - big endian (Windows, Linux and Solaris) “no” - little endian (Windows and Linux only) DISPLAY = value 0 optional 0 – no display 1 – display log 2 – create a disk log (3).

(1) Actions “etx” and “dtx” are special case capabilities that under normal circumstances have limited use for ColdFusion programmers. They were added to CFX_ENCRYPT_AES because the FIPS 197 standard defines certification vectors that require using KEY and TEXT values that include non-ASCII characters that are not valid in ColdFusion. If “etx” and “dtx” are used, please remember that if the text to be encrypted contains short blocks, the length is not a multiple of 16, the last block is right filled with hex ‘00”s. Also note that both the KEY and TEXT values must be supplied using hex notation. (2) If a fully qualified filename is not specified, the file is read from and written to the current working directory for ColdFusion. This directory most likely is c:\winnt\system32. If you execute the tag using DISPLAY=1, the current working directory will be displayed. (3) The log is written to the current working directory of ColdFusion using the filename “aes.log”.


Figure 3 provides a cross reference between the “ACTION” selected and the parameters supported.

ACTION

PARAMETERET DT EF DF ETF DFT KEYn

ACTION D O O O O O O

KEY R R R R R R X

DIGEST O O O O O O NA

TEXT R R NA NA R X NA

NAME O O NA NA NA O NA

FILEIN NA NA R R NA R NA

FILEOUT NA NA R R R NA NA

CBC O O O O O O O

IV O O O O O O O

COMP NA NA O O O O NA

DISPLAY O O O O O O O

RESPONSE X X X X X X X

RC X X X X X X X

O - Optional ParameterR - Required ParameterX - Output ValueNA - Not Applicable

Figure 3 - Tag Parameters Versus ACTION


APPENDIX B. ERROR CODES RC Description Action of tag0 A return code of 0 indicates that the length of the

input string or data file is 0. Output is created with a zero length. For example with a text value of “” or with a file of zero length.

n A positive value indicates that the encoding or decoding task has been successful.

The value is the length of the output text or file.

-1 Invalid ACTION parameter. The tag takes no action. -2 Invalid key parameter. A non-ASCII character was

found in the key. The actual key used by CFX_ENCRYPY_AES is 16 characters long for 128-bit encryption, 24 characters long for 192-bit encryption, and 32-bits long for 256-bit encryption. If the key parameter is longer than necessary, the leftmost characters are used. If the value supplied is less that that required, the right most values in the key are filled with hex “00”.

No output is created.

-3 FILIIN error. Most likely the file cannot be found or the directory specified does not exist.

The status of the output text or file is unknown.

-4 FILEOUT error. Most likely the directory or drive specified does not exist.

The status of the output text or file is unknown.

-5 Memory allocation error. This means that you do not have enough memory on your system to complete the encoding/decoding task.

The input is copied to the output unchanged.

-6 Data integrity error. This means that the contents of an encoded data string or file has been modified.


-7 Invalid NAME. This means that the variable name passed to the tag contained blanks or non-ASCII characters.


-8 Invalid HEX Value. This means that the KEY attribute contains an invalid hex value. This error message applies only when ACTION=”etx or dtx” has been specified.


-9 Invalid HEX Value. This means that the TEXT attribute contains an invalid hex value. This error message applies only when ACTION=”etx or dtx” has been specified.


-99 License error. This means that an attempt to execute the tag has occurred on an unlicensed system. The tag is executed, however, no encoding or decoding is performed.

The input is copied to the output unchanged


Figure 4 provides a cross reference between return codes and actions.

ACTION

RETURN CODE ET DT EF DF ETF DFT KEYn

Zero length input (1) 0 x x x x x x

Length of output (2) n x x x x x x x

Invalid ACTION -1 x x x x x x x

Invalid KEY -2 x x x x x x

FILEIN error (3) -3 x x x

FILEOUT error -4 x x x

Memory error -5 x x x x x x x

Data integrity error -6 x x x

NAME error -7 x x x

Clear text passthru (4) -99 x x x x x x x

x - Possible RC "blank" - not possible for this ACTION

Value

Figure 4 – Error Codes Versus ACTION


APPENDIX C. LOG The “DISPLAY=2” option causes CFX_ENCRYPT_AES to create a log. This option should be selected only for debugging purposes. It will seriously degrade performance. Figure 5 reflects what is written to the log for each of the ACTIONS selected.

LOG CONTENTDISPLAY=2 ET DT EF DF ETF DFT KEYn

Setup data x x x x x x x

License data x x x x x x x

Tag parameters x x x x x x x

Input text x x x

Output text x x x

Users who have problems should eMail a copy of their log, and a copy of both the input and output files, if applicable, to [email protected].

Figure 5 - Log Content Versus ACTION


APPENDIX D. SAMPLES Figure 6 illustrates just how simple it is to use this tag.

Example:<CFX_ENCRYPT_AES

ACTION="et"KEY="asdoinjreroycdnw"TEXT="This is the data to be encrypted"NAME="RESULT">


ACTION="ef"KEY="asdoinjreroycdnw"FILEIN="filea"FILEOUT="fileb">


ACTION="etf"KEY="asdoinjreroycdnw"TEXT="This is the data to be encrypted"FILEOUT="bfile">

Figure 6 - Samples

The CFX_ENCRYPT_AES distribution files contain the following sample programs. “aes0.cfm” This sample program encrypts and decrypts a text string using the ECB

mode. “aes1.cfm” This sample program encrypts file-to-file and performs the

reverse operation using the ECB mode. This example assumes the presence of some directories and a file that may not be valid on your system. Please modify these values to the correct values for your system.

“aes2.cfm” This sample program encrypts a text string to a file and performs the

reverse operation using the ECB mode. This example assumes the presence

of a directory that may not be valid on your system. Please modify these values to the correct values for your system.

“aes3.cfm” This sample program generates a key and encrypts and decrypts a text string using this key. It uses the ECD mode of encryption.


“cbc_aes0.cfm” This sample program encrypts and decrypts a text string using the

CBC mode. “cbc_aes1.cfm” This sample program encrypts file-to-file and performs the

reverse operation using the CBC mode. This example assumes the presence of some directories and a file that may not be valid on

your system. Please modify these values to the correct values for your system.

“cbc_aes2.cfm” This sample program encrypts a text string to a file and performs

the reverse operation using the CBC mode. This example assumes the presence of a directory that may not be valid on your system. Please modify these values to the correct values for your system.

“cbc_aes3.cfm” This sample program generates a key and encrypts and decrypts a

text string using this key. It uses the CBC mode of encryption.


cfx encrypt aes

Documents