Notes for Cipher Module
=======================

This contains implentations of the IDEA cipher and the MD5 hashing
algorithm.  Both of these implementations were derived from the PGP source
code which were in turn derived as described below.

The main loops of MD5 and IDEA are assembly language coded.  There is a SWI
interface and some easy to use *commands.


-----------------------------------------------------------------------------
IDEA
-----------------------------------------------------------------------------

IDEA (International Data Encryption Algorithm), formerly known as  IPES
(Improved Proposed Encryption Standard). Algorithm developed by Xuejia Lai
and James L. Massey, of ETH Zurich. This implementation modified and derived
from original C code  developed by Xuejia Lai.  Last modified 8 July 92.

The IDEA(tm) block cipher is covered by a patent held by ETH and a Swiss
company called Ascom-Tech AG.  The Swiss patent number is PCT/CH91/00117. 
International patents are pending. IDEA(tm) is a trademark of Ascom-Tech AG. 
There is no license fee required for noncommercial use.  Commercial users
may obtain licensing details from Dieter Profos, Ascom Tech AG, Solothurn
Lab, Postfach 151, 4502 Solothurn, Switzerland, Tel +41 65 242885, Fax +41
65 235761.

The IDEA block cipher uses a 64-bit block size, and a 128-bit key  size.  It
breaks the 64-bit cipher block into four 16-bit words because all of the
primitive inner operations are done with 16-bit  arithmetic.  It likewise
breaks the 128-bit cipher key into eight  16-bit words.

For further information on the IDEA cipher, see these papers:
1)      Xuejia Lai, "Detailed Description and a Software Implementation of 
the IPES Cipher", Institute for Signal and Information Processing,
ETH-Zentrum, Zurich, Switzerland, 1991 
2)      Xuejia Lai, James L. Massey, Sean Murphy, "Markov Ciphers and 
Differential Cryptanalysis", Advances in Cryptology- EUROCRYPT'91


IDEACipher_Idea_KeyInit
-----------------------
This installs the keys for encrypt or decrypt using idea in simple ECB
electronic code-book) mode.

r0 = pointer to workspace of length at least 108 bytes
r1 = pointer to 8 16-bit keys, lsb first (16 bytes)
r2 = 0 => Encrypt, 1 => Decrypt


IDEACipher_Idea_Cipher
----------------------
This does the Ciphering for a block of 8 bytes of data.  Whether it enciphers
or deciphers depends upon the pointer to the workspace and how it was
initialised with Cipher_Idea_Key_Init.

r0 = pointer to workspace as supplied to Cipher_Idea_KeyInit
r1 = pointer to data to cipher 4 16-bit words, lsb first (8 bytes)
r2 = pointer to space for ciphered data 4 16-bit words, lsb first (8 bytes)
The memory pointed to by r1 and r2 may be the same.


*IDEACipher
-----
Syntax:
*IDEACipher <inputfile>
            [-output <outputfile>]
            [-password <passwordtext> | -file <passwordfile>]
            [-encrypt | -decrypt] 

All switches can be abbreviated to just their first letter.  If the switches
are left out then the parameters will be used in the order above.

This encrypt or decrypts the file <input> with IDEA using the password
supplied <passwordtext>.  If no password is supplied then one is prompted
for.  Internally the routine uses MD5 to hash (digest) the password into 128
bits to make the IDEA keys.  You may also supply a file (of any length) to
contain the password <passwordfile>.  If the output is specified then the
output will be written to <outputfile> otherwise it will be written to
<inputfile>.  -encrypt and -decrypt are used to override the automatic
selection of encryption or decryption for example if you wanted to encrypt a
file twice.

The encrypted files are of type &180 and contain within them the full
timestamp, filetype (load, exec) of the original file.  This is restored on
decryption.  If you pass a file of type &180 to idea then it will decrypt it
uless you include -encrypt.  Likewise if you pass a file not of type &180 to
*IDEACipher it will encrypt it unless you specify -decrypt.

Note that case is important in passwords.  Making your password longer than
about 40 characters is probably redundant.  If you wnat to include spaces
in your password on the command line then you will need to enclose it in
quotes.

