Monster Media 1994 #1/monster.zip/monster/MODEM/OZPKE12A.ZIP/OZPKE.DOC

Text File | 1994-01-12 | 54KB | 1,199 lines

            ╔═════════════════════════════════════════╗
            ║   OzCIS Public Key Encryption utility   ║
            ║                 OzPKE                   ║
            ║      Copyright 1993 by Donald Moe       ║
            ║            CIS:72407,1054               ║
            ╚═════════════════════════════════════════╝

                                             12 January 1994
                                             OzPKE Version 1.2

Synopsis:
---------

This utility program, OzPKE, works in conjunction with Steve Sneed's
automated CompuServe access program OzCIS (v2.0a) and ViaCrypt PGP
program (v2.4) to assure secure communications via electronic mail.

Note to current users: Previous releases of the program consisted of two
modules that have now been combined into one. This requires a change in
the decryption command in "Externals Menu" (see below).

The goal is to simplify public key encryption of outgoing and decryption
of incoming messages and files passing through the CompuServe Information
System. Both direct electronic mail and forum messages as well as file
attachments are supported.  OzPKE handles encryption of outgoing messages
and files as well as decryption of incoming messages and received files.

Although the user could use whatever public-key encryption software he
chooses, provided it supports command-line operation, the recommended
program is ViaCrypt PGP system since OzPKE makes use of PGP's public
keyring file and specific features of that program.

Refer to documentation for PGP for a thorough discussion of message
and file encryption and decryption.


Legal Issues:
-------------

OzPKE is (c) Copyright Donald Moe, 1993.

OzPKE are made available for personal use at no charge by the author.
Commercial users are required to contact the author to license use of the
software after a trial period of 14 days.

The author assumes no liability for damages resulting from the use of this
software, even if the damage results from defects in this software, and
makes no representations concerning the merchantibility of this software
or its suitability for any specific purpose. It is provided "as is"
without express or implied warranty of any kind.


Quick Start:
------------

To install and start using OzPKE quickly, perform the following steps.

1) Install and configure PGP according to its instructions.

2) Install a file viewing program, such as Vernon Buerg's LIST.COM.

3) Copy OzPKE.EXE and OzPKE.CFG into the directory where OZCIS.EXE is
   located.

4) Edit OZPKE.CFG to conform with your system. (See Configuration file
   below.)

5) Enter macro definitions under menu entry "Configuration/Kbd Macros"
   (See Macros below) or copy the supplied KBD.MAC file to the OzCIS
   directory.

6) Add three external program definitions under "Tool/External Menu".
   (See External Menu below.)

The following steps assume that the corresponding macro definitions have
been entered with the same control keys.

To send messages:

1) Compose each message as if it were to be sent as a normal plain-text
   message.

2) Place cursor on any blank line within the message or at end and press ^P
   and/or ^S to insert the trigger phrases for private and/or signature on
   separate lines.

3) Store the message for sending (Alt-S). Enter addressee and subject as
   normal.

4) Prior to the on-line session, press Ctrl-E to perform encryption on
   all outgoing messages.

5) When a window appears with names of recipients, select proper addressee
   from the list and press return. If addressee is not found, press Esc to
   cancel, the message will remain unencrypted in the outgoing message file.

6) Log onto CompuServe as normal. Encrypted messages will be sent along
   with any plain-text messages without further user intervention.


To send a message with an attached file:

1) Perform steps 1 and 2 the under previous section, "To send messages".

2) With Alt-T request a file attachment and enter the name of the file to
   be sent. Set "Upload as ASCII" to "Y" for a file that should be sent as
   an ASCII-armored file. If set to "N", the file will be uploaded as a
   normal binary file and cannot be sent through the Internet gateway.

3) Continue with "Step 3" above.


To view an encrypted message or decrypt an encrypted file:

1) An encrypted message can be recognized by the header text at the start
   of the message:
      -----BEGIN PGP MESSAGE-----
   or
      -----BEGIN PGP SIGNED MESSAGE-----

2) While this message is in the OzCIS reader, press Ctrl-D to decrypt and
   display the corresponding plain-text message. If the "Subj:" line
   contains the word "Upload:", the message will be processed as an ASCII
   encoded binary file and will be stored in the directory specified by
   ASCDEC in the configuration file.

3) After reading decoded message, press Esc to return to OzCIS mail
   reader.


To force decryption of newly received encrypted file when the automatic
recognition failed. This may be needed when encrypted ASCII files are
received from Internet users or those using software other than OzCIS.

1) An encrypted file can not be destinguished from a normally encrypted
   message:
      -----BEGIN PGP MESSAGE-----
   or
      -----BEGIN PGP SIGNED MESSAGE-----

2) While this message is in the OzCIS reader, press Ctrl-F to force
   decryption of the message as an ASCII encoded file.

3) The resulting file will reside in the directory specified by the
   parameter ASCDEC in OzPKE.CFG.


To add a new public key to PGP's PUBRING.PGP:

1) In message reader, display message containing public key block with the
   header text:
      -----BEGIN PGP PUBLIC KEY BLOCK-----

2) Press Ctrl-X to have PGP process the public key block and add the new
   key to your public key ring.


Alternatively, if public key block has been reformatted by CompuServe's
forum software, so that the data block is incorrect, such as:

   -----BEGIN PGP PUBLIC KEY BLOCK----- Version: 2.4

   mQBNAixXGf0AAAECAMRsXjUbf8fHvaR2+LHq2ZtgyvCtIXlhjmBP0+96ep8sX3o7
   TCdBchTGuxcnVnYr9kye57sAV4eumFGdB8hhx6UABRG0KURvbmFsZCBLLiBNb2Ug
   PDcyNDA3LjEwNTRAY29tcHVzZXJ2ZS5jb20+ =eNRX -----END PGP
   PUBLIC KEY BLOCK-----

Use the following procedure to add a new public key to PGP's PUBRING.PGP:

