ARM Club 3/TheARMClub_PDCD3.iso/hensa/internet/b170_1/UserGuide

Text File | 1994-02-06 | 15KB | 262 lines

CipherEngine v0.66 User Guide (ShareWare release)
=================================================

1.1 License
===========
You are licensed to use this application in an unregistered state for
a period of 30 days.  After this time you must either delete all copies
of the software in your posession or register with the author.
You may pass unregistered versions of the software to any other person
on any media even after this period of 30 days (ie if you're a PD
library) provided that you are not using the software yourself.
You cannot use the modules in your own programs unless you are
registered, as the registration fee includes a distribution license.
By breaking the terms of this license you are breaking the law.

Registration costs £5.00.  For this fiver, you get a registration pack
comprising all the source code, a few examples, a manual on disc
detailing all the SWIs in the module, and some other goodies.
You also get free support and you get listened to when you complain!
(you don't if you're unregistered unless you've got something very
good to say!! [I jest -: ??]).  In short, you get a fair bit more than
the single application that you got with this release!  All discs are
high quality 3M floppies, formatted to 800K standard (E-format).
There are some programming examples in the documentation.  All this
ammounts to a very substantial suite of programs for your money.

To register: Send a cheque/postal order for £5.00 made payable to
Mr Seery in a sealed envelope, together with your order form (see below).
You will receive, by first class post, your registered version within
fourteen days, except in exceptional circumstances, although I hope to
turn around orders more quickly than this.

Ordering is made simple by my wonderful ordering program (!).  Somewhere
on this disc you should find an application !Order.  Load it and
double-click on its icon to open up two windows.  Enter your name and
address in the Customer Ordering Details window and toggle the mainshots
button if necessary.  Then select OK and move to the Customer Program
Details window.  This window provides details about the piece of software
under consideration. Select the appropriate piece of software by clicking
menu over the arrow next to the 'Program:' slot and choosing the right
item.  The window displays the program name, cost, and details.
Click 'OK' to order this piece of software.  Quit the program when you've
finished (it tells you how much you owe) and then bung it on a disc
and send it to me.  You get your order processed more quickly if you
use this method, but if you can't find the program then just write a
note specifying which program you want and the total cost.
REMEMBER: When passing the application on to someone else, pass on
a version with no pieces of software marked as ordered.  This entails
copying the program to another disc before using it as the details are
saved inside its directory.

Right, legal stuff over with now:

1.2 Introduction
================
CipherEngine is a module providing encryption and compression utilities
for Acorn Risc OS computers.  It is, to the best of my knowledge, the
only encryption utility providing archiving and encryption suitable
for EMail, as it calculates digital signatures for all files archived
and checks against tampering as they are de-archived.  Unless you are
a programmer you will probably be using the !SureMail application to
create encoded versions of your data.  Programmers should refer to
the Reference Manual supplied with the registered version for details
of the SWIs supported by the module.

PLEASE NOTE: YOU MUST HAVE THE 'SQUASH' MODULE FROM RISC OS 3 LOADED
TO USE THIS APPLICATION! !SureMail works on Risc OS 2 provided that
Squash is present.

Calling all programmers!

Remember that CipherEngine doesn't necessarily have to be used for
encryption.  It includes SWIs for squashing whole directories and single
files, and a variety of other useful bits and bobs.  An example of the
non-cryptographic use of the module is my own trashcan, !TrashFS, which
squashes all trashed files using a CipherEngine SWI.

2.1 !SureMail - User Guide
==========================
Load !SureMail by double-clicking on its icon in a filer viewer.
We are going to simulate a typical EMail session (remember that you don't
have to use !SureMail for EMail - it can be used just for encoding
sensitive data or anything else, for that matter) so you will need a
file or three to test.  If you haven't got anything, use this user guide
as an example.

