Cryptographic Actions Plugin

Actions

Crypto.Base64DecodeFromFile
Crypto.Base64DecodeFromString
Crypto.Base64EncodeToFile
Crypto.Base64EncodeToString
Crypto.BlowfishDecrypt
Crypto.BlowfishEncrypt
Crypto.MD5DigestFromString
Crypto.MD5DigestFromFile
Crypto.Rot13

Crypto.Base64DecodeFromFile (string Source, string Destination);

Description:

Decodes a base64-encoded text file and stores the result as a binary file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Source:

(string) The path to the base64-encoded text file that you want to decode.

Destination:

(string) The path and filename for the decoded binary file.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Decodes a base64-encoded text file located in the "Docs" project folder and stores the result as a binary file
-- in the user's Temp folder.
-- The base-64-encoded text file was previously encoded using the Crypto.Base64EncodeToFile action.
Crypto.Base64DecodeFromFile("AutoPlay\\Docs\\myfile_encoded.txt", _TempFolder .."\\myfile_decoded.txt");

-- Check to see if an error occurred in the Crypto.Base64DecodeFromFile action.
-- If an error occurred, display the error message.
error = Application.GetLastError();
if (error ~=0) then
	result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Crypto.Base64DecodeFromString (string Text, string Filename);

Description:

Decodes a base64-encoded string and stores the result as a binary file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Text:

(string) The base64-encoded text that you want to decode.

Filename:

(string) The path and filename for the decoded binary file.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Returns the contents of a small binary file as a base64-encoded string.
encoded_string = Crypto.Base64EncodeToString("AutoPlay\\Docs\\myfile.txt");

-- Check to see if an error occurred using the Crypto.Base64EncodeToString action.
error = Application.GetLastError();
if (error ~=0) then
	result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Display the contents of the string, just to show you what it looks like.
Dialog.Message("This is what the encoded string looks like:", encoded_string);

-- Decode the base64-encoded string and store the result as a binary file.
Crypto.Base64DecodeFromString(encoded_string, _TempFolder.."\\myfile_decoded_string.txt");

-- Check to see if an error occurred using the Crypto.Base64DecodeFromString action.
error = Application.GetLastError();
if (error ~=0) then
	result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Crypto.Base64EncodeToFile (string Source, string Destination, number LineLen = 76);

Description:

Stores the contents of a binary file as a base64-encoded text file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Source:

(string) The path to the file that you want to encode.

Destination:

(string) The path and filename for the base64-encoded file.

LineLen:

(number) The maximum line length for the base64-encoded text, in columns. (Use 0 for no line breaks.) The default value is 76.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Takes a binary file located in the user's Temp folder and stores the result as a base64-encoded text file,
-- also located in the user's Temp folder.
-- This file can then be decoded using the Crypto.Base64DecodeFromFile action.
Crypto.Base64EncodeToFile(_TempFolder.."\\myfile.txt", _TempFolder.."\\myfile_encoded.txt");

-- Check to see if an error occurred in the Crypto.Base64EncodeToFile action.
-- If an error occurred, display the error message.
error = Application.GetLastError();
if (error ~=0) then
	result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

string Crypto.Base64EncodeToString (string Source, number LineLen = 76);

Description:

Returns the contents of a binary file as a base64-encoded string.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Source:

(string) The path to the file that you want to encode.

LineLen:

(number) The maximum line length for the base64-encoded text, in columns. (Use 0 for no line breaks.) The default value is 76.

Returns:

(string) The contents of the specified binary file as a base64-encoded string. If the data cannot be encoded or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Returns the contents of a small binary file as a base64-encoded string.
encoded_string = Crypto.Base64EncodeToString("AutoPlay\\Docs\\myfile.txt");

-- Check to see if an error occurred using the Crypto.Base64EncodeToString action.
error = Application.GetLastError();
if (error ~=0) then
	result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Display the contents of the string, just to show you what it looks like.
Dialog.Message("This is what the encoded string looks like:", encoded_string);

-- Decode the base64-encoded string and store the result as a binary file.
Crypto.Base64DecodeFromString(encoded_string, _TempFolder.."\\myfile_decoded_string.txt");

-- Check to see if an error occurred using the Crypto.Base64DecodeFromString action.
error = Application.GetLastError();
if (error ~=0) then
	result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Crypto.BlowfishDecrypt (string Source, string Destination, string Key);

Description:

Creates a decrypted copy of a blowfish-encrypted file.

Source:

(string) The path to the file that you want to decrypt.

Destination:

(string) The path and filename for the decrypted file.

Key:

(string) The secret key that the data was decrypted with.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Create a blowfish-encrypted copy of the text file in the "Docs" project folder.
-- The encrypted copy will be created in the user's Temp folder.
Crypto.BlowfishEncrypt("AutoPlay\\Docs\\myfile.txt", _TempFolder.."\\myfile_blowfished.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishEncrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
	Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Decrypts the blow-fish encrypted file.
Crypto.BlowfishDecrypt(_TempFolder.."\\myfile_blowfished.txt", _TempFolder.."\\myfile_blowfish_decrypted.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishDecrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
	Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Open the decrypted file to see its contents.
File.Open(_TempFolder.."\\myfile_blowfish_decrypted.txt");

Crypto.BlowfishEncrypt (string Source, string Destination, string Key);

Description:

Creates a blowfish-encrypted copy of a file.

Source:

(string) The path to the file that you want to encrypt.

Destination:

(string) The path and filename for the blowfish-encrypted file.

Key:

(string) The secret key to encrypt the data with.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Create a blowfish-encrypted copy of the text file in the "Docs" project folder.
-- The encrypted copy will be created in the user's Temp folder.
Crypto.BlowfishEncrypt("AutoPlay\\Docs\\myfile.txt", _TempFolder.."\\myfile_blowfished.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishEncrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
	Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Open the encrypted file to see its contents.
File.Open(_TempFolder.."\\myfile_blowfished.txt");

string Crypto.MD5DigestFromString (string Text);

Description:

Creates an MD5 message digest for a given text string.

An MD5 message digest is a 128-bit "fingerprint" or digital signature, represented by a string of 32 hex digits. Every unique string of text is guaranteed to produce a unique message digest. More importantly, it is virtually impossible to determine the original string from the digest. In other words, the MD5 calculation only works in one direction. This makes it extremely useful for storing passwords.

Instead of storing a password in plain text, you should store its MD5 digest instead. When the user enters a password, calculate the MD5 digest for the text that they entered, and compare that to the MD5 digest that was stored. If it is identical to the stored digest, then the user entered the correct password.

Since there is no way to get from the digest back to the original password, it doesn't matter if anyone sees the digest.

Note: MD5 isn't a substitute for secure passwords. Using an insecure password like "sneeze" or "equine" can still leave your application open to so-called "dictionary attacks," where the hacker simply tries the MD5 digest for every word in the dictionary. Be sure to use secure passwords like "sationicat59" or "b$fer@fe!23."

Tip: A good way to defeat dictionary attacks when using user-supplied passwords is to append a non-alphabetic string to all passwords. For example, simply append "$!%" to the end of any password before generating the MD5 digest. This way, even a really bad password like "password" will be relatively safe from dictionary attacks.

Text:

(string) The text to create the message digest for.

Returns:

(string) The message digest that was calculated for the given text. If the message digest cannot be calculated or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError() to determine whether this action failed, and why.

Example 1:

-- calculate the MD5 message digest for the user's name and display it in a message
strName = Dialog.Input("", "What is your name?", "", MB_ICONQUESTION);
strDigitalSignature = Crypto.MD5DigestFromString(strName);
Dialog.Message("The digital signature for your name is:",strDigitalSignature);

Example 2:

--[[ note: our app allows the user to password-protect it. If the user
           chose to enable password-protection, they were prompted for
           a password, we appended a suffix to it (to help prevent 
           dictionary attacks), and the MD5 digest for the resulting
           password + suffix was stored in the Registry.]]
          
--[[ get the digest that was stored in the Registry at HKEY_CURRENT_USER\Software\SuperDooperApp
     note: this was calculated when the user supplied the password,
           before it was stored ]]
reg_md5 = Registry.GetValue(HKEY_CURRENT_USER, "Software\\SuperDooperApp", "password")

-- the value only exists when the app is password-protected
if reg_md5 ~= "" then

    --[[ ask the user for the password they supplied when they enabled
         the password protection feature ]]
    pw = Dialog.Input("", "Please enter your password:");

    --[[ we added "!$" to their password before it was stored,
         to help make the user's password safe from dictionary attacks ]]
    pw = pw .. "!$"

    -- calculate the MD5 message digest for the password + suffix
    pw_md5 = Crypto.MD5DigestFromString(pw);

    -- exit the app if the password digests don't match
    if pw_md5 ~= reg_md5 then
        Dialog.Message("", "Sorry, invalid password!");
        Application.Exit();
    end
end

string Crypto.MD5DigestFromFile (string Filename);

Description:

Creates an MD5 message digest for a given file.

Filename:

(string) The path to the file whose MD5 digest you want to calculate.

Note: The file can be of any type (binary or ascii).

Returns:

(string) The message digest that was calculated for the file. If the message digest cannot be calculated or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- calculate the MD5 message digest for a file
-- note: edit this path so it points to an actual file :)
file = "AutoPlay\\Docs\\MyFile.htm";
strMD5 = Crypto.MD5DigestFromFile(file);
if strMD5 then
	Dialog.Message("MD5DigestFromFile","The MD5 digest for "..file.." is:\r\n\r\n"..strMD5);
else
    err = Application.GetLastError();
	Dialog.Message("Arooga! Arooga!","ERROR "..err..": ".._tblErrorMessages[err]);
end

string Crypto.Rot13 (string Text);

Description:

Applies a simple Ceaser-cypher ("rot13") encryption to the text.

The simple Caesar-cypher encryption replaces each English letter with the one 13 places forward or back along the alphabet, so that "Indigo Rose is cool!" becomes "Vaqvtb Ebfr vf pbby!" In other words, it "rotates" the alphabet ahead 13 characters. Most Usenet news reading and posting programs include a rot13 feature to hide text from plain sight so the user must choose to view it. (For example, to hide "spoilers" -- information that gives away some secret that readers might not want to know if they haven't already read the book, played the game, etc.)

A nice feature of rot13 is that the same action is used to encrypt and decrypt the text.

Text:

(string) The text that you want to encrypt (or decrypt).

Returns:

(string) The encrypted (or decrypted) text. If the text cannot be encrypted (or decrypted) or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- encrypt the user's name
strName = Dialog.Input("", "What is your name?", "", MB_ICONQUESTION);

-- rot13 encrypt the name
strEncrypted = Crypto.Rot13(strName);
Dialog.Message("Your name, rot13 encrypted:",strEncrypted);

-- rot13 decrypt the name
strDecrypted = Crypto.Rot13(strName);
Dialog.Message("And now rot13 decrypted:",strDecrypted);