1) In message reader, display message containing public key block with the
   header text:
      -----BEGIN PGP PUBLIC KEY BLOCK-----

2) Mark the entire block including entire end-block text by positioning
   cursor at start, press Ctrl-KB, move to end and press Ctrl-KK.

3) Press Ctrl-C to copy this marked block into OzCIS's general editor.

4) Correct formatting so that the data block appears like this (but not
   indented):

   -----BEGIN PGP PUBLIC KEY BLOCK-----
   Version: 2.4

   mQBNAixXGf0AAAECAMRsXjUbf8fHvaR2+LHq2ZtgyvCtIXlhjmBP0+96ep8sX3o7
   TCdBchTGuxcnVnYr9kye57sAV4eumFGdB8hhx6UABRG0KURvbmFsZCBLLiBNb2Ug
   PDcyNDA3LjEwNTRAY29tcHVzZXJ2ZS5jb20+
   =eNRX
   -----END PGP PUBLIC KEY BLOCK-----

4) Press Ctrl-W to let PGP process the corrected public key block.


Operation:
----------

For outgoing traffic each message in the OzCIS ".REP" files is scanned for
the trigger keywords.  If the ##SIGNATURE## trigger is found on a separate
line in the message text, a public-key encryption (PKE) tool is used to
apply a digital signature to the message.  If the ##PRIVATE## trigger is
found in the message text, the PKE program is used to scramble the text of
the message.  If both triggers are found, both operations are performed in
a single step. The trigger words, including the enclosing ## characters,
must each appear left-justified on a separate line and be spelled exactly
(all upper case, no spaces, etc.) in order to be recognized. Macros can be
used to facilitate entering these trigger words.

The encrypted message replaces the plain-text message in the outgoing
message file and can no longer be read, unless the command flag was
enabled to save the messages to the associated outbox file (See OUTBOX
below).

Alternatively, the command UPLASCII can be set to Yes in OzPKE.CFG so that
the encrypted message is not stored in the outgoing message file. Rather
OzPKE causes OzCIS to upload the message with protocol to CompuServe MAIL
as an ASCII file. The ASCII file generated by PGP will be stored in the
path specified by UPLPATH with a filename based on the current date and
sequential number.  This feature was added to combat corruption of the
ASCII block during transmission to CompuServe. This capability is not
available for forum messages.

Additionally, OzPKE can handle a file attached to a message. If the main
message with the attached file is marked for encryption, the attached file
is also encrypted, either as a binary or an ASCII-armored file depending
on whether "Upload as ASCII" is answered with "N" or "Y", when the
attachment is specified.  Both the main message as well as the attached
file are encrypted. The attached file does not need to be compressed
beforehand since PGP automatically performs that step. For example, it
thus becomes extremely easy to securely transmit a spreadsheet data file,
even over the Internet gateway. The attached files can be sent with the
same level of security as the main message, except that Signature Only is
not available. Separate directories can be specified for the ASCII and
binary file uploads.

Warning: the resulting ASCII-armored attached files can become very
lengthy and possibly exceed the message length limit to Internet
recipients. PGP can accommodate this problem with the setting
"ARMORLINES=" in its configuration file, CONFIG.TXT. If this setting is
non-zero, PGP will automatically split lengthier message files into chunks
and sequentially number them starting with the extension AS1 or A01. A
setting of 220 lines results in message chunks of approximately 15KB
length. The current version of OzPKE is not yet capable of coping with
this situation but a fix is under development.

For incoming traffic, the user activates the decoding process when
he sees an encoded message on the screen of the message viewer. The
message will be decoded into a temporary file, preferably on a RAM disk,
and can then be read using a common viewer program, such as Vernon Buerg's
LIST.COM (not supplied). After being viewed, the temporary file is
deleted.  The OzCIS message file retains the encoded text block. (A later
version may allow the decoded message to be appended to the associated
message file.)

OzPKE also handles decryption of received files that have been encrypted
as ASCII or binary files. See "Decrypting Encrypted Files" below.

In OzCIS, macros can be defined to perform multiple operations. Several are
used to simplify OzPKE operation. (See macro definitions.)

OzPKE runs via the DOS gateway of OzCIS, which leaves a very small
footprint in memory during the gateway. When OzPKE activates PGP, it
likewise swaps out to EMS, XMS or disk, thus leaving a similarly small
footprint in memory. For OzPKE to have any EMS or XMS available, set the
parameter for OzCIS' protected mode to a value less than maximum available
memory, example "SET DPMIMEM=MAXMEM 4096".

Each message in each specified .REP file is scanned for the presence of
trigger words on lines by themselves, which produce the following effects:

   ##SIGNATURE##   Create a digital signature for this message.

   ##PRIVATE##     Encrypt this message, using the recipient's public key.

Any message containing these trigger words will have the appropriate OzPKE
magic done to it, and when OzPKE is finished, all processed .REP files
will contain the signed/encrypted forms of those messages that were
flagged for signature or encryption, plus the originals of messages that
didn't need a signature or encryption or that could not be encrypted since
the recipient's public key was not available.

When encryption is to be performed on a message, OzPKE will first attempt
to locate the recipient's CompuServe or Internet Email address in the
public key ring file. If an exact match is found, the message is
automatically processed. Otherwise OzPKE will display a pop-up pick list
in which the nearest match to the recipient's name is highlighted. The
user must select and/or confirm the proper recipient using the up/down
arrow keys and press return. If no matching recipient is available,
pressing Esc will cancel the encryption on that message, to continue with
the next one. The cancelled message will remain in the outgoing message
file so that the user can change, hold, or delete it within OzCIS.

The technique for properly matching Email addresses to those in PUBRING
assumes that the entries in PUBRING conform to the format recommended in
the PGP documentation, such as:

for CompuServe addressees:
   <[e-mail]>
or
   <72407,[e-mail]>
is also recognized,

or for Internet addressees:
   <[e-mail]>

The enclosing characters "<" and ">" are required to assure that a partial
match does not result in an incorrect recipient being selected.  If no
match is detected, the pick list will appear as before. Case is
irrelevant.

