Blowfish DLL Documentation
Version 1.00
By Roger Carbol
Copyright 1999 by Roger Carbol
Contents
"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.
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 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.
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:
-
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.
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.
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.