    Help file for FSLock
    ====================

   FSLock is designed to provide software locking on any filing system that
has Hard Drive discs on it. When enabled it generates an error on any
deletion/creation and alteration commands that affect the Hard Drives on the
Filing System it is locking. It cannot and will not be able to stop Disc
Sector editors and Formating programs that use the very low level DiscOp SWI
calls.

**NEW** in FSLock 0.19

   FSLock will allow full read/write access to any paths beginning with one
of the following:
  $.!Scrap.ScrapDir.
  $.Public.
This permits the use of the !Scrap application on the locked hard drive(s),
and also the presence of a writable section on any such drive(s). Rename
operations for which the source path is in a writable section and the
destination is in a non-writable section are faulted. Of course renaming
with a source in a non-writable section will be faulted anyway. It is
possible however to copy files from a non-writable section to a writable
section.

Note that this facility can be disabled by simply not copying !Scrap onto
the affected drive, and/or not creating the directory $.Public, as the
trailing "." on the above paths ensures only references to the *contents*
of those directories can be passed through with write access. Thus it is
only possible to create/remove these directories when the drive is unlocked
anyway.

Note also that for !Scrap to be used it must be installed in the root
directory, as it will otherwise not conform to the '$.!Scrap.ScrapDir.'
pathname and will be read-only, which is useless.

   FSLock is controlled totally by an OSCLI command interface which is
detailed below. In all cases where a password is required but not given on
the command line the user will be asked for it in a secure manner by
replacing all typed characters with `*`s. It is intended that this be used
when people are likely to see the password if it is entered on the command
line. In the password query routine Delete and <Ctrl>-U have their normal
effect.

Behaviour. (Not for general consumption)
----------

   FSLock works by intercepting the locked filing system's control block,
much in the same way as Broadcast Loader is said to. It also intercepts the
filing system control vector (FSCV) to catch soft filing system restarts. It
overwrites the FS Control Block with pointers to it's own routines, having
saved their previous contents in private workspace. It then examines each
call passed through these routines to see if locking is needed (usually by
checking the disc name in the pathname). It assumes the pathname will always
be a full one including a disc name, but not (necessarily) the filing system
prefix. The FSCV is intercepted to ensure that the pointers in the FS
Control Block are always intercepted.

   This means, however, that another routine could claim the same vector and
intercept the same call. Which, due to the way the vector system works would
give the other routine a first crack at the FSCB allowing it to note down
the original routine pointers and restore them after FSLock has altered the
block, thus circumventing the protection. This is a complex method and is
not being actively prevented due to the simple fact that anyone competent
enough to intercept the FSCV is capable of bypassing any protections we
could install on the FSCV.

   On startup, the module reads it's allocated (?) CMOS RAM, and verifies
it's validity. If the CMOS is found to be invalid (checksum doesn't
correspond with data), then a default password and filing system (specified
at assembly time) is stored and intercepted. The password is encrypted for
security and space considerations. It will crunch a password of *any* length
into 4 bytes. This means that:
  - There will be many possible passwords which will unlock FSLock
  - Finding them will still be very difficult, as ctrl characters are not
    allowed on the command line.
  - The security of passwords less than 4 characters in length is limited.
    It is recommended that passwords of at least 6 characters in length are
    used, but this is left to the user.

   Because the encrypted password and intercepted filing system number are
stored in the CMOS Ram, saving the CMOS to a file while no filing system is
locked and then restoring it could unlock the system at the next reset of
the module (Power on & hard break ) For this reason the OS_Byte Vector has
been intercepted and writes to the modules CMOS bytes are refused.

   If locking is put into effect after a file has been opened for writing on