The addresses of the outgoing messages should conform to the usual
CompuServe formatting, for example:

      First Last 70000,0000
   or
      Name INTERNET:[e-mail]

When OzPKE is done, OzCIS resumes operation at the same place it was
interrupted. The messages files can be sent normally at the next logon
session.

By default OzPKE makes a "backup" of your original .REP file by renaming
the original file to *.BAK.  If no backup file is desired, set the BAK
parameter in the configuration file to N.

As OzPKE is merely an interface program to PGP, the messages output by PGP
are still displayed on the screen and should be read in case of possible
error conditions. OzPKE will evaluate any error code returned by PGP and
display any non-zero code with a brief error message. The message box will
indicate whether the encryption or decryption section of the program is
reporting the error.


Command Inputs:
---------------

If no parameter is provided on the command line to OzPKE, a copyright
notice and brief description are displayed. A dummy parameter, X, is
required in the programs' definitions in OzCIS' External Menu for proper
operation of OzPKE. For decryption, a "-d x" is required on the command
line.  (All command line switches to OzPKE can be in the form "-d", "-D",
"/d" or "/D", as all of these forms are equally acceptable.)

If the password to PGP's secret ring file has not been specified in
OZPKE.CFG, it should be passed on the command line. This is accomplished
by defining the command under Externals Menu (see below) as shown in the
second alternative.  Each time OzPKE is activated, OzCIS will prompt for
the command line parameter. Enter just the password phrase.  Leading and
trailing blank space will be removed. Unfortunately there is no way to
suppress the echo in OzCIS' parameter input line, therefore caution is
advised in the presence of others.

The password string is temporarily inserted into the current environment
buffer with the environment variable PGPPASS. This works fine with PGP but
possibly not with other PKE programs. Thus multiple messages can be
processed without requiring the user to reenter the password for each one.
After completion, the password string is removed from the environment
buffer. If the environment size is insufficient to accommodate the password
string, a temporary environment with the minimum required entries will be
used.

The values used in OZPKE.CFG for SIGO, PRIV, SIGP, BINSIG, BINPRV, DECODE
and FILEDECODE naturally depend on which public-key encryption program is
selected by the user, as configured in OZPKE.CFG. If something other than
PGP was chosen, then the user is on his own to figure out what kind of
command-line parameters are required to achieve these desired results. It
may be necessary to create a .BAT file or other "wrapper" to accomplish
this.

If a program other than PGP is chosen, the main things to consider are that
 1) the plain-text message is written to "MAIL.IN" in the temporary
    directory for the PKE program to use as input,
 2) the encoded output from the PKE program has to be left in a file
    called "MAIL.PGP" because that's where OZPKE expects to find it, and
 3) any signature blocks or ciphertext emitted by the alternative PKE
    program must be "armored," or encoded as e-mailable ASCII characters,
    similar to the RADIX-64 format used by PGP.

The default options achieve this with PGP. Both "MAIL.PGP" and "MAIL.IN"
are workfiles, and are deleted after OzPKE has completed its work.

When the encoded ASCII messages are to be uploaded using protocol by
OzCIS, the file MAIL.PGP is not used for temporary storage, rather the
encoded messages are stored under sequentially numbered filenames based on
the date.

OzCIS supports a two optional settings in OZCIS.INI for pre- and post-
processing of messages: ReadPreProcess and CompPostProcess.

If "ReadPostProcess=\ozcis\ozpke -d x", OzCIS will inquire whether the
message file should be processed. Unfortunately this is not compatible
with the way OzPKE was designed to decrypt, whereby the encrypted messages
should be retained in secure form and only decoded on an individual basis
as required. However, if any users are not concerned about this aspect and
would prefer to have all messages decoded in a batch process and only
stored as plain-text, they should express this desire to the author of
OzPKE and this operation may be implemented in a future version.

If "CompPostProcess=\ozcis\ozpke x", OzCIS will inquire whether the
message just written should be processed. This works just fine on a
message-by-message basis and reminds the user to process each message, as
intended, but the capability of OzPKE to process multiple outgoing
messages in one pass can no longer be used to full advantage. Furthermore,
if messages are sometimes modified after being initially written but
prior to transmission, this is difficult if each message is encrypted
immediately after being written. For these reasons, the author prefers not
to set "CompPostProcess" and instead presses ^E just prior to the online
session. If a message is addressed to a recipient whose public key is not
available, this message can then be modified or killed prior to
transmission.


WARNING:
--------

Starting with OzPKE 1.1, the configuration file contains the parameter
WIPE, which will cause the work and message files containing plain-text to
be overwritten with the byte 0xFF and also filled to the next cluster
boundary. The operation is performed after all other operations have been
completed. The files affected by OzPKE are MAIL.IN, CISMAIL.REP, and
OZPKE.SWP, and MAIL.TXT and OZPKD.SWP when decrypting.

If the WIPE parameter is left to default setting of "No", then OZPKE does
not overwrite the MAIL.IN file containing the plaintext of the last
message encrypted. It merely deletes the file from the directory. You can
set a PGP option to overwrite or "wipe" this file if you like. See the PGP
documentation for details. However, if this is done, the original
plain-text messages cannot then be copied to the associated outbox files
since this step is only performed after the message has been successfully
encrypted. Hence it is better to set WIPE=Yes if the file should be wiped.

During processing, the new outgoing .REP file has the temporary extension
".R$P" until the operation has been completed. The original, unencrypted
".REP" file is renamed to ".BAK" and the ".R$P" is renamed to ".REP". The
BACKUP command in OZPKE.CFG determines whether backups of the files are to
be made.

Even if the original .REP files are deleted, traces of them may still be
accessible on the disk and therefore could be recovered by those with
adequate skills, unless the WIPE parameter is set to "Yes".


File Inputs:
------------

1) OzPKE first accesses its configuration file, OZPKE.CFG, which must be
   located in the same directory where OzPKE resides.

