Sky Dancer Studios, Inc.
 

BlowFish Documentation

 

 

 

Blowfish Plug-in for FileMaker™ Pro Documentation

BlowFish FileMaker Plug-in for Windows™ and Macintosh™
© 2004-2006, Sky Dancer Studios, Inc. - All Rights Reserved

Before using BlowFish, please read through the License Agreement included with this archive. [License.txt]

CONTENTS:

Description
Features
Blowfish Frequently Asked Questions (FAQ]
Installation
Demo Version
Purchasing a License for the BlowFish & AES Plug-ins
How to Contact Sky Dancer Studios
BlowFish History
Known Issues

FUNCTIONS
BLfsh_Version()

BLfsh_Register()
BLfsh_SetKey()
BLfsh_Encrypt()
BLfsh_Decrypt()
BLfsh_ResetChain()
BLfsh_SHA1()

Description:

Blowfish is a symmetric block cipher that can be used as a drop-in replacement for DES or IDEA. It takes a variable-length key, from 32 bits to 448 bits, making it ideal for both domestic and exportable use. Blowfish was designed in 1993 by Bruce Schneier as a fast, unpatented alternative to existing encryption algorithms. Since then it has been analyzed considerably, and it is gaining acceptance as a strong encryption algorithm.

Sky Dancer Studios has wrapped Bruce's Blowfish encryption algorithm into a FileMaker Pro 8 NATIVE plug-in. Blowfish is currently used in over 150 different products and has been incorporated into the Linux kernel starting with v2.5.47!

Features:

Blowfish's Main Points:

  • Block cipher: 64-bit block
  • Variable key length: 32 bits to 448 bits (Keys of 4 to 56 characters in length)
  • Designed by Bruce Schneier in 1993
  • Much faster than AES and DES
  • Unpatented and royalty-free
  • Still unbroken, even after years of study and attacks
  • "Open source" meaning there are no hidden "back doors" or weak spots

Sky Dancer's Blowfish Plug-in adds:

  • Fully Cross-Platform Compliant! Files encrypted on a PC can be decrypted on a Macintosh and vise-versa!
  • Three modes of encryption: ECB, CBC & CFB
  • Compatible with Unicode characters, language independent
  • Unlimited encoding input/output...it can encode anything that can exist in a FileMaker field
  • Self-tests at each startup to ensure integrity (licensed mode)

Visit Bruce's Official Blowfish WEB site! Visit: http://www.schneier.com/

 

Blowfish Frequently Asked Questions (FAQ):

1. Why choose BlowFish over the other "script-based" FileMaker encryption solutions?

a.) The algorithm has been published since 1993 and many security specialists have analyzed it and attempted attacks. (With so called "script-based" solutions, you only have the opinion of the seller, since the "encryption method" has never been analyzed by third party cryptographic specialists!) Don't trust YOUR data to someone who simply SAYS "it's secure"! Listen to the EXPERTS!

b.) Blowfish has become a very popular encryption 'standard' and is used in MANY products, including the popular TiVo™ digital video recorders! Click HERE to see a list of many of the current users of BlowFish!

c.) The BlowFish plug-in tends to run MANY times faster than interpreted scripts! This can save you HOURS when working with large databases! (Even DAYS in encrypting very large databases!)

2. How do we know this plug-in really (and correctly) uses Blowfish?

It has been tested with the testing vectors (known input-output tables) published along with the algorithm. Since the plug-in (and FileMaker Pro 7) uses multi-byte character sets known as Unicode, the result tables have been updated to reflect Unicode input/output, and are provided in the download package for your own testing and verification.

3. Does the plug-in require any other libraries or software to be installed?

No. The plug-in just requires FileMaker Pro 7, 8 or 8.5, FileMaker Developer 7, 8 or 8.5 or FileMaker Server 7 or 8.

4. Exactly what is in the download?

Windows Version

An ENCRYPTED, "ZIPPED" file containing the Blowfish folder, which contains the plug-in, sample databases showing how to use it and all documentation.

Macintosh OS X Version

A compressed file (sitx or zip) containing the Blowfish "disk image file" (dmg) which when mounted, contains the BlowFish folder, that contains the plug-in, sample databases showing how to use it and all documentation. Simply "DRAG" the BlowFish folder to your "Documents" folder (or wherever on your Mac you wish to store it.).

5. How short/long can the key be?

The key can be from 4 to 56 characters in length. Keys longer than 56 characters use only the first 56 characters in the key. Keys at least 8 characters in length or longer are recommended for security reasons! (The longer, the better!)

