MD5 Hashing Xtra v1.1
Copyright © 2003-2004 by Chieh An Lu
This document was last revised on May 17, 2004. For the most up-to-date documentation, please use the online docs at http://xtras.calu.us
Table of Content
Usage Terms
System Requirements
Overview
Security In Macromedia Director
How to use MD5 Hashing Xtra
caluMD5_register( )
new( )
getFileMD5( )
getStringMD5( )
getLastError( )
Inside the Director Demo File
Support Information
Version History
This End-User License Agreement("EULA") is a legal agreement between you and Calu software, please read it carefully.
YOU AGREE TO BE BOUND BY THE TERMS OF THIS EULA BY INSTALLING THIS PRODUCT. IF YOU DO NOT AGREE, DO NOT INSTALL THIS PRODUCT.
Calu software makes no representations concerning either the merchantability of this software or the suitability of this software for any particular purpose. It is provided "as is" without express or implied warranty of any kind. In no event is Calu software liable for any damage, including profit loss, and/or any other incidental or consequential damage. There may be errors in this software or its documentation and examples. You agree to bear all risks by agreeing to use this xtra.
You may not sell this xtra for profit and this document must accompany all source file distributions of the MD5 Hashing xtra .
Macromedia Director 7, 8, 8.5 and MX, MX2004
Microsoft Windows 98, ME, NT, 2000, XP or Macintosh 9.2 or Macintosh OSX
This has also been reported to work on Macromedia Authorware 6.
(a) MD5 was developed by Professor Ronald L. Rivest of MIT. What it does, to quote the executive summary of rfc1321 , is:
[The MD5 algorithm] takes as input a message of arbitrary length and produces as output a 128-bit "fingerprint" or "message digest" of the input. It is conjectured that it is computationally infeasible to produce two messages having the same message digest, or to produce any message having a given pre specified target message digest. The MD5 algorithm is intended for digital signature applications, where a large file must be "compressed" in a secure manner before being encrypted with a private (secret) key under a public-key cryptosystem such as RSA
In layman Director user terms, it means that MD5 is a quick tool at creating digital fingerprints. Using MD5 for security is much more secure than any encryption algorithm that are currently available for Director users. Using MD5 for file authenticity is much more reliable than CRC. Since MD5 creates a one way hash, it is not suitable for situations where decryption to the source is necessary. One way hashing is often used for comparing a message against a key to verify that the message have not been tampered with.
For more information on MD5, visit RSA at http://www.rsasecurity.com/rsalabs/faq/3-6-6.html .
(b) Some possible uses of this xtra
- Verifying the completeness of a downloaded file
- Create "signatures" to passwords for security
- Check for file differences
- Check for file tampering
- Check for the authenticity of a message
As Director developers, we know that ".dir" files contains no encryption thus it is never an option to distribute ".dir" files to clients. For distribution, files need to be converted into protected ".dxr" files, or ".exe" files. Anyone who has tried creating several executables know that this is a repetitive and painful process. Using stub projectors to launch "dxr" file is much more convenient. The dangers of using dxr is that all your assets are vulnerable to eavesdroppers. One can easily create a MIAW to copy bitmaps, vectors, text, field..etc, from the protect movie, but the source code (scripts) are never revealed. This is adequate security for most cases because hackers will have little use of the movie assets without the source code. Anyone who believes that "dxr" files are secure should read this carefully.
Try opening your "dxr" file in a hex editor and you will find lots of binary garbage, however if you look carefully, there are noticeable amounts of ascii text remaining. For example, your script handlers names are not encrypted. Even worse, look carefully and you will see the string constants in your source code are exposed too. String constants are anything in your script that is in between the 2 quotes marks. For example, consider the following lingo code
password = "hello world"
the string constant, "hello world" , is stored as it. This means that if you were to create a director movie with password validation, your password is exposed to the eavesdropper. To help avoid issues such as storing string constants in your Director movie, simply use the the MD5 Hashing Xtra. Read "Inside the demo file" to see how MD5 Hashing Xtra can help you.
Place a copy of MD5 Hashing Xtra into Macromedia Director's Xtra folder. For further instructions, check tech note ID 14888 at http://www.macromedia.com/ .
Function and methods in the xtra:
To check for the functions and methods in the MD5 Hashing Xtra , type the following into Director's message window:
put xtra("caluMD5").interface()
The possible function/Methods are:
- new()
- getFileMD5(string filePath )
- getStringMD5(string encodeText )
- getLastError()
- caluMD5_register(string user, string code)
Usage:
caluMD5_ register( user, registerCode )
Parameters:
user : (string) "I"
registerCode : (string) "agree with the usage terms"
Examples:
caluMD5_ register( "I","agree with the usage terms")
Returns:
boolean
(1) Registration successful
(2) Registration failed
Notes:
(1) While I'm giving away this MD5 Hashing Xtra for free, I do ask that you read and agree with the usage terms set forth in this document. In order to use this Xtra , you MUST agree with the usage terms. Copy the code in this example into your Director script prior to calling any other functions in MD5 hashing Xtra .
(2) Note that his function is a global Director handler, which means that it doesn't need to be instantiated prior to usage. This is the only function in this xtra that is in global scope.
Creates an instance of the MD5 Hashing Xtra
Usage:
new ( object me )
Parameters:
None
Examples:
xtra_md5 = xtra("caluMD5").new()
Returns:
A reference to an instance of the MD5 Hashing xtra .
Derives the MD5 hash value from the contents of a file.
Usage:
getFileMD5 ( object me, string filePath )
Parameters:
filePath : (string), the absolute path to a file
Examples:
Windows:
xtra_md5 = xtra("caluMD5").new()
md5Value = xtra_md5.filePath("C:\Program Files\Macromedia\Director 8.5\Readme.htm")
Macintosh:
xtra_md5 = xtra("caluMD5").new()
md5Value = xtra_md5.filePath("Macintosh HD:Applications:Macromedia Director MX:ReadMe.htm")
Returns:
(1) returns the MD5 hash value if the encoding was successful
(2) returns an empty string if there was a error. Use getLastError ( ) for more information.
Derives the MD5 hash value from a string.
Usage:
getStringMD5 ( object me, string encodingText )
Parameters:
encodingText : (string), the text that you wish to hash into a MD5 value.
Examples:
xtra_md5 = xtra("caluMD5").new()
passwordHashed = xtra_md5.getStringMD5("hello world")
Returns :
(String) - MD5 hash value.
Gets the error number from the previous operation
Usage:
getLastError ( object me )
Parameters:
None
Examples:
xtra_md5 = xtra("caluMD5").new()
passwordHashed = xtra_md5.getStringMD5("hello world")
nError = xtra_md5.getLastError( )
Returns :
(Integer) - an error code
Notes:
Error code : -5
Meaning: Xtra has not been registered.
Resolutions : read caluMD5_register
Error code: -4
Meaning: Error in file hashing. Probably because file is in use
Resolution: Try using another utility like fileXtra to make a copy of the file to another location and try hashing again.
Error code: -2
Meaning: String is not a valid path to a file.
Resolution: check that your path is valid.
Error code : -1
Meaning: File path parameter string is over the Windows legal limit of 259 characters
Resolution : check that your path is valid.
A director demo movie is provided to illustrate the use of the MD5 hashing xtra. Some of the examples in the movie makes frequent use of fileIO xtra and fileXtra 4. All xtras used in the demo can be downloaded and distributed for free.
The 3 examples in the movie demonstrate some possible uses of this xtra.
Examples 1 and 2 demonstrates the concept of file authentication. File authentication is frequently used to detect file tampering or file corruption. When you need to store files externally such as game's high scores or current game progress, it is recommended to also store the MD5 value. You can later detect if the end user physically tampered with your file. When downloading files, it is also important to verify that the file was not damaged during the download process. Do not always believe that the TCP/IP protocol will verify this accurately every time. TCP/IP works most of the time, but errors can still go undetected in the TCP/IP checksum process.
Example 3 demonstrate a password checker that makes good use of the this one way hash. As noted in this document, dxr files don't encrypt string constants. Password constants are vulnerable to eavesdropping. By using a one way hash, we can reveal the public key ( the MD5 hashed value ) and still protect the private key ( your password string ). When a user types a password into the input field, we hash the private key using the MD5 algorithm and test if the hashed password equals the public key. Even if the user tries to use a hex editor to read the stored password string constant, he/she cannot reverse engineer your private key from the MD5 Hash value.
To further increase the security of you application, it is recommended that you add a "salt" value to the hash algorithm. Adding salt means adding additional random string with your private key. Salt is a great way to prevent someone who wish to reverse engineer your hash algorithm. For example, to encode "hello world", add a random string such as "X%@" to the hash value. The encoded string "X%@hello world" is much harder to reverse engineer, especially against someone who tries to build a dictionary.
MD5 Hashing is a free xtra. There is no email support provided. If you have any questions, problems, concerns and/or bug, please submit them to the forums at http://xtras.calu.us/forums.
v1.0 Release - February 2, 2003. Final Release with a demo director movie.
v1.1 Release - May 17, 2004. Completely rewritten. New cross platform implementation. |