                                                1 April 2008.  SMS.

                     GnuPG 1.4.9 for VMS (1.4.9b)
                     ============================

------------------------------------------------------------------------

         Disclaimer
         ----------

   No claims of any sort are made herein.  The main GnuPG developers
are probably unaware of this effort.  (Any suggestions for improving the
code in the VMS-specific sections are welcome, but low expectations are
more realistic than high ones.)

------------------------------------------------------------------------

         Description
         -----------

   This note accompanies a quick VMS port of GnuPG version 1.4.9. 
"GnuPG is the GNU project's complete and free implementation of the
OpenPGP standard as defined by RFC2440."  Some of the most obvious
features seem to work (mostly), but many have not been tested.

   Built and tested (slightly) in these environments:

OpenVMS Alpha V7.3-2, HP C V7.3-009

OpenVMS IA64 V8.3-1H1, HP C V7.3-018

OpenVMS VAX V7.3, Compaq C V6.4-005

------------------------------------------------------------------------

         GnuPG Web Resources
         -------------------

   Main Web page:

      http://gnupg.org/

   HTML documentation:

      http://www.gnupg.org/(en)/documentation/index.html

------------------------------------------------------------------------

         Cautions
         --------

   The VMS-specific "entropy gathering" code ([.CIPHER]RNDVMS.C, used to
assist pseudo-random number generation) has not been evaluated for
quality.  Poor quality here could result in low-quality keys. 
Suggestions for improvement are always welcome.

   Files with any RMS record formats are accepted as input by GPG, but,
as with most UNIX-oriented programs, RMS file attributes are not
preserved.  All output files are Stream_LF, so any input files with more 
exotic attributes may be seen as corrupted after they've been processed
by GPG.  If RMS attribute preservation is important, it would be best to
preprocess the input file(s) using Info-ZIP Zip (or VMS BACKUP) before
GPG encryption, and then postprocess using UnZip (or BACKUP, after the
usual save set attribute adjustment) after GPG decryption.

   GPG normally resists overwriting an existing output file, prompting
an interactive user with a question like: "File `name.type' exists.
Overwrite? (y/N)".  "Overwrite" may appear to be safe, because a new
file version will be created instead of actually overwriting the
existing file.  However, if the existing file has non-UNIX-like
attributes ("Record format: Variable length", for example), then the new
file will inherit the attributes of the old file, and the result may be
a corrupt file, because the UNIX-like GPG code writes its output in ways
which do not conform to the original file's record structure. 
Overwriting a Stream_LF file should be harmless.

   Unless "-o" ("--output") is used to specify an output file name, GPG
expects to derive its output file name from its input file name by
adding or removing a file name extension.  For example, on a UNIX
system, encrypting "fred.txt" normally produces "fred.txt.gpg".  On VMS,
this would emerge as "fred^.txt.gpg" on an ODS5 file system, or
"FRED.TXT-GPG" on an ODS2 file system.  Keyring backup files are always 
"XXXring.gpg_bak" instead of "XXXring.gpg~", as they would be on UNIX.
Specifying files with version numbers will almost certainly confuse
these programs.

   The password agent (gnupg-agent) features (as currently coded)
require support for UNIX sockets, which is missing on VMS, so these
features have been disabled (CONFIG.H_VMS: ENABLE_AGENT_SUPPORT).

   OpenPGP Card (smart card) support features have been disabled
(CONFIG.H_VMS: ENABLE_CARD_SUPPORT).

   SHA-384 and SHA-512 digests are not available on VAX (CONFIG.H_VMS:
USE_SHA512).

   The tests (in [.CHECKS]) have not been run, as the automated test
procedure requires a Bourne shell.  The current VMS builder should
create the [.TOOLS] programs, and use them to generate the test data
files (in the architecture-specific [.CHECK.*] directory), but that's
all.  (Perhaps the GNV environment could be used to complete this.)

   Many features have not been tested.

------------------------------------------------------------------------

         Building GnuPG on VMS
         ---------------------

   Extract the files from the distribution kit.  The kit includes
