                                                20 August 2010.  SMS.

                    GnuPG 1.4.10 for VMS (1.4.10b)
                    ==============================

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

         Disclaimer
         ----------

   No claims of any sort are made herein.  The main GnuPG developers may
be 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.10. 
"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 V8.3, 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.

   GPG uses a UNIX-like path, "/SYS$LOGIN/gnupg", to locate files like a
user's keyrings.  This may cause problems when the equivalence name for
SYS$LOGIN is a search list, as it's likely to be, for example, for user
SYSTEM ("SYS$LOGIN" = "SYS$SYSROOT:[SYSMGR]", where "SYS$SYSROOT" is a
search list).  A typical failure might look like this:

gpg: can't create `/SYS$LOGIN/gnupg/pubring.gpg_tmp': no such file or directory
gpg: error writing keyring `/SYS$LOGIN/gnupg/pubring.gpg': file open error

To work around this problem, one can define the logical name GNUPGHOME,
which overrides the default path, "/SYS$LOGIN/gnupg".  Specify some
suitable value which does not involve a search list.  For example:

      define GNUPGHOME "/SYS$COMMON/SYSMGR/gnupg"

Any user may define GNUPGHOME, but only a user for whom SYS$LOGIN
involves a search list should need to do it.

   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 ([.vms]config.h_vms: ENABLE_AGENT_SUPPORT).

   OpenPGP Card (smart card) support features have been disabled
([.vms]config.h_vms: ENABLE_CARD_SUPPORT).

   SHA-384 and SHA-512 digests are not available on VAX ([.vms]
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 full 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, cURL support (see "Keyserver Programs", below), and
IDEA encryption 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 transferring 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_CURL_HP" will also need to be
defined at build time for the link to succeed.  (Similarly, if the cURL
library was built using OpenSSL shareable libraries, then the MMS macro
"GPG_CURL_OE" is required.  See [.vms]descrip.mms for details.)


      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 transferring 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.10b  2010-08-20
   ---------------------------

- Changed various builders ("[...]descrip*.mms") to solve some build
  problems, and to add optional support for the IDEA algorithm.
  Changed the GPG_HPSSL option macro to GPG_CURL_HP, and added
  GPG_CURL_OE.  Now, GPG_CURL_HP should be defined when using a cURL
  library which was built using HP SSL shared images, and GPG_CURL_OE
  should be defined when using a cURL library which was built using
  OpenSSL shared images.  The names of OpenSSL shared images may vary
  with the OpenSSL kit, so some editing of the associated link options
  file, [.vms]gpg_ssl_open.opt, may be needed.  See [.vms]descrip.mms
  for details.

- Explicit "^" characters in file specifications in
  [.checks]descrip_src.mms ("pubring^.pkr.asc", "secring^.skr.asc")
  triggered (spurious) %MMS-E-CDDACCERR (and related) complaints from
  MMS V3.9-00.  They're gone now.

- Since version 1.4.8a, [.vms]config.h_vms had defined HAVE_BZIP2
  unconditionally, instead of letting the builders do it (under user
  control), causing build problems (LINK warnings) if bzip2 support was
  not requested ("%LINK-I-UDFSYM, COMPRESS_FILTER_BZ2", ...).

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

   Version 1.4.10a  2009-12-07
   ---------------------------

- Update to GnuPG 1.4.10.

- Added VMS-specific code for faster file size determination when a
  UNIX-like file format makes the fstat() value accurate. 
  [.vmslib]vms.c:vms_file_size().

- Added jacket header file [.vms]time.h, to add a prototype for
  [.util]timegm.c:timegm().

- Added simple auto-sensing of some version-dependent cURL functions in
  the builders.  (There's still no true "configure" script, however.)

- Kits are now packaged on an ODS5 file system, obviating
  [.vms]vms_name_fix.sh, which is no longer included.  The builders have
  been revised to sense and cope with multi-dot file names on an ODS5
  file system, or the altered file names which will be found on an ODS2
  file system.  The builders should emit a message like the following
  when ODS2-altered filenames are used:
      (Expecting ODS2 under-dot names for multi-dot file names.)

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

   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]

      idea.c              Dummy idea.c.  Used only for automatic
                          dependency generation on VMS.  The user may
                          replace this dummy file with a real idea.c
                          file to get IDEA support.  See
                          [.vms]descrip.mms for details.

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


         [.vms]

      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_cmn_1.mms  Common description file.

      descrip_src_cmn_2.mms  Common 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 shared
                          images.

      gpg_ssl_oe.opt      LINK options file for the OpenSSL shared
                          images.

      gpg_tcpip.opt       LINK options file for the socket library.

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

      mman.h              Jacket header file for VMS.  Adds prototype
                          for [.vmslib]mlock_vms.c:mlock().

      mod_dep.com         Dependency modifier for descrip_mkdeps.mms.

      search.com          MMS-compatible SEARCH procedure.

      stream_lf.fdl       FDL definition file for a Stream_LF file.

      time.h              Jacket header file for VMS.  Adds prototype
                          for [.util]timegm.c:timegm().

      vms_notes.txt       These notes.


         [.vmslib]

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

      dotlock_vms.c       VMS-specific (currently dummy) replacements
                          for the excessively UNIX-or-Windows functions
                          in [.util]dotlock.c.

      mlock_vms.c         VMS-specific mlock() implementation.

      vms.c               Various VMS-specific code: DEC C run-time
                          initialization, file name adjustment, file
                          size determination, 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.)

      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.

      keydb.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.

      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 was constructed on an ODS5 file system,
so multi-dot or other ODS2-invalid file names should be preserved when
extracted onto an ODS5 (or UNIX(-like)) file system.  When extracted onto
an ODS2 file system, these exotic file names should be simplified in the
usual ways by a modern UnZip or VMSTAR program.  The builders should
sense the local situation and act accordingly without user intervention.

   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].  Because the Alpha binaries in the kit are built with
LARGE=1, they should appear in [.ALPHAL], and so this problem should not
arise, but 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.info
   382 South Warwick Street        (+1) 651-699-9818
   Saint Paul  MN  55105-2547