2) OzPKE automatically accesses several OzCIS (v2.0a) configuration files
   to determine the locations of the necessary message files:

   a) HOSTS.DB    contains path to forum directory for currently active
                  CompuServe host node.

   b) FORUMS.DB   contains names of the active fora and paths to their
                  message files.

3) OzPKE also accesses PUBRING.PGP, the file containing all known public
   keys of possible correspondents. The names are extracted and stored for
   quick access in OZPKE.STM. Updates to PUBRING.PGP are detected so that
   OZPKE.STM is likewise updated. Since the internal file structure of
   PUBRING.PGP is not available, PGP is called with the command "-kv *
   pubring" with output redirected to a temporary file, from which OzPKE
   then extracts the required information. This procedure may change in
   future versions.

4) OzCIS CISMAIL.REP and possibly the active forum *.REP files, as
   specified in the configuration file.


File Outputs:
-------------

OzCIS *.REP files, with messages signed and encrypted as directed.

If UPLASCII is set to Yes in OzPKE.CFG, PGP will encrypt into an ASCII
file in the directory specified by UPLPATH using filenames based on
current date and sequentially numbered extensions, e.g. AS931118.000. A
maximum of 1000 encrypted messages can thus be sent per day. These files
will be attached to an ASCII upload message header in CISMAIL.REP for
automatic uploading by OzCIS, but will not be automatically deleted after
sending. This housekeeping is currently left to the user to perform.
(Suggestions from users on how to automate this step would be welcomed.)

Any files attached to messages that are encrypted will also be assigned a
name according the same scheme, e.g. AS931118.001 or BN931118.001,
depending on whether the attached file is ASCII or binary. The originally
attached files are not deleted nor wiped.


Work Files:
-----------

Up to four temporary work files are created as OZPKE runs.

In the temporary directory, normally on a RAM disk:

 MAIL.IN       contains the plaintext of the message currently being
               processed.

 MAIL.PGP      the encrypted/signed version of the message as output by
               PGP, except when uploading messages as ASCII files.

 MAIL.M$G      will be created if a message needs repair and then renamed
               to MAIL.PGP.

In the OzCIS mail and forum directories:

 CISMAIL.R$P   file containing outgoing messages or upload control blocks
 <forum>.R$P   after processing by PGP.

The MAIL.IN file's maximum size is the length of your longest message, not
including headers and control information.

The MAIL.PGP file's maximum size may be somewhat larger than MAIL.IN,
since an encrypted message may be bigger than its plaintext form and
signed messages contain extra lines for the signature block, but it's
still about as large as the longest individual message.

The CISMAIL.R$P and <forum>.R$P files are replacements for the input .REP
file, so they will be about the same size or a bit larger than the
original .REP file. Therefore adequate space should be available on the
OZCIS disk to accommodate the necessary files.

All work and swap files are deleted when OZPKE is finished, but not
overwritten unless the parameter WIPE is set to "Yes" in OzPKE.CFG.

As OzPKE performs a DOS gateway, it needs to have adequate disk storage
available for the swap files, if insufficient EMS or XMS memory is
available. The file size is approximately 170KB.


Receiving Encrypted/Signed Messages:
------------------------------------

With "-d x" on the command line, OzPKE controls the decryption process for
messages, verification of signatures and/or adding of new public keys to
the public key ring. For this to work properly, the message must be
exported to the file MAIL.PGP in the same temporary directory as for
OzPKE.  This export operation is performed by a macro.

After PGP completes the decryption, the resulting plain-text output file
will be displayed by a file viewing program, such as Vernon Buerg's
LIST.COM, or any ASCII text editor.  After viewing, the intermediate
plain-text file can be wiped as well as deleted if WIPE=Y in OzPKE.CFG.
However, if the parameter KEEP in OzPKE.CFG is set to Y, the plain-text
file is retained to allow the user to then import it into the OzCIS reply
editor to allow quoting. A suitable macro may be used to facilitate this
operation.  (See definition for ^R under Macros and user suggestion at end
of documentation.) If the file should be wiped after quoting, the ^R macro
should be modified to activate a suitable batch file, which could call a
program such as Norton's WIPEINFO.

Alternatively, the decrypted plain-text message can be appended to the
file CISMAIL.MSG for storage, as determined by parameter APPEND in the
configuration file. The header of the original message is extracted from
MAIL.PGP and used for the new entry in CISMAIL.MSG. In such cases, the
file viewer, LIST.COM, is not activated. NOTE: Unfortunately this function
does not yet work correctly since OzCIS does not reload CISMAIL.MSG after
doing a gateway to DOS, hence it then overwrites the message file from
it's internal buffer. When a new release of OzCIS appears, this limitation
will hopefully be lifted.

Apparently text messages sent to CISMAIL occasionally suffer from minor
corruption, typically an extra blank at the start of a line around line
10. Although this can now be overcome by uploading the messages as ASCII
files, other users may not send their messages this way, so that you may
have to correct this problem. PGP will report the error and refuse to
decode messages with such corruption, albeit minor. In this case, PGP
returns errorlevel 1 (Invalid File).

A similar problem occurs when the PGP block has been indented. In this
case, PGP returns errorlevel 3 (Unknown File).

In both of these cases, OzPKE will automatically attempt to correct the
problem by copying the file, removing leading blanks from lines within
each PGP block in the file and also discarding extraneous text outside the
PGP blocks. PGP is then called for a second attempt.  If the repair
procedure succeeded, PGP will properly decode the ASCII message. During
this process may PGP may beep and display an error message.

If the repair effort was not successful, possibly due to additional
formatting errors within the PGP block, use the ^KB and ^KK commands to
mark the PGP message block in the message viewer. Copy this block to the
MAIL.PGP file in the temporary directory specified in OzPKE.CFG, such as
with the macro defined for ^C (see macro definitions), which copies the
block into the OzCIS general editor. Edit the file MAIL.PGP to correct the
formatting errors, press F2 to save it and then Esc to leave the editor.
Now press ^D again.  OzCIS will again export the message to MAIL.PGP,
appending the new text to the existing file, and then activate OzPKE.

