Readme for CryptRandom module v0.07 (26 Jan 2001)

What?
-----
CryptRandom is a module for generating cryptographically useful random
bytes under RISC OS.

Why?
----
Computers are, by their nature, deterministic - so applying the same sequence
of inputs to any program is likely to produce the same result.  This is a BAD
THING when it comes to cryptography, as if you use a known sequence to
encrypt a data stream, next time you turn on your machine you'll use the same
known sequence, making the code possible to break.  Thus we need a random
sequence so that no pattern can be spotted in it.  Basic provides a
pseudo-random sequence, but this is the same every time the machine is turned
on, so is not very good.  It is also just a sequence, which will eventually
repeat.  True randomness is only possible on a computer by attaching it to
other devices such as a radioactive source - not very practical.  CryptRandom
applies another method, which will produce different values showing to no
known pattern, which are different each time you switch the machine on.  This
is much less secure than using a true random source, but better than using a
predictable random number generator like that Basic uses.

How?
----
CryptRandom is based on code from PuTTY, the Windows SSH client by Simon
Tatham (see http://www.chiark.greenend.org.uk/~sgtatham/putty/).  It consists
of a 'pool' of random data, which is 'stirred' every time a byte is
requested, using a complex hashing function to ensure there is no discernible
pattern.  The pool is supplied by 'entropy' from various sources, designed so
that they are different every time they are called.  The numerous silly
sources include:

On initialisation of CryptRandom:
Unique machine ID
Current WIMP tasks
Current dynamic areas
Disc free space
Disc directory listings
Previous saved CryptRandom seed

Every time a byte is requested:
Real time clock
System interval timer
Battery manager data (voltages/temperatures etc)

Every mouse and key press:
Press data
Mouse position
System timer

Sources are ignored if they don't work (eg a Risc PC doesn't have a battery
manager).

The seed is saved over sessions to preserve the entropy - it'll first look
for <CryptRandom$SeedFile>, and if this is set use this as the seed location,
otherwise try Choices:Crypto.CryptRand.Seed or if Choices: is unset use
<Wimp$ScrapDir>.Seed

I don't claim to prove the security of the hashing process, so I can't
guarantee the randomness of the output, but it appears to be white noise - if
in doubt, do your own tests.  The hash is based on SHA-1, which is believed
by the computing community to be secure.  Any comments in this respect would
be welcomed.

SWIs
----

All SWIs currently corrupt flags.

CryptRandom_Byte (&51980)
  on entry: -
  on exit : r0 = random byte
  Interrupts disabled

This reads a byte from the pool, and subsequently stirs it.

CryptRandom_Stir (&51981)
  on entry: -
  on exit : -
  Interrupts disabled

Stirs the random pool - this should not be necessary in normal use

CryptRandom_AddNoise (&51982)
  on entry: r0 = pointer to block of noise
          : r1 = size of block
  on exit : preserved
  Interrupts disabled

Adds a block of noise to the random pool - shouldn't be necessary in normal
use

CryptRandom_Block (&51983)
  on entry: r0 = pointer to block to store random bytes in
          : r1 = number of bytes to read
  on exit : block is filled in
  Interrupts disabled

Generates a block of random data.  Note this is called with interrupts
off, so large blocks may cause your machine to hang while they are generated.
Note also the entropy generated by this call is likely to be less than
multiple CryptRandom_Byte calls (since times/battery status etc are likely to
be the same during this call, but not if _Byte calls are spread at different
points in your program), so randomness may suffer as a result.

Interrupts are disabled on SWIs as mentioned above - this is to allow
multiple users to access the pool from interrupt routines (events/callbacks
etc) - this may be subject to change in future versions.

Where?
------

Newer versions (if any) of this software may be found at
http://www.markettos.org.uk/
or else by contacting the author at:

email theo@markettos.org.uk

Theo Markettos
5 Willow Close
Liphook
Hants
GU30 7HX
UK

I'd also welcome any bug reports or fixes, or any other comments.

Source
------

Sources can be obtained from
http://www.markettos.org.uk/

To build them you'll need:
Acorn C v4 or v5

SDLS if have Acorn C v4
http://www.excessus.demon.co.uk/acorn/ssr/

Syslog (optional)
http://freenet.barnet.ac.uk/freenet/j.ribbens/syslog-0.17.spk

Makatic (optional)
http://www.mirror.ac.uk/collections/hensa-micros/local/riscos/projects/makatic.zip

OSLib
http://www.mk-net.demon.co.uk/oslib/


Copyright
---------

Copyright 2000-1 Theo Markettos
Portions copyright Simon Tatham, Gary S. Brown and Eric Young

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
SIMON TATHAM OR THEO MARKETTOS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

History
-------

0.07 (26 Jan 2001) Added CryptRandomLicence command to display licence
                   conditions

0.06 (16 Jan 2001) Split SHA digest creation into SHA1 module

0.05 ( 3 Jan 2001) Added CryptRandom_Block SWI

0.04 ( 1 Jan 2001) Now saves seed on Service_Shutdown (finalisation code may
                   not be called on normal shutdown).  Error giving wrong SWI
                   numbers in documentation corrected. Added computation of
                   SHA message digests.

0.03 (12 Dec 2000) Fixed problem where double clicks were being lost on some
                   machines (first click was reading second from mouse queue,
                   and so clearing it)

0.02 (12 Nov 2000) Changed seed path from Choices:CryptRand.Seed to
                   Choices:Crypto.CryptRand.Seed to fit in with SSHProxy

0.01 ( 1 Sep 2000) First version