Click on its icon on the icon bar and a large window will open, but it is
resizable if your display is cluttered.  The basic idea is to "pack" several
files into one file, called an "envelope".  This is analagous to putting
several letters into one real, paper, envelope.  The letters are then
"signed" (using what is known as a Digital Signature) and the "envelope"
is "sealed" (encryption).  You can probably tell that this sort of encryption
is tailored towards EMail, but there is another sort of file (an SEA)
that SureMail produces which is not - see later.
Anyway, fill in the 'To', 'CC', 'Subject', and 'From' fields.  You will
then need to chose two keys.  One is a single letter key - the ID key -
which is used for doubly encoding the details fields that you have just
filled in.  The second - the Envelope Key - is used for encoding the
entire envelope, and this can be up to 16 characters long.  As an aside
into encryption arithmetic, this gives 2^128 combinations (just take my
word for it!) which means that it would take about a trillion years
for an Acorn computer to crack by "brute force" (trying every single
combination until one is found that works).  Longer keys are better than
short ones, but are harder to remember.  You must specify case, spacing,
in fact everything, perfectly.  When you have set this up to your
satisfaction - be very careful entering keys, as they show up as asterisks
to minimise the risk of someone reading it over your shoulder - change
the filename in the writable icon in the 'Save as:' box, and drag the
file icon to a directory viewer.  You can now start adding files, as this
initial setup window disappears, to be replaced by one with a big arrow
in it.  Drag files - or directories - to this arrow to add them to the
envelope.  They are compressed en route, but not encrypted, to minimise
the final encryption time.  When you have finished, click on the OK
button, and the encryption process will start.  At this point, you may
receive a message of the form: 'File size not divisable by 8.  The last <x>
bytes will not be encrypted' where <x> is a number between 1 and 7.  This
means that the encryption algorithm is unable to encrypt the entire file,
and will ignore the last <x> bytes.  This is not a problem, however,
as it would be very difficult to ascertain either the key or the file's
contents from the last - at a maximum - 7 bytes!!  When the encryption
process has finished, another message will pop up telling you how many
centi-seconds (hundredths of a second) it took to encode a file.  The
encoding process is very quick and even for 100k plus files on a floppy
it is likely to be well under 10 seconds.  On a fast ARM3 with a RAM
or hard disc you are unlikely to notice any delay!

At this point the envelope is ready to be sent off either on disc or
via the phone line.  Errors introduced during the transmission of
data will be picked up on when an attempt is made to dearchive the
envelope, which is described below.

To dearchive the envelope, either double-click it (with or without !SureMail
being loaded) or drag it to !SureMail's icon on the icon bar.  A window
will open requesting the passwords and you must type this in EXACTLY as
they were specified when the envelope was created.  The envelope will then
be decrypted.  If you receive the message 'Not a packed envelope' then
you have typed the passwords in wrongly, or the file has suffered so much
damage in transit that it is unreadable to the scanning algorithm.  After
it has been decoded the envelope is useless, so I suggest that you make a
copy of it first and then try decoding the copy.  You will lose all the
data otherwise if something goes wrong (this is partly for security
purposes, if someone illicitly gets hold if the envelope, they are unlikely
to be able to unravel it).  If all went well then two further windows
will open.  One will tell you the details To, CC, Subject, From etc. that
were specified when the envelope was created.  This is a 'transient'
dialogue box which vanishes when you click a mouse button.  The other is
a save window which allows you to save files out from the envelope
one at a time.  The name in the writable icon will be the leafname - the
actual filename - of the file when it was packed.  Just drag it to a
directory viewer to save it out.  If something goes wrong, for example
you get a disc full error, then the program will reset to the beginning
of the file so that you can try again.  The next file will then be displayed
in the save box, and this process continues until there are no more files
to be saved out.  The save box then vanishes and the envelope is securely
deleted - that it, it is overwritten seven times with null bytes and then
removed from the catalogue.  Files deleted in this way cannot be recovered,
even with the use of sophisticated disc editor software or hardware.

The above envelope creation method can be a little long winded if you
are merely creating a single-file envelope.  Therefore there is a short
cut for single file envelopes, which entails merely dragging the file or
directory to the icon on the iconbar and filling in the details in the
window that pops up.  Drag the file icon to the appropriate viewer and
all the envelope creation process is done for you.  Unpacking is as before
and you must use the longer method for more than one file.