Since PGP will process multiple messages within an input file, it will
still report the error in the first message, but will then successfully
process the second, corrected one. Due to the automatic recovery process,
just described, OzPKE will still try to repair the defective file and
activate PGP. This may result in several beeps and error messages until
PGP successfully processes the non-corrupted message in the file.


Decrypting Encrypted Files:
---------------------------

OzPKE also handles decryption of received encrypted ASCII or binary files.
Two directories may be specified to receive the ASCII or binary files
following decryption. Attempts to decrypt non-encrypted files yield an
appropriate error message. The decrypted file is automatically named with
the original filename by PGP.  When PGP attempts to create the decrypted
file, it checks whether an existing file may already exist and in that
case asks the user whether the file should be overwritten. If the answer
is No, the default, PGP prompts for an alternative filename.  After
completion the user is alerted in a message box to the name of the
resulting file and directory.

If the incoming message is an ASCII file, OzPKE recognizes it as such when
the subject line consists of the phrase "Subj:  Upload:". If the message
points to a downloaded binary file, the phrase "% Message is Binary"
causes OzPKE to handle the file appropriately.

If the incoming ASCII file does not have a recognized "Subj" line, OzPKE
will process the file as a readable text file. If that is incorrect, press
Ctrl-F instead of Ctrl-D to force OzPKE to process the message as an ASCII
encrypted file. (See macro definitions below.) This procedure will probably
be needed for files received from Internet correspondents or those using
software other than OzCIS.

For alternative PKE programs, the parameter FILEDECODE needs to be set
appropriately in OZPKE.CFG.


Software Requirements:
----------------------

OzPKE was tested with MS-DOS 5.0, OzCIS 2.0b/c, ViaCrypt-PGP 2.4 and PGP
2.3a on 486/33 and 386/33 computers with QEMM 6.02 installed and Lantastic
5.0 loaded.  It may well work with earlier or later versions of those
related products, but the author doesn't know that for a fact. If anomalies
are observed when using other computer configurations, please report them to
the author at his CIS address 72407,1054. Files are opened in the
appropriate Share mode as appropriate, so that operation in a network
environment should present no difficulties.

Since OzPKE operates by invoking your PKE software, you must have your
chosen PKE package installed and working properly before OzPKE can function.


Forum limitations:
------------------

Although it is technically possible to post encrypted messages in a public
forum on CompuServe, this activity is frequently discouraged or outright
forbidden, including signatures on plain-text messages. Two general
principles should be obeyed in this regard:

 1. Don't post an encrypted message in any forum that has disabled the
    "private message" feature.  If they wanted you to have private
    side-conversations, they'd enable the forum feature that supports
    them.

 2. Don't use signatures in public messages unless you see that they're in
    common use in that particular forum.  In some forums, the sysops and
    most of the users regard the extra six or seven lines of hash as a
    waste of time--they're not generally going to bother with validating
    signatures anyway, and they don't want to pay to download the extra
    text. If in doubt, ASK the sysop.

Therefore, by default OzPKE ignores forum message files.


Macros:
-------

The following macros are recommended for smooth operation of OzPKE and
must be carefully entered into OzCIS's macro editor (Configuration/Kbd
Macros) or just use the version supplied in the distribution file. Adjust
the path to MAIL.PGP within the macros as appropriate.

Other activation keys may certainly be used instead of the following
control-key combinations, if desired, but beware of conflicts with normal
keyboard commands. ^ signifies a Ctrl-key combination.

Insert signature trigger: ^S
   <Home><Enter>##SIGNATURE##<Enter>

Insert private trigger: ^P
   <Home><Enter>##PRIVATE##<Enter>

Decrypt currently displayed message: ^D
   <AltM>vtG:\TEMP\MAIL.PGP<Enter><Alt1><Down><Enter>

Force decryption of currently
displayed message as ASCII file: ^F
   <AltM>vtG:\TEMP\MAIL.PGP<Enter><Alt1><Down><Down><Down><Down><Down><Enter>

Encrypt outgoing messages in CISMAIL and active forum message files: ^E
   <Alt1><Down><Down><Enter>

Add key to PUBRING.PGP: ^X      (use when text block not mangled)
   <AltM>vtG:\TEMP\MAIL.PGP<Enter><Alt1><Down><Down><Down><Enter>

Add mangled key to PUBRING.PGP: ^W   (use when mangled text block has been
                                      corrected in editor)
   <Alt1><Down><Down><Down><Enter>

Copy marked block to general editor: ^C
   <^J>c<AltO>gG:\TEMP\MAIL.PGP<Enter><^J>p<^K>h

Load decrypted message into Reply editor: ^R
   <AltR><^K>rG:\TEMP\MAIL.TXT<Enter><^K>h

Delete MAIL.TXT in temporary directory: ^Z
   <Alt1><Down><Down><Down><Down><Enter>

Note: Key codes within brackets <..>, such as <AltM>, are entered in
OzCIS' macro editor by pressing the corresponding key combination. For
<Enter> and <Down> press the Scroll-Lock key first.  (Refer to OzCIS
documentation.)

Several macros contain <Down>, which refers to the cursor-down key. This
must match with the associated commands in the External Menu. This is
critical for proper operation of the programs!


External Menu:
--------------

Three external definitions must be entered in the External Menu and must
be sorted into the top positions in this order. THIS IS CRITICAL! Change
paths as appropriate.

1)  DOS Gateway -- already defined.

