Bifroest	Mr. Tines	CTC Home	CTClib	MacCTC	CTCjava	Manual

Symmetric Ciphers

Constants

• MAXCVALGS=5 maximum number of conventional algorithm passes allowed
• MAXBLOCKSIZE=16 largest supported cipher block size (equalled for Square, with its 128-bit blocks)
• MAXKEYSIZE=32 up to a 256 bit key (e.g. GOST; or any of the AES candidates), currently however this limit is not reached (maximum is 20 bytes, 160 bits)

Data Types

typedef struct cv_details_T
{
        byte  cv_algor; /* algorithm */
        byte  cv_mode;  /* mode of application */ 
} cv_details;

cv_keysched

The key schedule structure is private; and its contents are dependent on the algorithm employed

Public Methods

cv_keysched cipherInit(cv_details *cipher, byte *key, boolean decryp);

The choice of cipher in cipher, a single cv_details structure passed by reference, with associated key data in key, as a packed byte stream, MSB-first, are initialised in the sense of operation given by decryp; with FALSE indicating encryption. The return value is a handle to the anonymous data structure holding any expanded key data or round values for the chosen cipher.

int cipherDo(cv_keysched context, byte *buf, int count);

Using the context established by cipherInit(), the array buf[count] bytes of data are processed (encrypted or decrypted as determined by the initialisation). The operation is despatched from this routine to the method handling desired mode of encryption; which in turn despatches the data to the appropriate cipher. Some of the data may be buffered internally, if the mode being used requires whole blocks to be encrypted (e.g. ECB or CBC); the return value indicates how many bytes of data are returned in buf[].

int cipherEnd(cv_keysched *context, byte *buf);

Having finished with the cipher, the context is disposed of, with heap storage being wiped and deallocated. If the mode being used requires whole blocks to be encrypted, then this routine manages the ciphertext stealing required to satisfy it. The return value is the number of bytes deposited in buf[], which should be of size 2*MAXBLOCKSIZE. If the mode is known not to require ciphertext stealing, and only in these circumstances, buf can be NULL.

int cipherBlock(byte cv_algor);

Return the block size (in bytes) of the chosen algorithm. If the algorithm should happen to be a stream , then this value is actually chosen to simply to indicate the amount of random padding ahead of any data, and should be at least 2 for architectural reasons.

int cipherKey(byte cv_algor);

Return the key size (in bytes) of the chosen algorithm. For variable key length algorithms, a single value is selected as part of the algorithm byte.

boolean cipherAlgAvail(byte cv_algor);

Return TRUE if the algorithm byte is supported (i.e. is defined in keyconst.h) and enabled (IDEA perhaps being disabled at compile time). Flag bits (except the top bit) are ignored.

boolean cipherAlgRecognised(byte cv_algor);

Returns TRUE if the algorithm byte is known to the system even if it is not implemented. (e.g. If the IDEA implementation is omitted it will still be known to the system.)

boolean cipherModeAvail(byte cv_mode, byte cv_algor);

Return TRUE if the mode byte is supported (flag bits being ignored). Note that for example, CFB and OFB make sense for hashes; but ECB and CBC modes, which require a reversible operation, do not, so the algorithm byte is potentially significant .

 

 
 
 
 
 

Private Methods

Dependencies

A key schedule initialiser

void init<ALG>(byte *key, int triple, void **keysched, size_t *length);

where key is 1 or 3 key block lengths, if triple is FALSE or not, returning the keyschedule and its length

A do-it routine

void ecb<ALG>(void *keysched, int triple, int encrypt, byte *in, byte *out);

to perform a single block encryption with the algorithm from in to out, where these are pointers to buffers of one block in size (not necessarily aligned, even on RISC machines and with algorithms operating on buffers structured into longer words).

A keyschedule destructor

void destroy<ALG>(void **keysched, size_t length);

to encapsulate memory allocation and deallocation for the keyschedule within each algorithm file.

Constants definitions

<ALG>KEYSIZE

algorithm key size

<ALG>BLOCKSIZE

block lengths in bytes.

The symmetric algorithms

The process of adding new algorithms is mechanical.  It requires modifications to several functions in cipher.c.  In each, an extra case must be added to a switch statement to process the new cipher, if the cipher algorithm matchs the appropriate key value.

ECB1block
Add case to call ecb<ALG>.
cipherInit
Add case to call init<ALG>.
cipherEnd
Add case to call destroy<ALG>.
cipherBlock
Add case to return appropriate blocksize.
cipherKey
Add case to return size of required key (in bytes).
cipherAlgAvail
Add case to return TRUE, to indicate the cipher is available.