A note on directory storage:  There is no provision for directories to
be stored per se in the current file format (this is described in the
manual accompanying the registered version).  Instead, the files are
stored one at a time just as single files, and are unpacked equivalently.
If you need to pack directories as directories then an alternative
method is described below.  If there is enough interest I will add the
ability to pack directories into envelopes as well.

I said earlier on that the envelope type of archive was tailored towards
EMail use.  Indeed it is, but not everyone requires EMail type archiving.
Thus, a seperate type of archive, called a Self Extracting Archive (SEA)
is provided.  SEAs have not been implemented on Acorn machines before
and CipherEngine/SureMail is unique in providing this extremely powerful
facility.  The basic idea is that the file or directory you wish to
archive is compressed into a single file, and encrypted, as for envelope
archives.  The diference lies in the fact that they may be decoded and
dearchived as many times as necessary and also that no seperate decompression
software is required.  Allow me to explain: the archive decodes itself, hence
the name Self Extracting Archive.  All you need do is double click on the
archive icon and a save window is automatically opened.  You enter the
filename and password and then save out in the normal fashion.  Also, SEAs
can store directories and reconstruct them properly unlike envelopes.
However, there is an overhead of about one and a half to two and a half K
depending on the type of archive.

To create an SEA is simple.  You just drag a file or directory to the
SureMail icon with the Control key (Ctrl) presssed down.  A save window
will pop up, which you use in the standard way.  P/W refers to password and
this abbreviation is also used when unpacking the SEA.
When you run an SEA it grabs all the memory available in the Next slot.
However, it is likely to terminate quickly so this should not be a problem.

3.1 Memory Requirements
=======================
The CipherEngine module is about 20k long, and requires about this much
RMA.  SureMail occupies just 32k of application memory, and this is a
consequence of it being written directly in ARM code.  In fact, the
entire system is written completely in ARM code making it very fast
indeed.  However, when compressing/decompressing a certain ammount of RMA
is required as temporary workspace and this can be deallocated after
use.  On a 2Mb or 4Mb+ machine it may be possible to allocate a
once-and-for-all margin but this may not be an option on a memory-restricted
1Mb Acorn (such as what I've got!) so some guide as to memory requirements
is needed.  On the whole, multiply the size of the file you are trying
to encrypt by about two and a quarter and add 10k.  About this much
memory will be required in the RMA.  When packing directories, memory
is claimed and released sequentially so only one file is loaded at once.
The net effect of this is that only as much memory is required as if you
were packing just one file.

4.1 Digital Signatures
======================
To help in verifying the authenticity of a file, a system of digital
signatures is used.  I will not bore you with the internal details
of this system, save to say that it is specified in the registered manual.
It is only fair to point out, as well, that digital signatures are only
applied to envelope archives (because you are - possibly - unlikely to
be sending SEAs instead of envelopes?) and not to SEAs.  If you get
the message 'Digital Signature and counter check disagree' or one
similar then it means that you have had a data dropout in transit or
that someone has fiddled with the code.  SureMail will refuse to
unpack a file that has been tampered with.


That is about all, I think, and it suffices to explain the basic system.
Indeed, the user interface is not all that complicated and was
expressly designed to be so.  The underlying module, however, is
vastly more complex, providing about 34 SWIs dealing with many
diverse subjects.  I apologise for the terseness of this documentation -
if it is terse - but the registered user's manual provides much more
detail (although not about !SureMail).

A final plea.  This package is very powerful and is, I think, the only
supported encryption/compression package on the market.  About
8 months work - research, coding, debugging, writing the documentation -
has gone into this project and a not inconsiderable ammount of money.
The end result is 7339 lines of source code (about 181k), about 50k
of executable program, and nearly 65k of documentation.  You can get
help if you need it - if you're a registered user - and you also
get free upgrades (again, registered users only).  It only costs £5.00
to register and if you think that this is a lot remember that commercial
utilites - if they become available - will cost a lot more.  Please
remember that I am entitled to a living also.

My address is:

        Mr David J Seery
        15 Farm Walk
        Bents Farm Estate
        Littleborough
        Lancashire
        OL15 8LJ

Remember that if you send your order on a disc I'll fill this disc up with
useful goodies and send you your registered version on a seperate disc.
After all, this is only fair.