objects and executables for Alpha, IA64, and VAX, in the corresponding
host-specific subdirectories.  These builds were done with optional
large-file support (except VAX), and bzip2 compression support.  LDAP
support is also available on non-VAX systems.  MMS or MMK is required. 
MMS commands are shown in the examples, but MMK should work.  (An
exception is for automatic dependency generation.  See
[.VMS]DESCRIP_MKDEPS.MMS for details.)

   Normally (starting in the [.VMS] subdirectory, basic build):

      MMS /MACRO = (LARGE=1)    ! Non-VAX (with large-file support)
      MMS                       ! VAX

   Instructions for various build options are included in the main
builder file, [.VMS]DESCRIP.MMS.  The optional support for features like
bzip2 compression and cURL support (see "Keyserver Programs", below)
requires software which is not included in this kit.  Large-file support
is available only on non-VAX systems with a sufficiently recent C
run-time library.  LDAP support requires the shareable library,
SYS$SHARE:LDAP$SHR.EXE.

   To avoid a lot of source code changes, the builders compile the code
with the PTRMISMATCH1 warning disabled (where needed).  This should have
stopped all the compiler warnings, but some informational complaints
remain, notably several QUESTCOMPARE[1].


      Keyserver Programs
      ------------------

   GnuPG has options to allow transferrng key data to and from key
servers (--recv-keys, --search-keys, --send-keys).  These options use a
set of external helper programs, which are built as
"[.KEYSERVER.*]GPGKEYS_*.EXE".

   Two of these programs are self-contained, designed to handle a
specific communication scheme: gpgkeys_finger and gpgkeys_ldap.  Two
others are intended to be linked with a cURL object library, if one is
available: gpgkeys_curl and gpgkeys_hkp.  These are always built using a
GnuPG cURL emulation library.  If true cURL support is enabled (by
defining the MMS macro GPG_CURL at build time), then the "real cURL"
versions of these programs will also be built.  Presumably, the real
cURL code allows gpgkeys_curl to support more schemes than the GnuPG
cURL emulation does.  Note that if a cURL object library is specified,
and if it was built with HP SSL support (which uses shareable run-time
libraries), then the MMS macro "GPG_HPSSL" will also need to be defined
at build time for the link to succeed.


      PSWAPM Privilege
      ----------------

   Use of the secure memory feature requires the privilege PSWAPM.  This
means that it will work only for an appropriately privileged user, or if
the GPG executable is linked /NOTRACEBACK (the default) and INSTALLed
with the appropriate privileges.

   A command to install the executable image should look like this:

      INSTALL ADD dev:[dir]GPG.EXE /PRIVILEGED = (PSWAPM)

   Without the PSWAPM privilege, you may expect GPG to emit warnings
like these:

gpg: WARNING: PSWAPM privilege is required for secure memory on VMS.
gpg: WARNING: can't lock memory: insufficient privilege or object protection
 violation
gpg: WARNING: using insecure memory!
gpg: please see http://www.gnupg.org/faq.html for more information


   Note that if the builder process lacks the PSWAPM privilege, then
late in the build, when the builder runs the newly created GPG
executable to generate the test data files, MMS tends to fail with
various complaints (especially noisy on IA64) involving abnormal process
termination.  MMK tends to hang in this situation.  CTRL/C will kill off
the hung MMK run.  With either MMS or MMK, re-running the build
(repeatedly) will get all the test data files built, except for the
final (and generally inconsequential) one, [.CHECKS.*]PREPARED.STAMP.

   Whatever the problem is when PSWAPM is lacking, it seems to have no
obvious effect outside of MMS or MMK; interactive GPG operation seems to
be unaffected.

------------------------------------------------------------------------

         Installation - Foreign Commands
         -------------------------------

   GPG executables are created in architecture-specific subdirectories
in the source tree ("[.G10.*]GPG*.EXE" and
"[.KEYSERVER.*]GPGKEYS_*.EXE", plus "[.VMSLIB.*]DECC_VER.EXE").  It may
be desirable to move or copy all the important executables to some
central (accessible) location.

   Set the symbols for the primary foreign commands:

      GPG :== $ actual_device:[actual.directory]GPG.EXE
      GPGV :== $ actual_device:[actual.directory]GPGV.EXE

   On non-VAX systems, with SET PROCESS /PARSE_STYLE = EXTENDED, GPG 