2)  Decrypt Received Mail Message:

       ╔════════════════ Externals Definition ════════════════════╗
       ║ Title        Decrypt Received Mail Message               ║
       ║ Command Line \ozcis\ozpke.exe -d x                       ║
       ║ Use 2nd Cmd Processor? N     Pause after execution? N    ║
       ║ Prompt for Params?     N                                 ║
       ║                                                          ║
       ║             F10-Ok ▄           Cancel ▄                  ║
       ║             ▀▀▀▀▀▀▀▀           ▀▀▀▀▀▀▀▀                  ║
       ╚══════════════════════════════════════════════════════════╝

    If no password to PGP's secret ring has been defined in OZPKE.CFG,
    then change the Externals definition as follows:

       ╔════════════════ Externals Definition ════════════════════╗
       ║ Title        Decrypt Received Mail Message               ║
       ║ Command Line \ozcis\ozpke.exe -d -p                      ║
       ║ Use 2nd Cmd Processor? N     Pause after execution? N    ║
       ║ Prompt for Params?     Y                                 ║
       ║                                                          ║
       ║             F10-Ok ▄           Cancel ▄                  ║
       ║             ▀▀▀▀▀▀▀▀           ▀▀▀▀▀▀▀▀                  ║
       ╚══════════════════════════════════════════════════════════╝

3)  Encrypt Outgoing Messages:

       ╔════════════════ Externals Definition ════════════════════╗
       ║ Title        Encrypt Outgoing Mail Messages              ║
       ║ Command Line \ozcis\ozpke.exe x                          ║
       ║ Use 2nd Cmd Processor? N     Pause after execution? N    ║
       ║ Prompt for Params?     N                                 ║
       ║                                                          ║
       ║             F10-Ok ▄           Cancel ▄                  ║
       ║             ▀▀▀▀▀▀▀▀           ▀▀▀▀▀▀▀▀                  ║
       ╚══════════════════════════════════════════════════════════╝

    If no password to PGP's secret ring has been defined in OZPKE.CFG,
    then change the Externals definition as follows:

       ╔════════════════ Externals Definition ════════════════════╗
       ║ Title        Encrypt Outgoing Mail Messages              ║
       ║ Command Line \ozcis\ozpke.exe -p                         ║
       ║ Use 2nd Cmd Processor? N     Pause after execution? N    ║
       ║ Prompt for Params?     Y                                 ║
       ║                                                          ║
       ║             F10-Ok ▄           Cancel ▄                  ║
       ║             ▀▀▀▀▀▀▀▀           ▀▀▀▀▀▀▀▀                  ║
       ╚══════════════════════════════════════════════════════════╝

4)  Update PGP Key File:  (change paths in NEWPUB.BAT as required)

       ╔════════════════ Externals Definition ════════════════════╗
       ║ Title        Update PGP Key file                         ║
       ║ Command Line \ozcis\newpub.bat                           ║
       ║ Use 2nd Cmd Processor? Y     Pause after execution? Y    ║
       ║ Prompt for Params?     N                                 ║
       ║                                                          ║
       ║             F10-Ok ▄           Cancel ▄                  ║
       ║             ▀▀▀▀▀▀▀▀           ▀▀▀▀▀▀▀▀                  ║
       ╚══════════════════════════════════════════════════════════╝


5)  Delete MAIL.TXT in temporary directory:

       ╔════════════════ Externals Definition ════════════════════╗
       ║ Title        Delete MAIL.TXT                             ║
       ║ Command Line del g:\temp\mail.txt                        ║
       ║ Use 2nd Cmd Processor? Y     Pause after execution? N    ║
       ║ Prompt for Params?     N                                 ║
       ║                                                          ║
       ║             F10-Ok ▄           Cancel ▄                  ║
       ║             ▀▀▀▀▀▀▀▀           ▀▀▀▀▀▀▀▀                  ║
       ╚══════════════════════════════════════════════════════════╝

6)  Force Decrypt Received File:

       ╔════════════════ Externals Definition ════════════════════╗
       ║ Title        Decrypt Received File                       ║
       ║ Command Line \ozcis\ozpke.exe -d -f                      ║
       ║ Use 2nd Cmd Processor? N     Pause after execution? N    ║
       ║ Prompt for Params?     N                                 ║
       ║                                                          ║
       ║             F10-Ok ▄           Cancel ▄                  ║
       ║             ▀▀▀▀▀▀▀▀           ▀▀▀▀▀▀▀▀                  ║
       ╚══════════════════════════════════════════════════════════╝

    If no password to PGP's secret ring has been defined in OZPKE.CFG,
    then change the Externals definition as follows:

       ╔════════════════ Externals Definition ════════════════════╗
       ║ Title        Decrypt Received File                       ║
       ║ Command Line \ozcis\ozpke.exe -d -f -p                   ║
       ║ Use 2nd Cmd Processor? N     Pause after execution? N    ║
       ║ Prompt for Params?     Y                                 ║
       ║                                                          ║
       ║             F10-Ok ▄           Cancel ▄                  ║
       ║             ▀▀▀▀▀▀▀▀           ▀▀▀▀▀▀▀▀                  ║
       ╚══════════════════════════════════════════════════════════╝

Batch file:
-----------

Place the following batch file as named in the Externals Menu, step 4, into
the OzCIS directory, e.g. NEWPUB.BAT:

   @echo off
   rem This batch file adds new Public Key to PGP's PUBRING.PGP file.
   rem Adapt paths as required.
   rem
   c:\pgp\pgp.exe -ka g:\temp\mail.pgp c:\pgp\pubring
   del g:\temp\mail.pgp



Programming Notes:
------------------

OzPKE was developed using Borland Pascal version 7.0 in conjunction with
the excellent Object Professional library from Turbo Power Software. At
the present time, I have chosen not to include the source code to OzPKE in
the distribution file, but will make it available for a small donation.

The idea for the program came from a similar program for TAPCIS users as
developed by Bob Smart [72027,3210], which he called TAPPKE. I also wish
to thank him for additional suggestions and contributions to this
documentation.

Needless to say, this project would have not been necessary without the
tireless efforts of Steve Sneed in first releasing version 2.0 of OzCIS
and continuing to update it. My express thanks to him for this excellent
program.

Of course, without the availability of such outstanding public-key
encryption software, like ViaCrypt PGP, this project would not have even
been conceived.

