#########################################################################
#       GNUPG_README_VMS.TXT (How to use GnuPG V1.2.3 on OpenVMS) 	#
#       Date:  September 20, 2003                               	#
#########################################################################


Disclaimer: "GnuPG for OpenVMS" is a port of the GnuPG Open Source
Project to OpenVMS. This program is free software; you can
redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation; either
version 2 of the License, or any later version. 

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details. 

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA. or http://www.opensource.org/licenses/gpl-license.php 
---------------------------------------------------------------------

Requirements (for GnuPG on OpenVMS Alpha and VAX)

   - OpenVMS Alpha version 7.2-2 or higher
	or
     OpenVMS VAX version 7.3 or higher

   - Compaq/DEC C version 6.0 or higher


1. Extract the GnuPG directories and files from the backup saveset,
   GNUPG-1_2_3.BCK. 

   It is recommended that you extract to SYS$COMMON,

   $ set default SYS$COMMON:[000000]

   $ backup GNUPG-1_2_3.BCK/save [...]

   This command will create the GnuPG directory tree in SYS$COMMON:[GnuPG...].
   (This file, README_VMS.TXT, resides in the [.GNUPG] directory)


2. Use GnuPG on OpenVMS

 2.1. Define symbols

    To use GnuPG commands on OpenVMS, GPG & GPGV symbols must be
    defined.	
   
    The executable images are included in the G10 directory.

	For Alpha: GPG_ALPHA.EXE & GPGV_ALPHA.EXE
	For VAX: GPG_VAX.EXE & GPGV_VAX.EXE

    Alpha examples:

	If GnuPG-1_2_3 is in SYS$COMMON:[GNUPG],

	$ gpg == "$SYS$COMMON:[GNUPG.GNUPG-1_2_3.G10]GPG_ALPHA.EXE"
	$ gpgv == "$SYS$COMMON:[GNUPG.GNUPG-1_2_3.G10]GPGV_ALPHA.EXE"

 2.2. GnuPG commands

    Once the gpg and gpgv symbols are defined-- you are ready to use GnuPG
    on OpenVMS.

    Display help menu:

	$ gpg -h
	$ gpgv -h

    Basic commands:

	Generate a new keypair

	$ gpg --gen-key

	List keys on a public keyring

	$ gpg --list-keys

	Export a public key:

	>> into a binary format

	     $ gpg --output alice.gpg --export alice@gnupg.org

	>> into an ASCII-armored format

	     $ gpg --output alice.asc --armor --export alice@gnupg.org

	Import a public key into the public keyring

	$ gpg --import bob@gnupg.org
	
	   Validating the imported key

	   $ gpg --edit-key bob@gnupg.org
	   Command> fpr
	   Command> sign
	   Command> check

	!! Read the "Important" section below before trying 
	   the following commands

	Encrypt a file

	$ gpg --output doc.gpg --recipient bob@gnupg.org --encrypt doc.txt

	Decrypt the encrypted file

	$ gpg --output doc.txt --decrypt doc.gpg

	Sign a file

	$ gpg --output doc.sig --sign doc.txt

	Verify the signed file

	$ gpg --verify doc.sig

	Verify & extract the signed file

	$ gpg --output doc.txt --decrypt doc.sig

	Clearsign a file (wrap a file with an ASCII-armored signature)

	$ gpg --clearsign doc.txt

    For more GnuPG commands and details about GnuPG,
    refer to the online documentation (http://www.gnupg.org/docs.html).

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!! IMPORTANT !!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

     1. To use the GnuPG's secure memory functionality on OpenVMS, the
        gpg process needs PSWAPM privilege.  If the process doesn't have
        the privilege, the gpg command issues the following warnings (then,
        the command will be executed). 
	-----------------------------------------------------------------------
	gpg: WARNING: PSWAPM privilege is necessary for secure memory on OpenVMS
	gpg: WARNING: using insecure memory!
	-----------------------------------------------------------------------

     2. UNIX style specification should be used with the "--homedir" option.

	< Example >

	  If the home directory (storing pubring.pgp, secring.gpg, 
          trustdb.gpg, etc.) is DKA0:[ALICE.GNUPG], run the following.
	  
	  $ gpg --homedir /DKA0/ALICE/GNUPG --list-key

     3. Set up permission (file protection) of the home directory. Remove
	GROUP (G) and WORLD (W) access to the directory.  Otherwise, 
	the gpg command issues a warning:
	----------------------------------------------------------------------
	gpg: WARNING: unsafe permissions on homedir "/dka0/alice/gnupg"
	----------------------------------------------------------------------

	< Example >

	To remove GROUP and WORLD access:

	   $ set security /protection=(g,w) DKA0:[ALICE]GNUPG.DIR

     4. GnuPG version 1.2.3 for OpenVMS can encrypt and sign an input
        file in any file format. 

	<Note>
	After the files have been processed by GnuPG version 1.2.3 for OpenVMS,
	they will then be in the Stream LF format.


A. [OPTION] Build GnuPG for OpenVMS

   The GnuPG images (GPG_ALPHA.EXE & GPGV_ALPHA.EXE for Alpha and
   GPG_VAX.EXE & GPGV_VAX.EXE for VAX) are included in this kit.

   To execute/build the GPGKEYS_LDAP tool in [.KEYSERVER], the LDAP shareable 
   image (LDAP$SHR.EXE) is required in SYS$LIBRARY.  If it doesn't exist,
   copy it from the [GNUPG.VMS] directory to SYS$LIBRARY.

   If you wish to build new GnuPG images on your system, follow the 
   instructions below:

   	- Move to the "VMS" directory ($ set default [.GNUPG-1_2_3.VMS])
   	- @BUILD_GNUPG.COM

   New images will be created in [.GNUPG-1_2_3.G10] after completing this
   build command procedure.

   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! compilation issues
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

   1. If a compiler warning "%CC-W-PTRMISMATCH" appears during building GnuPG,
      replace "/warn=(disable=PTRMISMATCH1)" with "/warn=(disable=PTRMISMATCH)"
      in BUILD_GNUPG.COM.

   2. "%CC-I-XXXXX" messages are informational, not a warning or an error.