                        Blowfish DLL Documentation

                                Version 1.00
                              By Roger Carbol
                      Copyright 1999 by Roger Carbol

        ------------------------------------------------------------

Contents

   * Overview
   * The Demo Program
   * The Blowfish DLL
   * Error Codes
   * Known Deviations from the Blowfish Algorithm
   * Possible Enhancements to the Blowfish DLL

        ------------------------------------------------------------

Overview

     "Blowfish, a new secret-key block cipher, is proposed. It is a
     Feistel network, iterating a simple encryption function 16 times.
     The block size is 64 bits, and the key can be any length up to
     448 bits."

     -- Bruce Schneier, "Description of a New Variable-Length Key,
     64-Bit Block Cipher (Blowfish)"

The Blowfish DLL makes writing Visual Basic programs which use Schneier's
Blowfish algorithm as easy as the following code fragment:

Public Sub Main()
  Dim bf as Blowfish
  Const BF_STYLE_HEX = 1

  bf.Style = BF_STYLE_HEX

  bf.Key = "0000000000000000"
  bf.Init

  Msgbox bf.Encipher("FFFFFFFFFFFFFFFF")
End Sub

Like the algorithm itself, this DLL may be freely used and distributed.

        ------------------------------------------------------------

The Demo Program

NOTE: After running the setup program for the demo, you should put a copy
of the DLL (blofsh10.dll) into the directory in which the demo was
installed. You should also use regsvr32 to register the DLL. A copy of that
program should be in C:\WINDOWS\SYSTEM; a copy has also been included with
this distribution. If you have regsvr32 in your system path or in the
actual directory with the DLL, you can register it by entering:

regsvr32 blofsh10.dll

                              ---------------

As a demonstration of the Blowfish DLL, a small demonstration program has
been written in Visual Basic 5. To test the DLL using known
key-cleartext-ciphertext sets (such as those found in vectors.txt) follow
these steps:

[Screenshot of Blowfish DLL Demo]

1. Click the Hex radio button, which changes the Blowfish's Style to Hex.
In this mode, the algorithm interprets "00" as the hexadecimal value 00,
rather than using the ASCII values for the character "0" twice.

2. Cut and paste the key into the key input box, or type it in. An example
key is "0000000000000000". The key may be anywhere from 1 byte to 56 bytes
in length (8 bits to 448 bits.)

3. Click the "Set Key" button. Then click the "Initialize Blowfish" button.
This causes the DLL to calculate the key-dependent S-boxes for use in
encryption and decryption.

4. Cut and paste the clear text into the clear text input box. An example
clear text is "0000000000000000". Unlike the key, the clear text (and also
the cipher text) must be exactly 8 bytes long.

5. Click the "Encipher Clear Text" button. The encrypted data should appear
in the cipher text input box. It should match the cipher text given in your
key-cleartext-ciphertext set. In the example that we've been using, the
cipher text should be "4EF997456198DD78".

6. Decrypting data is just as easy. Set the key as before, being careful to
click the "Set Key" button and the "Initialize Blowfish" button. Then enter
the enciphered data into the cipher text input box. Clicking the "Decipher
Cipher Text" button will give you the original clear text in the clear text
input box.

Once a key has been set and a clear text provided, you may wish to check
the performance of the algorithm on your particular hardware. The "Encrypt
64 kilobytes" and "Encrypt 200 kilobytes" buttons provide a method to check
this performance. Once clicked, they start the encryption process. When
finished, they will inform you when the process started, and when it
completed.

The DLL is approximately %250 faster in ASCII mode than in HEX mode. As a
rough guideline, the Blowfish DLL in ASCII mode on a Pentium 133 can
encrypt about 25 kilobytes per second.

The "Force Error" buttons are primarily for use by programmers. In
conjunction with the source code for the demo, they should provide helpful
in avoiding the errors possible when using the Blowfish DLL.

        ------------------------------------------------------------

The Blowfish DLL

The Blowfish DLL defines the Blowfish object. This object has two
properties and four methods.

Properties

Style
     This property affects how the DLL interprets the strings passed to it.
     It can equal either 0 or 1; assigning it any other value results in an
     error.

     Value 0: This is ASCII mode. It is the default. In this mode, the
     ASCII values of the string characters are used. This is most often
     used when someone is using a text passphrase for a key, for example,
     "This is my password." It is also useful when the data to be encrypted
     or decrypted is being inputted from or outputted to a binary file.
     This mode is typically %250 faster than the HEX mode.

     Value 1: This is HEX mode. In this mode, the string is assumed to be
     hexadecimal digits. Every byte is assumed to be rendered as two
     characters -- a string consisting of an odd number of characters will
     produce an error (use leading zeroes if required.) A string which
     contains any characters which are not hexadecimal digits ('0'-'9' and
     'A'-'F') will also produce an error. Alphabetic digits may be either
     uppercase or lowercase. This mode is useful for transferring
     non-alphabetic data by email, for example. Most test vectors, such as
     those contained in vectors.txt, should use this mode.

