#####################################################################
#   GNUPG_README_VMS.TXT (How to use GnuPG V1.4.7 on OpenVMS) 	    #
#    Date: November 5, 2007   			             	    #
#####################################################################


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 I64)

   - OpenVMS Alpha Version 7.2-2 or higher
 	+ Compaq/DEC C Version 6.0 or higher

   -or-

   - OpenVMS for Integrity servers (I64) Version 8.2 or higher
	+ HP C Version 7.1


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

   It is recommended that you extract to SYS$COMMON,

   $ set default SYS$COMMON:[000000]

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

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


2. Using GnuPG on OpenVMS

 2.1. Defining symbols and install the GnuPG image

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

	For Itanium: GPG_IA64.EXE & GPGV_IA64.EXE
	For Alpha: GPG_ALPHA.EXE & GPGV_ALPHA.EXE

    Alpha examples:

	If GnuPG-1_4_7 is in SYS$COMMON:[GNUPG],
	$ gpg == "$SYS$COMMON:[GNUPG.GNUPG-1_4_7.G10]GPG_ALPHA.EXE"
	$ gpgv == "$SYS$COMMON:[GNUPG.GNUPG-1_4_7.G10]GPGV_ALPHA.EXE"

    To use GnuPG's secure memory feature, either the PSWAPM privilege must
    be set for the user process or the gpg image must be installed with 
    the PSWAPM privilege (installing the gpg image with PSWAPM privilege 
    will allow users without the PSWAPM privilege to use the secure memory
    feature).

    To install the gpg image with the PSWAPM privilege (on ALPHA):

     $ install create -
       /privileged=PSWAPM SYS$COMMON:[GNUPG.GNUPG-1_4_7.G10]GPG_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, please refer to the
    online documentation located at url http://www.gnupg.org/docs.html.

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

     1. To use the GnuPG's secure memory functionality on OpenVMS, the
        PSWAPM privilege is necessary.  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!
	----------------------------------------------------------------------

	In order to eliminate these warning messages, the gpg user process must 
        have the PSWAPM privilege, or the gpg image must be installed 
        with privilege.

	   To assign the PSWAPM privilege to the user process:

	    $ set process/privilege=PSWAPM
	
	   To install the gpg image with the PSWAPM privilege (on ALPHA):

     $ install create -
       /privileged=PSWAPM SYS$COMMON:[GNUPG.GNUPG-1_4_7.G10]GPG_ALPHA.EXE

     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], specify the home directory
          as in the following commandline:
	  
	  $ gpg --homedir /DKA0/ALICE/GNUPG --list-key

     3. Setting 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 V1.4.7 for OpenVMS can encrypt and sign an input file 
        of any file format.

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


A. [OPTIONAL] Build GnuPG for OpenVMS

   The GnuPG images (GPG_ALPHA.EXE & GPGV_ALPHA.EXE for Alpha,
   GPG_IA64.EXE & GPGV_IA64.EXE for Itanium) 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 on your ALPHA system, copy it from the [GNUPG.VMS]
   directory to SYS$LIBRARY. On OpenVMS IA64 V8.2, the LDAP shareable
   image is available in 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_4_7.VMS])
   	- @BUILD_GNUPG.COM

   New images will be created in [.GNUPG-1_4_7.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.