6. How many characters (or how long a string) can the plug-in encrypt?

There is no limit on the plug-in. The only limit is the size of FileMaker database fields (in version 7, that is approximately 2 GB!)

7. Can I send the encrypted text in an email or over IM?

YES! The encrypted text simply consists of the "hexadecimal" Unicode text characters: "0123456789ABCDEF" which are compatible with any email, instant messaging or other application that can handle simple Unicode text (the normal text characters used in a Mac or Windows PC.)

To send the encrypted text, simply copy the encrypted field text to the clipboard and paste it into any email message. To decode any encrypted text you receive in an email or message, simply copy the encrypted text to a Filemaker field and decrypt it with the BlowFish Plug-In as you would do normally.

HINT: Sometimes in transiting thru emails, the encrypted text gets added characters and line-feeds added to it. To properly decrypt the text, these extra characters must be removed before calling the BlowFish "Decrypt" function. To remove any added characters, use the FileMaker built-in text function "Filter", using hexadecimal characters as the filter like this:

Setfield( <target field>, Filter( <encrypted text>, "0123456789ABCDEF"))

Where <target field> is the field you will pass to BlowFish to decrypt, and <encrypted text> is the encrypted text you received in the email or IM.

Then simply call BlowFish's "Decrypt" function on the <target field>, recovering the original text!

8. How do I install the plug-in?

Plug-in files must be installed in the appropriate folder and enabled in FileMaker Pro, FileMaker Developer or FileMaker Server before they can be used. Simply copy the plug-in into the FileMaker Extensions folder inside the FileMaker application folder and enable it in the preferences dialog box.
Windows: Choose Edit menu > Preferences.

Mac OS X: Choose FileMaker application menu > Preferences.

Then select the "Plug-Ins" tab and make sure it appears with a checkbox next to the plug-in.

9. How do I get rid of the dialog box that shows up when I first use the plug-in each time?

Simply register the plug-in from Sky Dancer for a very small fee! Special rates are available for developers and companies needing multiple copies.

10. What do the modes "ECB", "CBC" and "CFB" mean?

ECB: Electronic Code Book (ECB) is a mode of operation for a block cipher, with the characteristic that each possible block of plaintext has a defined corresponding ciphertext value and vice versa. In other words, the same plaintext value will always result in the same ciphertext value. Electronic Code Book is used when a volume of plaintext is separated into several blocks of data, each of which is then encrypted independently of other blocks. In fact, Electronic Code Book has the ability to support a separate encryption key for each block type.

CBC: Cipher block chaining (CBC) is a mode of operation for a block cipher (one in which a sequence of bits are encrypted as a single unit or block with a cipher key applied to the entire block). Cipher block chaining uses what is known as an initialization vector IV) of a certain length. One of its key characteristics is that it uses a chaining mechanism that causes the decryption of a block of ciphertext to depend on all the preceding ciphertext blocks. As a result, the entire validity of all preceding blocks is contained in the immediately previous ciphertext block. A single bit error in a ciphertext block affects the decryption of all subsequent blocks. Rearrangement of the order of the ciphertext blocks causes decryption to become corrupted. Basically, in cipher block chaining, each plaintext block is XORed (see XOR) with the immediately previous ciphertext block, and then encrypted.

CFB: Ciphertext feedback (CFB) is a mode of operation for a block cipher. In contrast to the cipher block chaining (CBC) mode, which encrypts a set number of bits of plaintext at a time, it is at times desirable to encrypt and transfer some plaintext values instantly one at a time, for which ciphertext feedback is a method. Like cipher block chaining, ciphertext feedback also makes use of an initialization vector (IV). CFB uses a block cipher as a component of a random number generator. In CFB mode, the previous ciphertext block is encrypted and the output is XORed (see XOR) with the current plaintext block to create the current ciphertext block. The XOR operation conceals plaintext patterns. Plaintext cannot be directly worked on unless there is retrieval of blocks from either the beginning or end of the ciphertext.

11. Can FileMaker database fields encrypted on a PC be decrypted on a Macintosh and vise-versa?

YES!!! The plug-in is fully cross-platform compatible including all Windows PCs and Macintoshes with either PowerPC or Intel processors.

12. Do I need a separate license for both the PC version and the Mac version?

A. Yes. The two versions of the plug-in use different key schemes.

13. How can I find out more about Blowfish?

Visit Bruce's Official Blowfish WEB site!

Visit: http://www.schneier.com/blowfish.html

Installation:

Windows:

