This is a quick guide to creating a key pair and using MH to send and
receive enhanced messaged.  For more information, see the "TIS/MOSS
User's Guide" and the online man pages.


Key Generation
--------------

While you can verify an unencrypted MOSS message's signature on any
computer with the necessary keys and TIS/MOSS software, you must
create a key pair for yourself before you can send Privacy Enhanced
Mail messages or receive encrypted messages.

The program used to create key pairs, and optionally certificates in
which the public keys are placed, is mosskey.  The calling format is:

mosskey private-key-access <mode> private-key <access-info>
        [subject-name <distinguished-name> serial-number <hex-serial-number>]
        [<tag/value pairs> ...]

Both private-key-access, indicating the method by which the private
key is to be accessed (choice is currently limited to 'file'), and
private-key, providing information necessary to access the private key
(file name) are required.

Both subject-name and serial-number must be included or excluded.  If
they are included, a self-signed certificate is generated.  If they
are excluded, a bare public-key is generated.

Other tag/value pairs are included in the newly created user record.
If you intent to retrieve encrypted messages using this user, you
should include 'alias me'.  If you want to use this user record as
your primary user record for generating signatures, include 'alias
sig-user'.  While multiple user records can contain 'alias me', only
one should be 'alias sig-user'.  Aliases can easily be added after the
fact using a text editor.

You will be prompted for the initial TIS/MOSS password for your
private key.  Your TIS/MOSS password protects your RSA private key and
is an important aspect of TIS/MOSS' security.  We recommend that you
use a password that is different from your login password to enhance
security.

Make sure that you choose a password that you can remember.  IF YOU
FORGET YOUR PASSWORD, YOU WILL NO LONGER BE ABLE TO SIGN MESSAGES AND
YOU WILL BE UNABLE TO DECRYPT ANY CONFIDENTIAL MESSAGES SENT TO YOU
USING YOUR CURRENT RSA KEY PAIR. You will then need to create a new
key pair.  Even after creating the new key pair, you won't be able to
read confidential messages sent using the older RSA key pair.

Enter the password you have chosen.  The password can be composed of
upper and lower case letters, which are considered distinct, numbers,
spaces, and punctuation.  The password can be of arbitrary length.
For security reasons, the password is not displayed when you type it.
This is to prevent someone from looking over your shoulder and seeing
it.  To ensure that you did not make a typographical error, you will
be prompted to enter it again.


Sending and Receiving MOSS messages
----------------------------------

Once you have created a key pair, you can use TIS/MOSS to apply,
verify, and remove MOSS security services.  The following sections
describe how to perform these functions.

Sending mail is accomplished using the Rand MH Message Handling System
(MH).  For more information on MH, see "The Rand MH Message Handling
System: User's Manual" and the on-line 'mh' manual pages (type 'man
mh' at the shell prompt).  You must be running MH version 6.8.3 or
later with the TIS/MOSS-modified mhn program.


Sending a MOSS Message with MH
------------------------------

You can send signed MOSS messages to anyone.  To send confidential
mail, the recipients' key pairs must be in the your database and there
must be an alias mapping on each user record so you can identify it.

The addition of MOSS enhancements is managed by the mhn command.
Before continuing, you should take a quick look at the mhn man page.
It describes how 'mhn' works -- how when composing a message it takes
directives and runs external programs to incorporate the various body
parts into the final message.

In order for mhn to be able to process MOSS directives when you
compose messages, you must add the following lines to the
'.mh_profile' file in your home directory (indent for readability --
do not indent in your .mh_profile):

  mhn-compose-application/moss-signature: mosssign.sh %s %f %a
  mhn-compose-application/moss-keys: mossencrypt.sh %s %f %a
  mhn-compose-application/key-data: getkeydata

Invoke the MH comp command at your UNIX shell prompt.  In our
examples, the shell prompt is '%'.  If an editor has been defined in
your .mh_profile, you will be placed in that editor and you can then
compose the message using regular editor commands. If no editor is
defined, you should just type the message as you would like it to
appear and then type control-D (hold down the control key and press
the letter D) on a line by itself.

Enhancing a message is a two part process.  First, when composing the
message, you embed mhn directives.  One of the simplest is '#sign':

  To: galvin@tis.com
  Cc: feldman@tis.com
  Subject: Some signed text
  --------
  #sign
  Ok Jim, Here's some signed text.  Just the way you like it.  I'd write
  more, but this is just a demo message.

The '#sign' directive indicates that the following body part should be
signed.  By default, the following body part is text/plain.  To cause
the enhancement to be processed, at the 'What now?' prompt, type 'edit
mhn':

  What now? edit mhn

This will cause the message to be processed by mhn.  The resulting
message will be enhanced.  After 'mhn' is finished, you will be
returned to the 'What now?' prompt.  From there you can use 'list',
'send', or any of the other valid 'What now?' commands.  If for some
reason you need to edit your composition after you've run 'edit mhn'
you will need to specify your editor on the 'edit' line otherwise mhn
will be run again.