Please report problems or bugs in OzPKE to the author via Email to his
CompuServe user number 72407,1054. Please include the version number of
the program when it is called without parameters and describe the anomaly
as succinctly as possible.

The author would also welcome suggestions for enhancments to these
programs.


Errors:
-------

When OzPKE detects an error condition, it displays an appropriate message
in a pop-up box. If PGP returns an errorlevel greater than zero, this is
also reported, including a brief error text. When PGP returns errorlevels
1 or 3 during decryption, OzPKE will make one attempt to correct the
defective message block.

If Debug mode is enabled, OzPKE will display additional advisory
information and pause for 2 seconds after each activation of PGP. Turn
this off when you are satisfied that PGP and OzPKE function correctly.

Some users have experienced problems with a previous version in that the
environment buffer was inadequate to accommodate their passwords. This can
be overcome by changing the command line for OzPKE in External Menu to the
following:
    c:\command.com /e:1024 /c ozpke x
Change the location for COMMAND.COM and the necessary environment size as
necessary. This "work-around" should no longer be required with version 1.0c
of OzPKE (or later).


Configuration file:
-------------------

The file OZPKE.CFG must be located in the same directory in which
OZPKE.EXE is located. Lines beginning with semicolon are treated as
comments. Remove the semicolons to activate the command.

;  This is the configuration file for OZPKE and must be in the
; directory where OZPKE is located, usually the OZCIS directory.
; Entries can be either upper or lower case.
;
; PROG is complete path to PGP.EXE or other public key encryptor.
PROG=C:\PGP\PGP.EXE
;
; TEMP points to a temporary working directory, preferably on a RAM disk.
; If not defined here, the environment variables TEMP or TMP will be
; checked for a valid path to a temporary directory. If nothing else is
; defined, temporary files will be stored in PGP's directory.
TEMP=G:\TEMP
;
; OZCIS is the directory where OzCIS' program file and HOST.DB are located.
OZCIS=D:\OZCIS
;
; USER must contain your ID number as stored in SECRING.PGP.
; (This is changed from the user name in previous versions.)
; Example: USER=0x61C7A5
USER=User ID
;
; LIST is complete path to LIST.COM or other file viewer or editor.
LIST=c:\util\list.com
;
; PASS is your password to PGP's secret ring file.
; If not defined, then pass it on command line to OZPKE after "-p".
; Leading/trailing blanks are removed.
;PASS=
;
; PRIV may contain the PGP command string for private message only.
; The default for PGP is internal to program and defaults to:
;PRIV= %i "%a" -u %u -o %o -eat +clearsig=off
;
; where:
;        %i is placeholder for filename of input file to encode
;        %a is placeholder for name or ID number of addressee
;        %u is placeholder for name of user as stored in SECRING.PGP
;        %o is placeholder for filename of output file after encoding
;
;    Quotes around %a are required!
;
; SIGO may contain the PGP command string for signature only.
; The default for PGP is internal to program and defaults to:
;SIGO= %i -u %u -o %o -sat +clearsig=on
;
; SIGP may contain the PGP command string for signature and private.
; The default for PGP is internal to program and defaults to:
;SIGP= %i "%a" -u %u -o %o -seat +clearsig=off
;
; BINSIG contains command string for binary file attachments,
; signature and private.
; The default for PGP is internal to program and defaults to:
;BINSIG= %i "%a" -u %u -o %o -es
;
; BINPRV contains command string for binary file attachments,
; private message only.
; The default for PGP is internal to program and defaults to:
;BINPRV= %i "%a" -u %u -o %o -e
;
; ASCSIG contains command string for ASCII file attachments,
; signature and private.
; The default for PGP is internal to program and defaults to:
;ASCSIG= %i "%a" -u %u -o %o -sea
;
; ASCPRV contains command string for ASCII file attachments,
; private message only.
; The default for PGP is internal to program and defaults to:
;ASCPRV= %i "%a" -u %u -o %o -ea
;
; DEBUG can be set to 0/1 or N/Y to disable or enable additional messages
; and delays for debugging purposes. Default=N
;DEBUG=N
;
; DECODE contains PGP command for decoding messages.
; The default for PGP is internal to program and defaults to:
;DECODE= %i -o %o
;
; FILEDECODE contains PGP command for decoding files to original name.
; The default for PGP is internal to program and defaults to:
;FILEDECODE=%i -p
;
; FORUM can be set to 0/1 or N/Y to disable or enable processing of
; outgoing forum message files. Default=N
;FORUM=N
;
; BAK can be set to 0/1 or N/Y to disable or enable making a backup of forum
; and CIS message files. Default=Y
;BAK=Y
;
; APPEND can be set to 0/1 or N/Y to disable or enable appending of decoded
; messages to the CISMAIL.MSG file. Default=N.
; Due to problem with OzCIS not reloading CISMAIL.MSG after DOS gateway, this
; command does not yet function correctly. An OzCIS version later than 2.0a
; may support this feature.
;APPEND=N
;
; To determine storage for plain-text copies of encoded outgoing messages
; before encryption.
; OUTBOX can be set to:
;    CISMAIL  : stores only Cismail messages to CISMAIL.OBS
;    FORUM    : stores only forum messages to <forum>.OBS
;    BOTH     : stores both Cismail and forum messages
;    NONE     : neither.
; Actual name for <forum>.OBS is stored in FORUMS.DB and for CISMAIL.OBS in
; HOST.DB. For a forum in which "Save Outbox Msgs?" is set to "N", the
; forum setting here will be ignored.
; Settings can be abbreviated to just first letter. Default=None.
;OUTBOX=None
;
; Keep plain-text output file from PGP rather than deleting it, so that
; the message can be inserted into OzCIS' reply editor (^KR) for quoting.
; Default=N
;KEEP=N
;
; Upload outgoing PGP ASCII messages as files instead of normal text messages.
; This should only be needed if ASCII text messages are corrupted when
; transmitted normally. Default=N
;UPLASCII=N
;
; Directory in which to store the ASCII PGP files to be uploaded.
UPLPATH=D:\OZCIS\PGP
;
; Directory in which to store the BINARY PGP files to be uploaded.
BINPATH=D:\OZCIS\PGPBIN
;
; Directory in which to store decoded binary PGP files.
BINDEC=D:\OZCIS\BINDEC
;
; Directory in which to store decoded ASCII PGP files.
ASCDEC=D:\OZCIS\ASCDEC
;
; Overwrite (wipe) temporary plain-text files before deleting them.
; Default=N
;WIPE=N
;
; ---- End of OzPKE.CFG ----