To install the plug-in under Windows OS, first quit FileMaker Pro if it is open. Next unzip or unstuff the contents of the Blowfish.zip or file into a directory. After you have unzipped or unstuffed the archive file into a directory, you should find a file in that directory named "Blowfish.fmx". This is the plug-in file. Copy this file to the directory named "System" inside your FileMaker Pro application directory. This directory is usually on your hard drive in a directory similar to this: C:\Program Files\FileMaker\FileMaker Pro 7\Extensions\ or C:\Program Files\FileMaker\FileMaker Developer 7\Extensions\

If you had a BlowFish plug-in installed previously, you may find a file in your System directory named "Blowfish.fmx". You will need to delete or alow the new plug-in to overwrite the old one before starting FileMaker Pro so that you do not have two versions of the plug-in installed. After installation, you can restart FileMaker Pro and the plug-in should appear under the "Preferences" dialog, "Plug-ins" tab. Quick Start: Open FileMaker and then open the "Blowfish Example.fp7" database.

Macintosh:

To install the plug-in under OS X, the download should automatically expand into and mount a "disk image" on your desktop. Simply open the disk image and drag the" Blowfish Plug-In" folder to your Documents folder ( or any location you wish to keep the examples). After storing the Blowfish folder, open it up and locate the folder named "Plug-In". Inside, you will find "Blowfish.fmplugin" (the plug-in). Either drag or copy the plug-in to the FileMaker "Extensions" folder (located in the folder named "FileMaker Pro 8" or "FileMaker Pro 8 Advanced" which is located in your "Applications" folder.

NOTE: If the "disk image" does not automatically mount on your desktop, or if you have problems with it, you may not have the required "STUFFIT EXPANDER" in your OS X system (or you may need the latest version!). You can download the latest version (FREE!) from: http://www.stuffit.com/mac/expander/index.html

After dragging or copying the plug-in to the FileMaker "Extensions" folder, start up FileMaker and click on the "Preferences" menu under the "FileMaker Pro" or FileMaker Pro Advanced" menu. Then select the "Plug-Ins" tab. You should see the "Blowfish" plug-in listed. Make sure it is checked to enable it. That's it!

Try out the functions and take a look at the scripts.

 

Demo Version:

The download version is the fully functional plug-in! The only difference is a "reminder dialog" which appears at the first and every tenth call to the encrypt or decrypt functions. Otherwise, the licensed and unlicensed plug-ins are the same.

 

Purchasing a License for the BlowFish Plug-in:

You can purchase a license for the BlowFish plug-in at http://www.skydancerstudios.com/ using your credit card. Just locate the license you wish to purchase and click on the "BUY NOW" button! (Credit Card Processing provided by PayPal)

Our pricing structure for the BlowFish FileMaker Plug-in is as follows:

 
    License Price  
    1 User $ 29.95  
    Company $ 90.00  
    Developer $135.00  
         

Purchase License(s)

Single User - This license allow the plug-in to be used by a single user at a single site. The plug-in may not be distributed or sold.

Company License - This license allows an unlimited number of users, at an unlimited number of sites within one organization, to use the plug-in. The license is restricted to a single database solution. The plug-in may not be distributed or sold.

Developer License - The developer has the right to bundle and distribute the software to an unlimited number of customers, an unlimited number of sites, an unlimited number of users and an unlimited number of database solutions. The developers' customers are not required to register the plug-in as it has already been licensed by the developer. This license only covers solutions that are resold by the developer.

After purchasing a license for BlowFish, you will be sent an email receipt containing your Registration name and Registration Code. To register Blowfish, please use the "BLfsh_Register" function.

 

How to Contact Sky Dancer Studios:

Please send any bug reports, suggestions or questions to mike@skydancerstudios.com.

Updates can be downloaded from http://www.skydancerstudios.com

 

BlowFish History:

WINDOWS VERSION:

-- 07-21-2006 BlowFish 2.0.0 Released.

Added SHA1 Hashing and IV generation & setting to the plug-in.

-- 09-24-2005 BlowFish 1.8.0 Released.

Updated BlowFish for compatibility with FileMaker Pro 8

-- 01-30-2005 BlowFish 1.2.0 Released.

Removed multithreading support from BlowFish that on some older versions of Windows caused FileMaker to not see the plug-in even though the plug-in was located in the FileMaker "Extensions" directory.

-- 12-5-2004 BlowFish 1.1.0 Released.

Fixed a bug which caused encrypted fields larger than 1024 characters in "ECB" mode or larger than 256 characters in the "chained modes (CBC and CFB) to encrypt incorrectly

-- 11-6-2004 BlowFish 1.0.0.1 Released.

Removed all references to the Windows Registry

-- 8-5-2004 BlowFish 1.0.0 Released. First Release of Blowfish Plug-in

MACINTOSH VERSION:

-- 12-17-2005 BlowFish 1.8.1 Released.

Fixed binary error in download sitx

-- 09-24-2005 BlowFish 1.8.0 Released.

Updated BlowFish for compatibility with FileMaker Pro 8

--12-9-2004 BlowFish 1.0.0 Released.

First Release of Blowfish Plug-in for Macintosh

 

Known Issues:

As of 07-21-2006 --None Known

FUNCTIONS:

FUNCTION BLfsh_Version

BLfsh_Version( "" )

EXAMPLE
----------------------------------------------

BLfsh_Version( "" )

DESCRIPTION
----------------------------------------------

This function should be called first in your STARTUP script to make sure the plug-in is available and working correctly.

RESULT
----------------------------------------------

It returns a string similar to: "Blowfish x.x"

Always check for the word "Blowfish" in the returned result. If you DON'T get the expected result string, check to make sure the plug-in is located in the proper FileMaker directory (or the proper folder in your bound solution) and that it is enabled in the "Preferences" dialog under the FileMaker menu.

SEE ALSO:
----------------------------------------------

 

 

FUNCTION BLfsh_Register

BLfsh_Register( RegisteredName ; License Code ; RegistrationCode )

EXAMPLE
----------------------------------------------

BLfsh_Register( "Mike" ; "U07" ; "4EF997456198DD78")

DESCRIPTION
----------------------------------------------

This function allows you to register your copy of Blowfish It is mostly meant for developers so that they can register plug-ins for bound solutions. (This prevents the "Unregistered Dialog" from appearing during running of the database or solution.)

The parameters passed are the Registered Name, the License Code and the Registration Code as obtained from www.skydancerstudios.com. Call this function in your STARTUP script, immediately after calling BLfsh_Version.

RESULT
----------------------------------------------

If successful, the function will return the string: "Registered", otherwise it will return a question mark ("?").

SEE ALSO:
----------------------------------------------

BLfsh_Version( "" )

 

FUNCTION BLfsh_SetKey

BLfsh_SetKey( theKey {; mode ; IV Initialization String} )

EXAMPLE
----------------------------------------------

BLfsh_SetKey( "ABCD")
BLfsh_SetKey( "ABCD"; "ECB")
BLfsh_SetKey( "ABCD"; "CBC")
BLfsh_SetKey( "ABCD"; "CBC"; "" )
BLfsh_SetKey( "ABCD"; "CBC"; "This string will initialize the IV" )
BLfsh_SetKey( "ABCD"; "CFB")
BLfsh_SetKey( "ABCD"; "CFB"; "")
BLfsh_SetKey( "ABCD"; "CFB"; "Hello World!" )

DESCRIPTION
----------------------------------------------

This function sets the encrypt/decrypt key and (optionally) sets the mode of operation to "ECB", "CBC", or "CFB" and initializes the "IV" . (If you don't pass the MODE parameter, the Blowfish plug-in defaults to using the "ECB" mode.)

The parameter "KEY" must be at least 4 characters long and can be up to 56 characters.

The parameter "mode" must be "ECB", CBC" or "CFB".

NOTE: If you use modes "CBC" or "CFB", call this function before each call to either BLfsh_Encrypt or BLfsh_Decrypt or alternately call BLfsh_ResetChain (which is FASTER!) to reset the Initialization Vector!

The parameter "IV Initialization String", if given, will be "hashed" by the SHA1 Hash algorithm and used to "initialize" the Initialization Vector (IV) in modes "CBC" and CFB" (this causes the encrypted output to become highly unpredictable and increases security!) If the string is empty or missing, the IV will be initialized to zero. The string may be of any length.

NOTE: If the mode is set to "ECB", the IV is not used and any string given in the parameter "IV Initialization String" will be ignored.

RESULT
----------------------------------------------

If the function is successful, it will return a single character string of "0". If it fails, it will return a question mark ("?").

SEE ALSO:
----------------------------------------------

BLfsh_Encrypt( string )
BLfsh_Decrypt( string )
BLfsh_ResetChain("")

 

FUNCTION BLfsh_Encrypt

BLfsh_Encrypt( string )

EXAMPLE
----------------------------------------------

BLfsh_Encrypt( "Encrypt this text." )

DESCRIPTION
----------------------------------------------

This function call encrypts the string using the current KEY, MODE and IV that was set by a previous call to BLfsh_SetKey().

RESULT
----------------------------------------------

If successful, the function returns the encrypted string in Unicode HEXADECIMAL If the key hasn't been set, or some other failure occurs, the function will return a question mark ("?")

SEE ALSO:
----------------------------------------------

BLfsh_SetKey( theKey {; mode; IV Initialization String} )
BLfsh_Decrypt( string )

 

FUNCTION BLfsh_Decrypt

BLfsh_Decrypt( string )

EXAMPLE
----------------------------------------------

BLfsh_Decrypt( string )

DESCRIPTION
----------------------------------------------

This function call decrypts the encrypted string using the current KEY, MODE and IV that was set by a previous call to BLfsh_SetKey(). The string must be a Unicode HEXADECIMAL string from a previous call to BLfsh_Encode.

RESULT
----------------------------------------------

If successful, the function returns the plain text unencrypted string in Unicode text. If the key hasn't been set, the string isn't a Unicode Hexadecimal result of a previous call to BlowFish's "Encrypt" function, or some other failure occurs, the function will return a question mark ("?")

SEE ALSO:
----------------------------------------------

BLfsh_SetKey( theKey {; mode; IV Initialization String} )
BLfsh_Encrypt( string )

 

FUNCTION BLfsh_ResetChain
BLfsh_ResetChain( IV Initialization String)

EXAMPLE
----------------------------------------------

BLfsh_ResetChain( "" )
BLfsh_ResetChain( "This sentence is being used to initialize the IV. " )

DESCRIPTION
----------------------------------------------

This function call resets the "chain" bytes used in the serial encryption modes "CBC" and "CFB" (in serial modes, each encrypted block depends on the previous encrypted blocks.) Calling this function restarts the 'chain' of blocks by resetting the accumulated chain results to zero (if an empty string is given for the IV Initialization String, or the SHA! "hashed" value of the given IV Initialization String. The advantage of using BLfshResetChain is that it is faster than resetting the master key with BLfsh_SetKey().

In modes "CBC" and "CFB", the parameter "IV Initialization String", if given, will be "hashed" by the SHA1 Hash algorithm and used to "initialize the Initialization Vector (this causes the encrypted output to become highly unpredictable and increases security!) If the string is empty or missing the IV will be initialized to zero. The string may be of any length.

NOTE: Setting the encryption master key by calling BLfsh_SetKey() also resets this chain.

NOTE: This function has no effect in "ECB" mode, since "ECB" mode doesn't use chaining.

RESULT
----------------------------------------------

If successful, the function returns a text "0", or if some other failure occurs, the function will return a question mark ("?")

SEE ALSO:
----------------------------------------------

BLfsh_SetKey( theKey {; mode; IV Initialization String} )

FUNCTION BLfsh_SHA1
BLfsh_SHA1( Any String or Text)

EXAMPLE
----------------------------------------------

BLfsh_SHA1( "This sentence will be 'hashed" by the SHA1 hashing algoritym." )

DESCRIPTION
----------------------------------------------

This function call generates a "SHA1 Hash" of the given string or text. The likely hood of the "hash" result being the same for any two text strings that are not absolutely identical is very remote! This function can be used to check if text has been changed since the last time a "hash" was generated.

For more security, the hash can be also be used as a BlowFish encryption "Key". Simply "hash" any string you want to use as the BlowFish "Key" and pass the resulting hash to BlowFish using the BLfsh_SetKey() function.

NOTE: The "SHA1" function does not need or use the "Key" set by calling "BLfsh_SetKey("). SHA1 generates the hash by using its own "built-in" key system

NOTE: Since Windows and Macintosh store text files differently, the generated "hash" from one computer may not match the other. For instance, Windows uses two characters to do a "line-feed" while Macintoshes use only one. (This will not be visible when you look at the text in a file, but the SHA1 function "sees" the differences and will generate a different hash for them, even though the text in the files may look to be exactly the same! )

RESULT
----------------------------------------------

The function returns a "SHA1 Hash" of the given text in "hexadecimal" format. This is a "one-way" function and the original text CANNOT be "decrypted" from the resulting "hash".

SEE ALSO:
----------------------------------------------

BLfsh_SetKey( theKey {; mode; IV Initialization String} )

-

Sky Dancer Studios, Inc. www.skydancerstudios.com

Visit Bruce Schneier's official Blowfish WEB site.

FileMaker is a trademark of FileMaker, Inc., registered in the U.S. and other countries. FileMaker and the file folder logo are trademarks of FileMaker, Inc.

 

Copyright © 2004-2006 Sky Dancer Studios, Inc.