To send an encrypted message, the command is '#encrypt', followed by a
semicolon and a list of semicolon-separated 'recip=' pairs:

  #encrypt; recip=galvin; recip=feldman

If you do not include yourself as a recipient, you will not be able to
decrypt the encrypted body part(s).

These are the basics.  Once you understand the basics of mhn and the
MOSS directives, you can build more complex structures in your
messages.  Unlike the previous TIS/PEM implementation, the MOSS
integration allows you to add multiple enhancements to a single
message.  The enhancements can be in series over one or more body
parts and/or recursively applied.

One of the more common uses of recursion is the combination of
signature and encryption:

  #encrypt; recip=galvin; recip=feldman
  #sign
  Hi, Jim.  Here's something that I signed and then encrypted
  so that only the two of us can read. 

The '#encrypt' encrypts the following body part, which happens to be a
signed message.  The '#sign' signs the following body part, which
defaults to text/plain since there are no other directives.

Body parts can be enhanced individually or as groups.  Following is an
example of multiple parts enhanced individually:

  #sign
  Jim, sorry to keep bothering you, but no one else responds to my
  mail.  Anyway, following is a signed voice message from me.
  #sign
  #audio/basic [Important words for Jim] /tmp/soundfile.au

This produces a message with a a signed piece of text and a separately
signed audio file.  To sign more than one body part with a single
signature, the body parts must be grouped together, effectively making
them a single body part.  The '#begin' and '#end' directives can be
used for this:

  #sign
  #begin
  Jim, this time I'm signing a compound body part that consists of
  text and another voice message.  Two body parts w/one signature.
  What more could you ask for?
  #audio/basic [More important words for Jim] /tmp/soundfile2.au
  #end

An example of recursion:

  #sign
  #begin
  Jim & Paul, 

  Following are your passwords for logging onto my Mac.  Ok, this is
  just a demo and there are no passwords, but you already knew that
  #encrypt; recip=galvin
  Your password is nopass
  #encrypt; recip=paul
  Your password is passno
  #end

In the above example, the entire message is signed and there are two
additional body parts after the clear text, each encrypted for a
single individual.

In addition to invoking mhn manually using 'edit mhn' at the 'What
now?' prompt, including the following line will in the '.mh_profile'
file in your home directory will cause mhn to be invoked for all
messages that you compose:

  automhnproc: mhn

mhn will be invoked automatically before the 'send' command at the
'What now?' prompt.

If you use the supplied 'mosssend.sh' script as your 'sendproc', it
will take care of processing MIME directives and it will also allow
you to place a single MOSS processing directive at the top of the file,
before the mail headers, indicating that the entire message should be
signed (#sign), encrypted (#encrypt; recip=<recipient>), or signed and
encrypted (#privacy; recip=<recipient>).  This is the only context in
which '#privacy' works.  Anywhere else in the message you must specify
both '#sign' and '#encrypt' to sign and encrypt a body part.


Receiving MOSS Messages with MH
-------------------------------

As long as the necessary public keys are available, you can verify
signatures on signed, unencrypted MOSS messages on any computer
running TIS/MOSS.  You need not have your own key pair for signature
verification.  You can only de-enhance encrypted MOSS messages on
computers on which your key pair is present.  As with sending MOSS
messages, you use the Rand MH Message Handling System to receive and
de-enhance MOSS messages.

The MH mhn command is used to view as well as compose MIME messages
containing MOSS privacy enhancements.  mhn is the only MH command that
was modified in order to provide MOSS support.  All actual MOSS
processing occurs in scripts that are called by mhn.  Before
continuing, you should take a quick look at the mhn man page.  It
describes how mhn works -- how on receipt of a MIME message it
recognizes body parts and runs the appropriate external programs to
display them.

Before mhn can process MOSS enhancements, the following lines must be
added to the '.mh_profile' file in your home directory:

  mhn-show-application/moss-signature: %pmossverify.sh %s %f %a
  mhn-show-application/moss-keys: %pmossdecrypt.sh %s %f %a
  mhn-show-application/key-data: %psavekeydata header-in %f

These directives tell mhn how to process de-enhancements.  Once these
directives are in place, to de-enhance a MOSS message, just 'show' it.
By default, the show command will recognize that it's a MIME message
and run mhn as the 'showproc'.  mhn will display the various body
parts, de-enhancing the MOSS sections.  While show calls mhn
automatically on MIME messages, you can also use mhn directly and add
options to produce different results.

In addition to de-enhancing and displaying a message, the show command
can save a copy of the message after all body parts have been
de-enhanced along with annotations describing how it was de-enhanced
as a new message.  The following lines must be added to the
'.mh_profile' file in your home directory in order to process
annotations:

  mhn-annotate-application/moss-signature: mossverify.sh %s %f
  mhn-annotate-application/mosskeys: mossdecrypt.sh %s %f

