
	 Using TIS/PEM With The Rand MH Message Handling System

In this directory are a number of files that will assist you in using
TIS/PEM with MH.  The version of MH you use must include support for MIME.
These files were developed with MH Version 6.8.3; your mileage may vary.  If
you have not already done so, you must obtain a copy of the MH 6.8.3
distribution and build and install it according to its instructions.  For
your convenience, you may obtain a copy from the same place you retrieved a
copy of the TIS/PEM distribution.

The files group into 4 categories:

	o changes to MH's mhn.c program
	o script to be executed instead of MH's send
	o scripts to interface mhn to TIS/PEM

Finally, at the end of these instructions is a collection of the suggested
additions to the a user's .mh_profile in order to make use of the glue
provided here.


CHANGES TO MH'S MHN.C PROGRAM

  mhn.c (located in the MH source tree as uip/mhn.c) has been modified to
  support the security multiparts multipart/signed and multipart/encrypted.
  A complete mhn.c is provided in the file mhn.c.  If you have made local
  changes to your mhn.c we have also included a context diff of our changes
  to the Version 6.8.3 mhn.c in the file diff-c-mhn-6.8.3.  For your
  information we have included a copy of the original mhn.c as found in
  Version 6.8.3 of MH.

  Note that security multiparts are independent of the email security
  protocol being used.  Thus, if other protocols besides PEM makes use of
  these content types the enclosed changes to mhn.c will support them.

  To install these changes you will need to do one of two things.

  1. Apply the context diff changes to your locally modified mhn.c.
  Upon successful application of all the changes, rebuild mhn and
  install it.

  or

  2. Replace the mhn.c in your MH distribution with the one included
  here.  Rebuild mhn and install it.


SCRIPT TO BE EXECUTED INSTEAD OF MH'S SEND

  One script has been included: pemsend.sh to replace send.  The correct way
  to use this script is to install it in the same directory as the rest of
  your MH binaries and to instruct individual users to configure their own
  MH environments to use it.  In this way users may continue to type "send"
  as they always have.

  To use the script users must place the following line in their .mh_profile
  file:

	sendproc: pemsend.sh

  When sending messages, the pemsend.sh script will operate in one of three
  different modes:

  1. pass through - it does nothing but execute the real send program

  2. behave according to explicit direction - a user may indicate on the
  command line to protect a message according to MIME multipart/signed or
  MIME multipart/encrypted.  This can be done from the whatnow prompt by
  simply invoking send with the appropriate command line options.

  3. behave according to implicit direction - a user may indicate the
  desired enhancements by placing a directive as the first line of the
  message being submitted.  This feature is most useful for inclusion in
  component template files.

  The pemsend.sh script has additional command line arguments that make
  it suitable for use by the XMH interface included in the distribution.

  The script has extensive comments about its operation included with it.
  Please read them.

  The pemsend.sh script depends on the existence of a special format file:
  mhl.pemheaders.  This file should be installed in your MH etcpath
  directory, probably something like /usr/local/lib/mh.

  The pemsend.sh script depends on two additional programs, the source code
  for which is also included in this directory: headskip and msgsplit.
  These programs will need to be compiled as follows and installed in the
  directory with the rest of the PEM programs:

	cc -o headskip headskip.c
	cc -o msgsplit msgsplit.c

  Some versions of tail on some systems are suitable for replacing the
  functionality of headskip.  However, since not all can do it we include a
  separate program.

  At first glance one might think that msgsplit could be easily replaced by
  some combination of sed and awk.  However, both of these programs assume
  their input streams are text-based and newline terminated.  Not all input
  upon which this program operates has those characteristics.  Therefore,
  this program is required.


SCRIPTS TO INTERFACE MHN TO TIS/PEM

  MH's MIME interface requires users creating MIME messages to place
  directives in message files and then to stream edit the message file with
  the MHN program.  To facilitate the application of PEM services to MIME
  body parts, the following two scripts are included:

	pemsign.sh
	pemencrypt.sh

  Both of these scripts include comments about their operation and use.
  Please read them.  See below for additions to the .mh_profile file.

  In addition, the MIME interface allows users to configure mhn to recognize
  certain body parts and process them with commands specified by the user.
  The following scripts understand the mhn interface and will invoke the
  appropriate TIS/PEM commands to process body parts when directed by mhn:

	pemdecrypt.sh
	pemverify.sh

  Both of these scripts include comments about their operation and use.
  Please read them.  See below for additions to the .mh_profile file.


ADDITIONS TO .mh_profile

  Users will need to make the following additions to their .mh_profile files
  in order to make use of the PEM services:

    mhn-compose-application/key-data: getkeydata
    mhn-compose-application/pem-keys: pemencrypt.sh %s %f %a
    mhn-compose-application/pem-signature: pemsign.sh %s %f %a
    mhn-show-application/key-data: savekeydata
    mhn-show-application/pem-keys: %ppemdecrypt.sh %s %f %a
    mhn-show-application/pem-signature: %ppemverify.sh %s %f %a
    mhn-annotate-application/pem-signature: pemverify.sh %s %f %a
    mhn-annotate-application/pem-keys: pemdecrypt.sh %s %f %a
    automhnproc:mhn
    sendproc: pemsend.sh

  After that, you can use the #sign and #encrypt directives when composing
  MIME messages.  See the mhn man page for more details.
