Table of contents Up Previous Next Glossary Home   Extending BestCrypt: Module Example  

Development process could be divided into three successive steps:

Finally, take a look at BestCrypt files layout and do not forget to add your module information to BestCrypt configuration file.

Step 1: Preparing the Environment

 Top  

First of all, we should choose module's name. It should be noted that module name will be used in several places:

  • module sources directory name
  • module binary output file name
Our module example deserves "dummy" name. Now source directory must be called dummy and module binary will go to bc_dummy.o file 

[developer@mod ]$ ls -XF
3des/      dummy/     README        bc_mgr.c
bf128/     gost/      Makefile.alg  mkver.c
bf448/     idea/      bc_alg.c      bc_cfg.h
blowfish/  rijn/      bc_dev22.c    bc_dev.h
cast/      twofish/   bc_dev24.c    bc_mgr.h
des/       Makefile   bc_dev.c

Next, we should correct BestCrypt driver's Makefile so that our algorithm module sources will be included to build list.
Actually we have added dummy to SUBDIRS list (line 57 of Makefile). 

...

LDFLAGS = -d -r

SUBDIRS = gost blowfish twofish des bf128 bf448 cast idea 3des rijn dummy
OBJS = bc_dev.o bc_mgr.o

TARGET = bc.o

all: $(TARGET) subdirs 
...

Step 2: Understanding module interface

 Top  

Module interface related code is collected in bc_dummy.h header file. Annotated listing follows: 

#define SERVICE_NAME	"BC_Dummy"
#define DISPLAY_NAME    "DUMMY"
#define ALGORITHM_ID     0xff
 Module identification constants.
SERVICE_NAME and DISPLAY_NAME are not used; these values were left to preserve BestCrypt for Windows source compatibility.
ALGORITHM_ID is unique byte-sized number which identifies encryption algorithm module. Please choose unique id for your module. 
#define BLOCK_LENGTH		(8)
// Key length in bits
#define KEY_LENGTH		(8)
#define KEY_LENGTH_EXTENDED	(1024)
Algorithm parameter constants.
BLOCK_LENGTH is algorithm's data block length specified in bytes. 8 bytes (64 bits) is common block size used by most block ciphers.
KEY_LENGTH is algorithm's key length specified in bits. For example, DES algorithm uses 56-bit key, thus KEY_LENGTH must equal 56 in that case.
KEY_LENGTH_EXTENDED is algorithm's extended (preprocessed) key size specified in bits. Most block ciphers allow speed optimizations that require preprocessed encryption key rather than original one. If your module does not use optimisations of such class, KEY_LENGTH_EXTENDED should be equal to KEY_LENGTH. 
#define DRIVER_MAJOR_VERSION 1
#define DRIVER_MINOR_VERSION 1
These values were left to preserve BestCrypt for Windows source compatibility. 
BOOL
KeyExtend( PUCHAR KeySource,
           PDWORD KeyDestination );
 Key extension procedure entry. KeyExtend takes original encryption key as input argument and writes out extended key. Please see notes to KEY_LENGTH_EXTENDED above.
PUCHAR KeySource address of original key. Key size is specified by KEY_LENGTH constant (see above).
PDWORD KeyDestination address of extended key. Key size is specified by KEY_LENGTH_EXTENDED constant (see above). 
VOID
Encrypt( DWORD *IVector, 
         DWORD *KeyAdress,
         DWORD *SrcBuffer,
         DWORD *DstBuffer,
         DWORD Length );    // in bytes
VOID
Decrypt( DWORD *IVector, 
         DWORD *KeyAdress,
         DWORD *SrcBuffer,
         DWORD *DstBuffer,
         DWORD Length );    // in bytes
Encryption and decryption procedure entries.
DWORD *IVector is address of initialization vector.
DWORD *KeyAdress is address of key. Please note that extended (preprocessed) key is used here.
DWORD *SrcBuffer is source buffer address.
DWORD *DstBuffer is destination buffer address.
DWORD Length is buffers length specified in bytes. Source and destination buffers are the same length.

Step 3: Dealing with encryption

 Top  

Now it's time to implement module's body: encryption and key preprocessing routines. 

#include "bc_types.h"
/*
#ifndef __WIN95__
#include 
#else
#include 
#endif
*/
#include "bc_dummy.h"
 Includes section.
bc_types.h brings win32-style data types definition to BestCrypt for Linux. Replaces Win32 includes which are commented out here. Intended to make Linux and Windows Encryption Algorithm Modules source-level compatible.
bc_dummy.h is our module interface specification. See Step 2 for details. 
VOID
Encrypt( DWORD *IVector, 
         DWORD *KeyAddress,
         DWORD *SrcBuffer,
         DWORD *DstBuffer,
         DWORD Length )    // in bytes
{ 
	DWORD i, lengthDword = Length >> 2;

	for ( i=0; i < lengthDword; i++) 
		DstBuffer[i] = SrcBuffer[i];
}

VOID
Decrypt( DWORD *IVector, 
         DWORD *KeyAddress,
         DWORD *SrcBuffer,
         DWORD *DstBuffer,
         DWORD Length )    // in bytes
{
	DWORD i, lengthDword = Length >> 2;

	for ( i=0; i < lengthDword; i++) 
		DstBuffer[i] = SrcBuffer[i];
}
Data encryption code.
Encrypt and Decrypt procedures should implement encryption and decryption respectively. Our example illustrates module skeleton, not encryption technologies, hence "encryption" and "decryption" are simple data copying here. 
BOOL
KeyExtend( PUCHAR KeySource,
           PDWORD KeyDestination )
{
  return TRUE;
}
Key preprocessing code.
KeyExtend procedure should contain key preprocessing code. Since our example "encryption" is trivial, no actions required here.
  Table of contents Up Previous Next Glossary Home   Top