# 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:

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:
  - 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:
  - 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:
  - Ensure the correct Style is set.
  - 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:
  - 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:
  - 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:
  - 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:
  - 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:
  - Pass only valid hexadecimal numbers when using the Hex Style.
  - 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:
  - Pad single hexadecimal digits with a leading zero.
  - 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:
  - Ensure the correct Style is set.
  - Truncate or pad arguments which are too long or too short.
  - 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.