the soon-to-be-locked filing system, the file remains open for writing even
after the FS is locked. This is due to the way FSLock intercepts FS_Open
calls, but not calls on open files (which don't provide a full pathname).
OPENUP style operations are converted to OPENINs, so that they can still be
used to read data from the locked drives, but OPENOUTs are intercepted and
fail.

   Finally everytime a filing system call is made that the module would
prevent then it checks it's workspace for validity. If it finds that it's
workspace has been tampered with then it re-scans for the HD names of the
locked Filing System and validates it's CMOS settings as well. This is
intended to prevent people randomly , or otherwise , poking the workspace of
the module to try and circumvent the modules protection. The only areas left
unchecked are the modules copies of the FS entry points and scratch
workspace that gets cleared regularly anyway.

Error Messages.
---------------

&806500 : Unknown FSLock SWI.
          An unknown FSLock SWI has arrived for decoding.

&806501 : A Filing System is already locked.
          Only one FS is allowed to be locked at a time, and this must be
          unlocked before a new one can be locked.

&806502 : There is no such FS currently active!
          An attempt was made to lock a filing system the kernel currently
          knows nothing of (poosibly because it is still dormant). Or you
          screwed up when typing in the name.

&806503 : This is an unsuitable FS to lock.
           An attempt was made to lock a filing system for which locking is
           pointless, eg. ramfs, printer, vdu, kbd etc.

&806504 : No filing system is locked.
          An attempt was made to unlock a filing system when no FS is
          currently locked.

&806505 : Protected disc
          An attempt was made to write to/modify the contents of a locked
          hard drive.

&806506 : No!
          An attempt was made to kill the FSLock module permanently.

In addition to these error messages, the following is displayed when an
incorrect password is entered:-

    Incorrect password.

However this is NOT an error. This is intended to make life difficult for
hackers writing programs to search through password combinations for the
working one.

OSCLI Commands.
---------------

*FSLock_Lock locks the specified filing system from being written to, with
the specified password. Syntax: *FSLock_Lock <FSName> [Password]

*FSLock_Unlock unlocks the currently locked filing system when given the
right password. If the -full flag is not given then the filing system is
only unlocked till the next reset of the machine. Syntax: *FSLock_Unlock
[-full] [Password]

*FSLock_Status reports on whether a filing system is currently locked or
not. Syntax: *FSLock_Status

SWI Commands.
-------------

SWI "FSLock_Version" (&44780)

  On Entry:-

  On Exit:-
    R0 Version number * 100
    R1 Pointer to modules workspace.

  Errors:-
    None.

  Re-Entrancy:-
    Re-Entrant.

  Use:-
       It is intended that modules use this SWI to determine the version number
    of the version of FSLock loaded. It is also used internally by the Vector
    and FS interception code to get the location of the modules workspace. It is
    reccomended that this `feature` not be made publicly available as it makes
    it easy for hackers to get at the modules workspace. (Not that they can't
    find it out via an OS_Module call but why make it easy for them?)

SWI "FSLock_Status" (&44781)

  On Entry:-

  On Exit:-
    R0 contains the numeric version of the modules status. (0-2)
    R1 if R0 is 2 then contains locked filing system number else is
       undefined.

  Errors:-
    None.

  Re-Entrancy:-
    Reentrant.

  Use:-
       It is provided purely for the use of Front End applications to this
module and it reflects the current status of the module. 0 means unlocked
completely , 1 means temporarily unlocked and 2 means fully locked. If R0
is set to 2 then R1 will be loaded with the currently locked Filing System
number. For security reasons this SWI will not be, in the production
version of the module, in the SWI decoding table but *will* be present as a
number. This is to try and obscure the fact that it exists....

Version History.
----------------

+---------------------------------------------------------------------------+
| Version | Comment                                                         |
+---------+-----------------------------------------------------------------+
| 0.01    | Early proto-type. Basically intercepted FS calls and did nothing|
|         |   to them.                                                      |
| 0.02    | Properly claims and releases needed vectors and FS calls now.   |
| 0.03    | Began code on using CMOS. Now reads and stores its password and |
|         |   locking status properly.                                      |
| 0.04    | Added code to vet out certain FS calls. It now locks an entire  |
|         |   FS at a go preventing all write operations.                   |
| 0.05    | Altered the code to use Risc OS 3 SWI calls to scan for Hard    |
|         |   Drives. Now it only prevents writes to drives 4,5,6 & 7.      |
|         |   Extended the locking to prevent the setting of a Hard Drive's |
|         |   name. Has obscure lurking bug which we need to find....       |
| 0.06    | Found and corrected lurking bug. Module now performs as required|
|         |   without causing address exceptions.... (21 Jan 1992)          |
| 0.07    | Fixed RMTidy bug and added the status SWI to the module.        |
|         |   (30 Jan 1992)                                                 |
| 0.08    | Encrypted the encryption routine. (4 Feb 1992)                  |
| 0.09    | Fixed another little lurking bug to do with OPENOUT not getting |
|         |   trapped... (6 Feb 1992)                                       |
| 0.10    | Changed -temporary to -full with default unlocking now being    |
|         |   always temporary. (6 Feb 1992)                                |
| 0.11    | Added OS_Byte validation code and workspace integrity checks.   |
|         |   Added a correction to the String Comparison code but am unable|
|         |   to check this quite yet.... (9 Feb 1992)                      |
| 0.12    | Corrected an error in the workspace paranoia routines. Guess who|
|         |   likes comparing bytes to words.... <Blush> (17 Feb 1992)      |
| 0.13    | Corrected an error in the initialisation code and recoded the   |
|         |   module to use the assigned SWI chunk and error chunk.         |
|         |   (26 Mar 1992)                                                 |
| 0.14    | Corrected an error in the Password routine that caused problems |
|         |   when <Ctrl>-U ing an empty string. (28 Mar 1992)              |
| 0.15    | Applied change to drive scanning routine in an attempt to avoid |
|         |   problems when there is no hard drive (eg after DEL-PowerOn)   |
|         |   We can't be 100% sure that it is fixed until it is tested in  |
|         |   an EPROM though. (29 Apr 1992)                                |
| 0.16    | Fixed intermittent floppy-locking bug which only shows up when  |
|         |   Impression Junior 1.16 has been loaded (for some strange      |
|         |   reason). CMPs can actually SET the V flag. Guess how we were  |
|         |   vetting the various FSEntry_File opcodes? Yeah. CMPs. Now     |
|         |   explicitly doing "cmp r0,r0" all over the place to clear V.   |
|         |   (21 Aug 1992)                                                 |
| 0.17    | This time we *REALLY* fixed the above error. Seems we were      |
|         |   unnecessarily trapping FSEntry_Args... this was leading to    |
|         |   problems when calling OS_Args 3 or 8. (21 Aug 1992)           |
| 0.18    | Added ResourceFS, PipeFS, DevicesFS and ArcFS to the list of    |
|         |   silly-to-lock filing systems. (22 Aug 1992)                   |
| 0.19    | Added '$.!Scrap.ScrapDir.' and '$.Public.' exceptions to write- |
|         |   protection. This means that if present:                       |
|         |     - The !Scrap utility can remain on the locked drive.        |
|         |     - There can be a writable partition on the locked drive.    |
|         | Removed RamFS from silly-to-lock list.                          |
|         | Removed the *Opt 4 locking to prevent spurious errors due to    |
|         |    re-entrancy problems. (26 Aug 1992)                          |
| 1.00    | Version for commercial release. Module code integrity checking  |
|         |    added to prevent snooping of the code via breakpoints.       |
|         |    (04 Sep 1992)                                                |
+---------+-----------------------------------------------------------------+