will preserve the case of the command line.

   On VAX systems (or with SET PROCESS /PARSE_STYLE = TRADITIONAL),
command-line options and arguments with upper-case content must be
quoted to avoid conversion to lower case by the C run-time library.


      Keyserver Programs
      ------------------

   GnuPG has options to allow transferrng key data to and from key
servers (--recv-keys, --search-keys, --send-keys).  These options use
external helper programs, like the ones in the set of programs,
"[.KEYSERVER.*]GPGKEYS_*.EXE".  On VMS, GPG expects to run these
programs (using the C RTL "system()" function) using a command like
"gpgkeys_XXX [option ...]", where "XXX" will be "curl" or some specific
scheme name, like "finger", "hkp", or "ldap".  This means that another
set of DCL foreign command symbols must be defined to enable such
commands to find the proper programs.

   In general, GPG will use "gpgkeys_curl" for all the schemes which do
not have a known, scheme-specific program.  For the FINGER, HKP, and
(optional) LDAP schemes, GPG will use the scheme-specific program,
"gpgkeys_finger", "gpgkeys_hkp", or "gpgkeys_ldap", respectively.  Thus,
multiple "gpgkeys_XXX" symbols may be needed:

      $ gpgkeys_finger :== $ actual_dev:[actual.dir]GPGKEYS_FINGER.EXE

To use the programs built using GnuPG cURL emulation:

      $ gpgkeys_curl :== $ actual_dev:[actual.dir]GPGKEYS_CURL.EXE
      $ gpgkeys_hkp  :== $ actual_dev:[actual.dir]GPGKEYS_HKP.EXE

Or, if they were built, the programs built using the real cURL library:

      $ gpgkeys_curl :== $ actual_dev:[actual.dir]GPGKEYS_CURL_RC.EXE
      $ gpgkeys_hkp  :== $ actual_dev:[actual.dir]GPGKEYS_HKP_RC.EXE

If LDAP support was enabled:

      $ gpgkeys_ldap :== $ actual_dev:[actual.dir]GPGKEYS_LDAP.EXE


   Note that GPG attempts to verify that it can access any special
