BF-SDK ~~~~~~ V1.1 Pascalinterface ~~~~~~~~~~~~~~~ (c) 1996 Cedric Reinartz & Markus Hahn This documentation helps you to use the pascal interface in your own program. You need to include the unit BLOWFISH.TPU in your programm. It should be sufficient to use the provided one which was compiled with the default parameters. For changing the parameters please see ASM.TXT. The following type declarations are made in BLOWFISH.TPU: ULONG = Longint; { unsigned 32bit } UINT = Word; { unsigned 16bit } UCHAR = Byte; { unsigned 8bit } BOOL = Word; { 16bit boolean } P_UCHAR_Buffer = ^T_UCHAR_Buffer; T_UCHAR_Buffer = array[0..MAXDATA-1] of UCHAR; P_UINT_Buffer = ^T_UINT_Buffer; T_UINT_Buffer = array[0..(MAXDATA div 2)-1] of UINT; P_ULONG_Buffer = ^T_ULONG_Buffer; T_ULONG_Buffer = array[0..(MAXDATA div 4)-1] of ULONG; You need this declarations to understand and use the following descriptions. See also PAS_DEMO.PAS for reference. Functions ~~~~~~~~~ Blowfish_Init(pKey : P_UCHAR_Buffer; unKeySize : UINT); Function : Initialises the Boxes Argument : Pointer to the Password (which is NOT a string) Length of the Password Return : none Description: A Password with a maximum of 56 Bytes is used to encrypt the Boxes. These encrypted boxes are vital for the further encryption process with Blowfish_(CBC)Encrypt and Blowfish_(CBC)Decrypt. If you want to change the password at runtime you have to restore the original contents of the boxes before you can use this function again (See Blowfish_GetBoxes and Blowfish_SetBoxes). ------------------------------------------------------------------------------- Blowfish_WeakKey : BOOL; Function : Test if the generated Boxes are weak Argument : none Return : Status (1=weak, 0=good) Description: After "Blowfish_InitCrypt" you should test the Boxes with this function. If they provide a weakness which a cryptoanalyst could use to break the cipher a "1" is returned. In this case you should reload the original boxes and let the user choose a different password. ------------------------------------------------------------------------------- Blowfish_ECBEncrypt(pBuffer : P_ULONG_Buffer; unCount : UINT); Function : Encrypts a plaintext string using the ECB method Argument : Pointer to the plaintext Length of the plaintext Return : none Description: This function encrypts (multiple) blocks of 8 Bytes of plaintext using the ECB method (blocks are not chained). The generated ciphertext will overwrite the plaintext. Thus the plaintext- pointer will point to the ciphertext after the encryption. The length of the plaintext must be a multiple of 8. If it is not, plaintext bytes will be left at the end of the ciphertext. ------------------------------------------------------------------------------- Blowfish_ECBDecrypt(pBuffer : P_ULONG_Buffer; unCount : UINT); Function : Decrypts a ciphertext string using the ECB method Argument : Pointer to the ciphertext Length of the ciphertext Return : none Description: This function decrypts (multiple) blocks of 8 Bytes of cipher- text using the ECB method (blocks are not chained). The generated plaintext will overwrite the ciphertext. Thus the ciphertext- pointer will point to the plaintext after the decryption. The length of the ciphertext must be a multiple of 8. If it is not, ciphertext bytes will be left at the end of the plaintext. ------------------------------------------------------------------------------- Blowfish_CBCEncrypt(pBuffer : P_ULONG_Buffer; unCount : UINT; var ulCBCLeft, ulCBCRight : ULONG); Function : Encrypts a plaintext string using the CBC method Argument : Pointer to the plaintext Length of the plaintext Lower part of the IV Upper part of the IV Return : none Description: This function encrypts (multiple) blocks of 8 Bytes of plaintext using the CBC method (blocks are chained using an initialisation vector IV). The generated ciphertext will overwrite the plain- text. Thus the plaintext-pointer will point to the ciphertext after the encryption. The length of the plaintext must be a multiple of 8. If it is not, plaintext bytes will be left at the end of the ciphertext. The IV must not be secret. For different encryptions you can choose the same IV but if possible you should use different ones to improve security. Note: you need the original IV for decryption. ------------------------------------------------------------------------------- Blowfish_CBCDecrypt(pBuffer : P_ULONG_Buffer; unCount : UINT; var ulCBCLeft, ulCBCRight : ULONG); Function : Decrypts a ciphertext string using the CBC method Argument : Pointer to the ciphertext Length of the ciphertext Lower part of the IV Upper part of the IV Return : none Description: This function decrypts (multiple) blocks of 8 Bytes of ciphertext using the CBC method (blocks are chained using an initialisation vector IV). The generated plaintext will overwrite the cipher- text. Thus the ciphertext-pointer will point to the plaintext after the decryption. The length of the ciphertext must be a multiple of 8. If it is not, ciphertext bytes will be left at the end of the plaintext. Note: The IV is the same used on encryption. ------------------------------------------------------------------------------- Blowfish_Done; Function : Clears the Boxes Argument : none Return : none Description: Clears the contents of the P- and S-Boxes. This should be used before you exit your program to make sure that no one can get your Key. ------------------------------------------------------------------------------- Blowfish_SetRounds(Rounds : UINT): UINT; Function : Set number of rounds. Returns number of rounds. Argument : # of rounds = 16, 32 or 2-32. See variable RNDS in ASM.TXT Return : number of rounds Description: You always have to give a Argument. If BFENG386.ASM was compiled with "rnds equ 3" you are able to set the number of rounds between 2 and 32. This function always returns the number of rounds actual used. If you supply an invalid argument nothing is changed and the currently used number of rounds is returned. For more details see variable RNDS in ASM.TXT. ------------------------------------------------------------------------------- Blowfish_GetBoxes(pBuffer : P_ULONG_Buffer); Function : Copies the actual P- and S-Boxes to a user buffer Arguments : Pointer to the user buffer Return : none Description: Use this to save the original Boxes. If you want to change the Password at runtime you have to restore these Boxes first. You can also save the encrypted Boxes and restore them if needed. In this way you are able to swap Passwords at high speed. The needed buffer size is 1042 for rnds=1 and 1058 for rnds=2 or rnds=3 (see ASM.TXT for the meaning of "rnds"). ------------------------------------------------------------------------------- Blowfish_SetBoxes(pBuffer : P_ULONG_Buffer); Function : Copies a user buffer to the P- and S-Boxes Arguments : Pointer to the user buffer Return : none Description: Use this to restore the Boxes with previously saved ones. See description of "Blowfish_GetBoxes". ------------------------------------------------------------------------------- Blowfish_GetBoxPointer : Pointer; Function : Returns a Pointer to the beginning of PBox in DX:AX Arguments : none Return : pointer to the Boxes Description: For a reason I do not know the pointer is sometimes wrong, so verify this! Normaly there is no need to use this function. - eof -