Examples:
Encrypt or decrypt "document" to "document" using password "acorn"
   *IDEACipher document -password acorn
Encrypt or decrypt "text" to "e_text" using password "archimedes"
   *IDEACipher text -o e_text -p archimedes
Encrypt or decrypt "work" to "work" password will be prompted for.
   *IDEACipher work
Encrypt or decrypt "banana" to "orange" using password file "nuke"
   *IDEACipher banana orange -f nuke
Encrypt "my_mail" to "mail" using password "the bigger the better"
   *IDEACipher my_mail mail "the bigger the better" -e


-----------------------------------------------------------------------------
MD5
-----------------------------------------------------------------------------

The message digest routines used by Cipher are derived from the RSA Data
Security, Inc. MD5 Message-Digest Algorithm.

MD5 is a cryptographically strong message digestalgorithm.  It takes the
fingerprint of the data supplied to it and returns that in 16 bytes of
digest.  To make two messages with identical digests it would take 2^64
operations (=10^18) and to make a message with a given digest would take
about 2^128 (=10^36) operations.  Therefore MD5 can be used, in conjunction
with a public key system capable of signatures (such as RSA), for verifying
authenticity.


IDEACipher_MD5_Start
---------------------
This starts the MD5 algorithm off.  It must be used first.

r0 = pointer to workspace of length at least 104 bytes


IDEACipher_MD5_Update
----------------------
This adds a number of bytes into the digest.  It may be called as many times
as desired between IDEACipher_MD5_Start and IDEACipher_MD5_End.

r0 = pointer to workspace as supplied to IDEACipher_MD5_Start
r1 = pointer to data to add into digest
r2 = number of bytes to add into digest


IDEACipher_MD5_End
------------------
This must be called to finish the MD5 digest calculation.  It returns the
address of the digest.  You may not call IDEACipher_MD5_Update after calling
this.

r0 = pointer to workspace as supplied to IDEACipher_MD5_Start
On Exit:
r0 = pointer to message digest (in workspace) length 16 bytes


*MD5Hash
--------
Syntax:
*MD5Hash <input> [<output>]

This takes the digest of the <input> file and stores in in the file
<output>. The file <Output> will be 16 bytes long and contain the binary data
of the digest.

If the <output> file is not specified then it prints the result as 32 hex
digits plus the file name.


-----------------------------------------------------------------------------
History
-----------------------------------------------------------------------------

0.02 - 03Apr98
--------------

First public release

0.03 - 07May98
--------------

Fixed problem with images files - thanks to Michael Rozdoba for noticing this.

0.04 - 12May98
--------------

Made os_utils.c into its own linkable object and created os_utils.h and
cipher.h for more modular programming (I can tell that I wrote the bulk of
the cipher module 6 years ago ;-)

Recompiled without -zM.  There is some part of the OS which doesn't like
this when you use stdout from a module and causes things to go bonkers. 
Won't be a problem since cipher can't be multiply instantiated and it has no
static data.

Bad OS_GBPB error reported by Michael Rozdoba.  Tracked this down to a
compiler bug which compiling with cc 4.05 fixed.  I haven't tracked it down
further than that.

0.05 - 05Sep98
--------------

Changed *md5 so that it doesn't include any 0 padding on the end of the file. 
It used to round the file size up to a multiple of 256 bytes with 0 padding
for some reason but this makes it different to the MD5 utilities available
with PGP etc.  This is obviously not desireable but changing it will mean
that MD5 checksums users have made with *md5 are now incorrect.  This change
doesn't affect the SWI interface at all.

Changed *md5 so that if you miss out the <output> parameter it prints the
hash in the same format as md5sum.

0.06 - 28 Oct 2001 (Justin Fletcher)
------------------

Updated so that the module name, command names, SWI base, SWI prefix and
error base are now registered with Allocations service. Prior versions are
obsolete as dangerous through not having been registered.

MD5Hash now returns an error if the file specified does not exist.


-----------------------------------------------------------------------------
Author
-----------------------------------------------------------------------------

Nick Craig-Wood
07May98
ncw@axis.demon.co.uk	http://www.axis.demon.co.uk
nick@craig-wood.com	http://www.craig-wood.com