Key
     This property contains the current key. The manner of its expression
     depends on the Style property. One may convert between ASCII and HEX
     representations of a string (up to 56 bytes) by setting one Style,
     setting the key, changing to the other style, and retrieving the key.
     The key may be from 1 byte to 56 bytes in length. Keys shorter or
     longer than this will produce an error.

Methods

About
     This method returns a string which contains version and other
     information about the DLL. It may be used to ensure that the most
     current DLL is in use, for example.

Init
     This method initializes the algorithm by calculating the key-dependent
     subkeys. It must be called before using the Encipher or Decipher
     methods, or an error will occur. It must also be called after the Key
     has been changed before using either of those two methods.
     Technically, this is not an error -- as long as the subkeys are
     initialized to some key, the algorithm will work, regardless of what
     then happened to the key. However, in virtually all instances,
     changing the key implies a recalculation of the subkeys. Therefore an
     error will occur if the key is changed and either Encipher or Decipher
     are called without again calling Init.

Encipher
Decipher
     These methods actually encrypt or decrypt the argument. The argument
     must be exactly 8 bytes in length; any other length will result in an
     error. The methods return a string of 8 bytes. These strings will be
     expressed according to the current Style method; the argument and the
     returned string will always be expressed in the same Style.

        ------------------------------------------------------------

Error Codes

The Blowfish DLL introduces ten error codes.

Error 1001
     "A key must be assigned to the Blowfish object prior to referencing
     this property."

     Occurs when Key is retrieved before it has been set. There is no
     default Key value.

     Remedy:
        o Assign a value to Key prior to referencing it.

Error 1002
     "A key must be assigned to the Blowfish object prior to using this
     method."

     Occurs when Init is called prior to a Key being set.

     Remedy:
        o Assign a value to Key prior to calling the Init method.

Error 1003
     "The Blowfish key may not exceed 56 bytes in length."

     Occurs when one attempts to assign Key a value which is longer than 56
     bytes. In ASCII Style, this implies a string longer than 56
     characters. In Hex Style, it implies a string longer than 112
     characters.

     Remedy:
        o Ensure the correct Style is set.
        o Truncate the key to 56 bytes before assigned it to Key.

Error 1004
     "The Init method must be called after the Blowfish key has been
     changed."

     Occurs when the Key is given a new value but the Init method is not
     called prior to calling Encipher or Decipher.

     Remedy:
        o Call the Init method after each Key update.

Error 1005
     "The Blowfish key may not be the zero-length string."

     Occurs when the zero-length string "" is assigned to the Key.

     Remedy:
        o Use keys which are at least 1 byte in length.

Error 2001
     "Invalid value assigned to the Style property of the Blowfish object."

     Occurs when the zero-length string "" is assigned to the Key.

     Remedy:
        o Define two constants such as:

          Public Const BF_STYLE_ASCII As Byte = 0
          Public Const BF_STYLE_HEX As Byte = 1

          and only use those constants in assigning a value to the Style
          property.

Error 3001
     "The Init method of the Blowfish object must be called prior to using
     this method."

     Occurs when the Encipher or Decipher methods are called without first
     calling the Init method.

     Remedy:
        o Call the Init method after Key has been set and before calling
          either Encipher or Decipher.

Error 4001
     "Argument contains characters which are not hexadecimal digits."

     Occurs when the Hex Style is used and a string is passed to the
     Blowfish object which contains characters other than hexadecimal
     digits ('0'-'9','A'-'F','a'-'f').

     Remedy:
        o Pass only valid hexadecimal numbers when using the Hex Style.
        o Use ASCII Style instead.

Error 4002
     "The Blowfish object must receive an even number of hexadecimal
     digits."

     Occurs when the Hex Style is used and a string is passed to the
     Blowfish object which contains an odd number of characters.

     Remedy:
        o Pad single hexadecimal digits with a leading zero.
        o Use ASCII Style instead.

Error 5001
     "Data passed to the Encipher method or Decipher method of the Blowfish
     object must be exactly eight bytes in length."

     Occurs when the argument to Encipher or Decipher is longer or shorter
     than 8 bytes. This implies an argument of 8 characters in ASCII Style
     and 16 characters in Hex Style.

     Remedy:
        o Ensure the correct Style is set.
        o Truncate or pad arguments which are too long or too short.
        o Pass only arguments of the correct length.

        ------------------------------------------------------------

Known Deviations from the Blowfish Algorithm

The only known deviation from the algorithm as published by Schneier is
that the key must consist of a whole number of bytes, that is, it may be 8
bits, 16 bits, etc. This deviates from the standard, which states that any
number of bits up to 448 may be used. It is not considered a serious
limitation to the utility of the Blowfish DLL.

        ------------------------------------------------------------

Possible Enhancements to the Blowfish DLL

The following are features which may be added to the DLL at some future
date:

   * The ability to import and export S-boxes.
   * Automatic detection of weak keys.
   * Variable number of rounds.
   * Support for different block sizes.
   * Inherent ability to arbitrarily limit key sizes.
   * Further optimizations for speed.
   * Inherent chaining modes.
   * Allow the subkeys to be initialized with a plaintext other than the
     all-zeroes string.
   * Allow the subkeys to be initialized with values other than the digits
     of pi.
