****    DES3_README.TXT    ****

This directory contains a simple DES encryption/decryption 
program that uses CDSA, and participates in bilateral 
authentication.  It links implictly against
CDSA$INCSSM300_SHR.EXE using the Application Adaption Layer.

This example is designed to be signed using the CDSA signing tools.

********************
**  Special Note  **
********************

Sys$common:[syshlp.examples.cdsa]readme.txt contains general
information that applies to all of the example programs that are signed.

The necessary files to build the example on OpenVMS are included, 
with the exception of appselfkey.h.  This include file must be 
generated from the certificate created for the application(s).

See the OpenVMS book "Open Source Security for OpenVMS, Volume 1: Common Data
Security Architecture", CDSA Programing Concepts, for complete instructions.
Special attention should be paid to the section on Signed Application Development.

A signed CDSA application will not execute until the proper credentials are
 generated.

**********

The DES3 example files are:

AALPROXY.C            AALDEFS.H               DES3_BUILD.COM
AALPROXYAPI.C         AALPROXY.H              DES3.OPT
AALPROXYINTERNAL.C    AALPROXYDEFS.H          DES3_INS.OPT
CALLOUTS.C            AALPROXYINTERNAL.H      DES3_SIGN.COM
DES3.C                AALPROXYTAB.H           DES3_INSTALL.COM
DO_DES3.C             CALLOUTS.H
                      PRECOMP.H
                      DESGUID.H
                      (APPSELFKEY.H not provided, user generated)

After performing the steps to generate the application credentials
and the include file appselfkey.h, the DES3 example program can be 
built by copying the example files into a local build area, 
and executing the BUILD_DES command file, as follows:

        $ define/trans=conceal cdsa_tempdir <userdisk>:[<userdir>.]
        $ set default cdsa_tempdir:[des3]
        $ copy SYS$SYSROOT:[SYSHLP.EXAMPLES.CDSA.DES3]*.* []
        $ copy cdsa_sysdir:[sign]appselfkey.h []
	$ @DES3_BUILD



The resulting image must be 'signed'.
       **************
On the SIGNING SYSTEM run the command procedure to generate the manifest.
       **************

       $ @DES3_sign

Finally back on the development system run the command procedure
to install the module.

       $ @DES3_INSTALL

The resulting DES3.EXE file can be run as a foreign command.  This can be set up
via:

	$ DES3 :== $<local_build_area>DES3.EXE

The program can then be executed with the following options:

	-e	: encrypt with supplied key (requires -k switch)
	-d	: decrypt with supplied key (requires -k switch)
	-h	: specifies that the supplied key is a 16 character
                  hexadecimal number
	-k key	: use key "key" (apostrophes {aka, single quotes} are necessary if used with -h)

To encrypt MYFILE.TXT using an ascii key with the DES example program, you
would issue the following command:

	$ des3 -e -k "xyzzy" MYFILE.TXT MYFILE.DES

To decrypt the same file, you would issue this command:

	$ des3 -d -k "xyzzy" MYFILE.DES MYFILE.TXT

To encrypt/decrypt using a hexadecimal key, use a key length of exactly 16
typed characters (8 hex bytes), and the -h switch as follows:

	$ des3 -e -k '012abcde012abcde' -h MYFILE.TXT MYFILE.DES
	$ des3 -d -k '012abcde012abcde' -h MYFILE.DES MYFILE.TXT