
		       TIS/PEM Version 7.0 Beta
			     October 1994


The complete installation process is described in this document, located
at the top of the TIS/PEM distribution.  The following files may be
found in this directory:

CHANGES --- This file contains release notes.  It describes the new
features in this version and the differences between this version and
the last distributed version.  If you are upgrading an existing
installation of TIS/PEM, you should check this file to see what has
changed.

INSTALL --- This file contains the configuration and installation
instructions, which you are currently reading.

README --- This file contains a description of the TIS/PEM distribution
and of its license agreement, including pointers to more information.

copyright.txt --- This file contains a copy of the copyright notice that
appears in each source file.

license.text --- This file contains the full text of the license
agreement that specifies the conditions under which this software may be
used.

pem --- This directory contains the complete TIS/PEM source
distribution.  The pathname of this directory will be referred to as
PEM-root throughout the remainder of this document.

rsaref --- This directory contains a copy of the latest version of
RSAREF that TIS/PEM in known to interoperate with.  It is provided as a
convenience for those sites who do not already have a version of RSAREF
available locally.  The pathname of this directory will be referred to
as RSAREF-root throughout the remainder of this document.

Listed below are the steps to be completed to configure, compile, and
install TIS/PEM.  If you have any problems or questions, please send
email to "tispem-support@tis.com".

1. Acquire the software.

   If you are reading this you have probably already completed this step and
   the next.  However, just in case, the TIS/PEM software is retrieved
   via anonymous FTP from the host "ftp.tis.com".  You must retrieve the
   file "/pub/PEM/README" and understand it before retrieving the
   software.  Complete instructions are in the /pub/PEM/README file.

2. Uncompress and untar the software.

   Assuming you retrieved a file named "pem-X.tar.Z", where "X" is the
   version of the software you retrieved, create a directory for the
   software distribution and place the file in it.  The following
   commands:

     uncompress pem-X.tar.Z
     tar xpf pem-X.tar

   will create a directory called "pem-X", where "X" is the version
   number of the software you have retrieved.  In this directory will be
   all of the files described above.

3. Configure the software.

   TIS/PEM is completely configured by editing PEM-root/Makefile.com.
   Although there are many options you may configure in this file, there
   is a very small number which you must check before compiling the
   software.  If you look at the top of the file it will tell you
   exactly which options you must check.

   The macro CRYPTOLIBS deserves special mention.  As distributed,
   TIS/PEM is dependent on RSAREF.  You must set CRYPTOLIBS to the
   pathname of an RSAREF library.  If you already have RSAREF, then
   point it at that version.  If not, we have included a version of
   RSAREF in our distribution which you can configure and compile prior
   to configuring TIS/PEM.  See the file RSAREF-root/README for
   instructions on how to build RSAREF.  Note, if you copy rsaref.a to a
   new location you must remember to run ranlib on it.

   You will also find that all of the options in PEM-root/Makefile.com
   are preceded by a comment describing their use and various settings.
   Please read each comment to determine if the option value must be
   reset for your environment.

   Finally, TIS/PEM has execution time defaults pre-defined in the file
   PEM-root/h/init.h.  Although all of the values in the file can easily
   be changed by any user at run-time, you may wish to check the
   defaults to see if they are appropriate for your environment.

4. Build the software.

   Prior to building TIS/PEM you must have built RSAREF.  If you have
   not already done so, see the file RSAREF-root/README for instructions
   on how to build RSAREF.  Be sure to set CRYPTOLIBS in
   PEM-root/Makefile.com to the location of the RSAREF library.  Note,
   if you copy rsaref.a to a new location you must remember to run
   ranlib on it.

   To build TIS/PEM proceed to the PEM-root directory and type "make".
   There should be no problems during the compilation, including warning
   messages.  If you have any unusual messages contact
   "tispem-support@tis.com" for assistance.

   TIS/PEM uses lex and yacc to parse messages.  On some platforms, the
   look-ahead buffer in the lex-generated file, lex.yy.c, in the
   directory pem-7.0/pem/lib/parse may be too small and cause the
   verify and decrypt programs to fail.  The constant YYLMAX should be
   defined to be 400 or greater, with BUFSIZ being a reasonable value.
   If, after building TIS/PEM you notice that the value is under 400,
   change it and rebuild.

5. Install the software.

   To install TIS/PEM proceed to the PEM-root directory and type "make
   inst-all".  There should be no problems during the installation,
   including warning messages.  If you have any unusual messages contact
   "tispem-support@tis.com" for assistance.

6. Use the software.

   You now have basic TIS/PEM functionality but sending and receiving
   messages will still be beyond your grasp until you read the user manual.
   Print the user manual located in the directory PEM-root/doc/user.  While
   in that directory use the command "make print-1up".  See the Makefile for
   other options.

   If you have had TIS/PEM before you should already have a registration
   (certificate and private key).  Use your old cai program to export your
   registration.  Use the new pemdbconv program to convert the exported
   registration to your new database.  Each user with a registration will
   need to do this in order to convert private keys to the new database.
   The pemdbconv program can also be used to export all other certificates
   from your previous database and make them available in a shared database
   file for all users.  This may be done by any user.
   
   Alternatively, the pemkey program can be used to generate a new
   public/private key pair, which may be embodied in a certificate or not,
   as specified by command line options; the default is no certificate.
   
   To send and receive enhanced mail, TIS/PEM must be integrated with a mail
   user agent.  The relevant TIS/PEM programs are sign, encrypt, decrypt,
   and verify.  Included in the distribution is the "glue" necessary to
   allow the Rand MH Message Handler Version 6.8.3 to use the TIS/PEM
   programs.  The glue, in the form of /bin/sh scripts, is located in the
   directory pem/interfaces/mh.  See the file pem/interfaces/mh/README for
   complete instructions on installing and using the glue.
   
   If you do not use MH or prefer an alternative user agent, the glue
   included for MH demonstrates how to integrate TIS/PEM with other user
   agents and other applications.  In the future, we expect to add to our
   collection of glue to make TIS/PEM easy to use for everyone.  If you
   would like to make a contribution to the collection please contact
   "tispem-support@tis.com".

7. Join the tispem-users email distribution list.

   TIS uses the tispem-users list to announce patches and new
   distributions of TIS/PEM.  We recommend that everyone who retrieves
   the software subscribe to this list so that you can stay abreast of
   the latest TIS/PEM developments.  It is a very low traffic volume
   mailing list.  To subscribe to the list send a message to
   "tispem-users-request@tis.com".