OzPKE History:
--------------
  Date    Version   Comments
01/12/94    1.2     Revised documentation for ViaCrypt-PGP

12/07/93    1.2     Converted OzPKE & OzPKD to units in common program.

                    Reduced memory footprint during DOS gateway.

                    Trap for empty Outbox filename under host options.

                    Make any missing subdirectories

12/02/93    1.1     Removed check for recipient if signature-only.

                    Check for CIS or Internet address match in pubring entry
                    and skip pick list if match found.

                    Accept multi-line addresses in pubring list.

                    Wipe plain-text message files as appropriate and also
                    OZPKE.SWP if used.

                    Handle ASCII or binary encryption of file attachments.

11/18/93    1.0e    Added switch UPLASCII and UPLPATH in OzPKE.CFG for
                    uploading ASCII PGP messages with protocol for cases
                    when ASCII messages garbled in normal method.

10/28/93    1.0d    Improved error trapping for missing OzPKE.CFG

                    Display appropriate error message from PGP in addition
                    to errorlevel.

                    Increase number of free bytes needed in environment

10/16/93    1.0c    Revised handling of user and recipient names: now passes
                    6-digit ID numbers instead of full names to PGP. Long
                    names would cause overflow of command line to PGP.

                    If environment buffer has insufficient space for password
                    and path to PGP, temporary environment is used.

                    Corrected pathname problems to files like CISMAIL.REP.

                    Debug mode now displays command line to PGP.

10/06/93    1.0b    Additional error trapping during initialization.

09/03/93    1.0a    Initial release.

OzPKD History:
--------------
  Date    Version   Comments
12/13/93    1.2     Fixed bug in storing path to PGP in environment.

                    Converted to unit with OzPKE under common program.

                    If PGP returns errorlevel 1 (Invalid File) or 3
                    (Unknown File), try to repair file:
                       1) remove possible leading blanks within PGP block
                       2) discard extraneous text
                       3) call PGP again

                    Make any missing subdirectories

12/01/93    1.1     Wipe plain-text message files as appropriate and also
                    OZPKD.SWP if used.

                    Handle decryption of ASCII or binary files.

10/28/93    1.0b    Increase number of free bytes needed in environment

                    Improve error handling if OzPKE.CFG not found

                    Make certain that MAIL.PGP and MAIL.TXT deleted before
                    exiting back to OzCIS.

                    Add command KEEP in OzPKE.CFG to not delete MAIL.TXT
                    after viewing plain-text output from PGP.

                    Display appropriate error message from PGP in addition
                    to errorlevel.

                    New Macro, ^R, defined to loaded decrypted message into
                    OzCIS reply editor.

10/16/93    1.0a    If environment buffer has insufficient space for password,
                    temporary environment is used.

                    Corrected pathname problems to files like CISMAIL.REP.

                    Debug mode now displays command line to PGP.

09/03/93    1.0     Initial release.



Suggestions from users:
-----------------------

One user is concerned about the decoded message being left on disk in
a recoverable form. He writes:

  "I have worked out a reasonable solution for myself.  I set KEEP=Y so
   that MAIL.TXT is created when I decrypt.  When I decrypt a message,
   though, I run the following batch file instead of OzPKD:

      @echo off
      c:\ozcis2\ozpkd.exe -p %1
      cls
      be ask "Would you like to reply to this note? " ny DEF=n
      if errorlevel 2 goto end
      wipefile c:\pgp\temp\mail.txt /g
      :end

  "After I am done reading a decrypted message, the batch file gives me
   the choice of preserving the plaintext for a reply, or wiping it out
   immediately.  If I choose to retain it, I still must use ^R to invoke
   the reply feature.  However, I also modified the ^R macro to run
   wipefile on MAIL.TXT after it finishes loading it into the OzCIS Reply
   Editor.  I accomplished this by creating a new external to run the
   necessary wipefile command.  My ^R macro simply executes this external
   after it has finished loading MAIL.TXT into the reply editor.  As long
   as I use ^D and ^R consistently, one or the other of the two macros will
   wipe MAIL.TXT from my hard drive."

Note: Starting with this version of OzPKE, replace the second line in his
batch file with the following command:

      c:\ozcis2\ozpke.exe -d -p %1


The same user also thought of a clever way to keep his encrypted outgoing
messages available for review. He writes:

  "OZPKE has an option to APPEND an outgoing message to the CISMAIL.MSG
   file.  As you correctly point out, this doesn't work right now, because
   of the way OZCIS handles its buffers when you shell out to DOS (I ran
   into this problem months ago with Todd Fiske's OZM).  I wanted to point
   out, however, that it may not be necessary to have this feature in
   OZPKE, unless the user wants to save *plaintext* to the CISMAIL.MSG
   file. I set OZCIS to save all outgoing mail to my CISMAIL.MSG file.
   This way, the ciphertext gets saved to the message file.  If I want to
   read messages I sent, I merely decrypt them using ^D.  I can decrypt
   messages I sent, because I include myself as a recipient of every
   message I send.  I managed this by putting my ID on the command line
   for SIGP and PRIV in OZPKE.CFG.  This arrangement gives me greater
   security, because plaintext is never stored on the hard drive."

Note: This trick doesn't work quite as expected if UPLASCII=Y since only
the reference to the uploaded message is written to the message file.

====== End of OzPKE documentation =============================