"gpgkeys_XXX" program before it tries to use it.  If it can't find the
program (that is, on VMS, if the foreign command symbol is not defined,
or if the program file itself can't be found), then it silently (!)
falls back to using "gpgkeys_curl", which will probably fail with some
obscure and uninformative error message.

------------------------------------------------------------------------

         Installation - Configuration Files
         ----------------------------------

      Configuration and Data File Locations:

   System-wide:

      /SYS$MANAGER/gnupg_share/

   Individual user (keyrings, et c.):

      /SYS$LOGIN/gnupg/


   Copy (and, optionally, customize) the [.G10]OPTIONS.SKEL template GPG
options file to the system-wide location:

      CREATE /DIRECTORY SYS$SYSROOT:[SYSMGR.GNUPG_SHARE]
      COPY /PROTECTION = W:RE [.G10]OPTIONS.SKEL -
       SYS$SYSROOT:[SYSMGR.GNUPG_SHARE]

This file will be copied (except for the first three lines) to a user's
/SYS$LOGIN/gnupg/ directory the first time the user runs GPG.

------------------------------------------------------------------------

      News
      ----

   Version 1.4.9b  2008-04-01
   --------------------------

- Added some VMS-specific changes to RMS parameters to improve I/O
  speed.  Now, principal file open operations use a callback function to
  set non-default RMS parameters: file extend quantity (deq) = 16384,
  multi-block count (mbc) = 127, and multi-buffer count (mbf) = 2. 
  Explicitly set RMS_DEFAULT values override these built-in values. 
  ("-vv" shows details at run-time.)

- Added VMS-specific file-locking code for use with the random seed file
  (normally, "/SYS$LOGIN/gnupg/random_seed").  This should stop the
  annoying accumulation of multiple versions of this file.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

   Version 1.4.9a  2008-03-26
   --------------------------

- Update to GnuPG 1.4.9.  No VMS-specific code changes since version
  1.4.8a.  

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

   Version 1.4.8a  2007-12-23
   --------------------------

- Update to GnuPG 1.4.8.

- Improved handling of file name suffixes, to reduce errors like:
     gpg: can't create `fred.txt.gpg': i/o error
  on ODS2 file systems, and (anywhere):
     gpg: fred.txt-gpg: unknown suffix

- Fixed a problem enabling PSWAPM for GPG.EXE installed with that
  privilege.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

   Version 1.4.7a  2007-03-08
   --------------------------

- Update to GnuPG 1.4.7.  No VMS-specific code changes since version
  1.4.6a.  Some changes were needed in the builders and
  [.vms]config.h_vms, to cope with changes in the source files. 
  [.vms]g10defs.h_vms has been removed.  [.vms]libgnuintl.h_vms is now
  copied into both [.intl]libgnuintl.h and [.intl]libintl.h.  Changes to
  "configure" have moved to "config.h_in" ("config.h.in").

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

   Version 1.4.6a  2006-12-06
   --------------------------

- Update to GnuPG 1.4.6.  No VMS-specific code changes since version
  1.4.5a.

- VMS builders should now produce all-upper-case binary files (.EXE,
  .OBJ, .OLB) on ODS5 file systems, matching the results on ODS2 file
  systems.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

   Version 1.4.5a  2006-07-09
   --------------------------

- New.  Probably needs work.

------------------------------------------------------------------------

      Changes to Source Files
      -----------------------

   Files new for VMS:

         [.cipher]

      rndvms.c            VMS-specific "entropy gathering" code.


         [.vms]

      bzlib.h             bzlib.h jacket header file for bzip2 support.

      cert_vms.h          Header file with some otherwise missing items.

      collect_deps.com    Dependency collector for descrip_mkdeps.mms.

      config.h_vms        VMS-specific config.h.

      configmake.h        Dummy configmake.h to satisfy (defective)
                          [.intl]localcharset.c.

      descrip.mms         Main MMK or MMS description ("make") file.

      descrip_config.mms  Generated headers description file.

      descrip_mkdeps.mms  Source dependency generator description file.

      descrip_src.mms     Source list description file.

      descrip_src_flags.mms  Compile and link flags description file.

      find_bzip2_lib.com  bzip2 file location procedure.

      gpg_ldap.opt        LINK options file for the LDAP library.

      gpg_ssl_hp.opt      LINK options file for the HP SSL library.

      gpg_tcpip.opt       LINK options file for the socket library.

      libgnuintl.h_vms    VMS-specific [.intl]libgnuintl.h (and
                          [.intl]libintl.h).

      mman.h              Header file extension for VMS.

      mod_dep.com         Dependency modifier for descrip_mkdeps.mms.

      vms_notes.txt       These notes.


         [.vmslib]

      decc_ver.c          Program to show versions: VMS, C compiler, C
                          run-time library.

      mlock_vms.c         VMS-specific mlock() implementation.

      vms.c               Various VMS-specific code: DEC C run-time
                          initialization, file name adjustment, foreign
                          command symbol checking, terminal echo
                          control, fractional-second sleep.

      vms.h               VMS-specific header file.  Function prototypes
                          for VMS.C.

         [.<various>]

      descrip*.mms        Various MMS description files.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

   Files modified for VMS:

         []

      config.h_in       Added system-dependent file name suffixes for
      (config.h.in)     backup and temporary files, including new
                        VMS-specific ones on VMS.  (Not used on VMS, but
                        needed to allow this kit to work elsewhere.)


         [.cipher]

      rand-internal.h   Added declaration of rndvms_gather_random().

      random.c          Added use of rndvms_gather_random() on VMS. 
                        Added VMS-specific file-locking code for the
                        random seed file.


         [.g10]

      build-packet.c    Disabled a byte-count mismatch error message to
                        accomodate non-UNIX-like VMS/RMS record formats.

      gpgv.c            Added dummy functions on VMS for the new or
                        newly global functions in [.util]ttyio.c.

      iso7816.c         Renamed "readonly" (a keyword for VMS C
                        compilers) to "read_only" to avoid compiler
                        confusion.

      keyring.c         Changed file name suffixes for backup and
                        temporary files on VMS.

      keyserver.c       Avoid the use of a "/" when forming a command to
                        run a gpgkeys_XXX helper program on VMS.

      misc.c            Included <time.h> on VMS.
                        Changed to avoid setrlimit() on VMS.
                        Changed to use a VMS-specific path_access()
                        function on VMS.  (In [.vmslib]vms.c.)

      openfile.c        Adjusted /SYS$LOGIN/gnupg directory protection.
                        Changed to accomodate ODS2-restricted file
                        names.

      passphrase.c      Made some "#include" directives conditional on
                        the related feature.

      plaintext.c       Changed on VMS to use a VMS-specific file open
                        function, fopen_vms(), adding RMS parameter
                        adjustment.  (In [.vmslib]vms.c.)

      signal.c          Changed on VMS to restore the terminal echo
                        setting on an error exit.


         [.include]

      ttyio.h           Added two external function prototypes for VMS. 
                        New: ttyfp_is().  Formerly local: init_ttyfp().


         [.mpi]

      src_alpha.dir     Renamed from "alpha.dir", to avoid conflict with
                        the [.alpha] destination directory used by the
                        VMS builders.


         [.util]

      cert.c            Added '#include "cert_vms.h"' for VMS.

      dotlock.c         Added VMS conditionality to file locking code.

      iobuf.c           Added byte counting code for file size
                        determination.  (Adapted from the HP-supplied
                        code in its GnuPG 1.2.3 kit.)
                        Changed to use a VMS-specific file open
                        function, open_vms(), adding RMS parameter
                        adjustment.  (In [.vmslib]vms.c.)

      logger.c          Changed the initialization of the log file
                        pointer to eliminate overwritten terminal
                        messages.

      pka.c             Added '#include "cert_vms.h"' for VMS.

      secmem.c          Changed the "can't lock memory" error to a
                        warning on VMS.

      srv.c             Added '#include "cert_vms.h"' for VMS.

      ttyio.c           Changed to use VMS-specific terminal echo
                        control on VMS.
                        Made the formerly local init_ttyfp() function
                        global on VMS.
                        Added on VMS a new function, ttyfp_is().

------------------------------------------------------------------------

   The accompanying source kit may suffer from storage on an ODS2 file
system, which does not preserve case, or allow "@" or multiple dots in a
file name.  Building this kit should work on VMS, but it may be expected
to fail on other systems.  To use this kit on a non-VMS system, the
files may need to be renamed to restore their original mixed-case and/or
multi-dot names.  The UNIX shell script "vms_name_fix.sh" (or something
like it) should do the job.

   Developers should note, however, that there is a conflict between the
VMS binary directory [.MPI.ALPHA] and the original Alpha-specific source
directory [.MPI.ALPHA] (which is not used on VMS).  To avoid collisions,
the VMS kit has the original source directory [.MPI.ALPHA] renamed to
[.MPI.SRC_ALPHA], but the "vms_name_fix.sh" script will attempt to "mv
mpi/src_alpha mpi/alpha", and this will work incorrectly if an
"mpi/alpha" directory already exists.  Because the Alpha binaries in the
kit are built with LARGE=1, they should appear in [.ALPHAL], and so this
problem should not arise.  (If the original source [.MPI.ALPHA]
directory were not renamed, various CLEAN operations by the VMS builders
would delete the source files situated there.)

   When reporting problems, especially build problems, with GnuPG for
VMS, it is often useful to reveal precise compiler, run-time library,
and VMS version information.  The program DECC_VER.C (included in the
kit) is intended to make that easier.

------------------------------------------------------------------------

   Steven M. Schweda               sms@antinode.org
   382 South Warwick Street        (+1) 651-699-9818
   Saint Paul  MN  55105-2547

