HP SSL Version 1.4 for OpenVMS
Installation Guide and Release Notes

March 2010

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

This document contains hardware and software prerequisites, 
installation instructions, postinstallation tasks,
instructions for building your application, the HP SSL directory 
structure, and release notes for HP SSL Version 1.4 for OpenVMS. 

For the latest information about HP SSL, see the HP SSL for OpenVMS
web site at 

  http://h71000.www7.hp.com/openvms/products/ssl/ssl.html

The information in this file applies to HP SSL running on 
OpenVMS Integrity server and OpenVMS Alpha. 


HP SSL Version 1.4 for OpenVMS is based on OpenSSL 0.9.8h and 
includes the following latest security updates, known to date, from OpenSSL.org. 

Vulnerabilities CVE/CAN:

CVE-2008-5077 
CVE-2009-0590 
CVE-2009-0591 
CVE-2009-0789
CVE-2009-3245
 
-------------------------------------------------------------------
   

Installation Requirements and Prerequisites
-------------------------------------------------------------------
   
The following sections list hardware and disk space requirements, and 
software prerequisites.
   
   Hardware Prerequisites - Disk Space Requirements

The HP SSL for OpenVMS kit requires approximately 45,000 blocks of 
working disk space to install. Once installed, the software occupies 
approximately 40,000 blocks of disk space. 

   Software Prerequisites

HP SSL for OpenVMS requires the following software.

-  Operating System

HP OpenVMS Alpha Version 8.2 or higher, or
HP OpenVMS Integrity server Version 8.2-1 or higher

-  TCP/IP Transport

HP TCP/IP Services for OpenVMS Version 5.6 or higher (for HP SSL on 
OpenVMS Integrity server and OpenVMS Alpha Version 8.2 or higher), or

HP SSL for OpenVMS has been tested and verified using HP TCP/IP 
Services for OpenVMS. On OpenVMS Alpha, there are no known problems 
running HP SSL for OpenVMS with other TCP/IP network products, 
including TCPware and MultiNet from Process Software Corporation. 
However, HP has not formally tested and verified these other products. 
 

-   Account Quotas and System Parameters

There are no specific requirements for account quotas and system 
parameters for installing or using HP SSL for OpenVMS.


New Features in HP SSL Version 1.4 for OpenVMS
-------------------------------------------------------------------

The new features in HP SSL Version 1.4 include: 

- Partial backport from 0.9.9-dev

Introduced bn_mul_mont (dedicated Montgomery multiplication
procedure) as a candidate for BIGNUM assembler implementation.
While 0.9.9-dev uses assembler for various architectures, only
x86_64 is available by default in the 0.9.8 branch, and
32-bit x86 is available through a compile-time setting.

- TLS session ticket callback

This allows an application to set the TLS ticket cipher and HMAC keys
instead of relying on hardcoded fixed values. This is useful for key 
rollover, for example, where several key sets may exist with different
names.

- Backport of CMS code to OpenSSL 0.9.8

This differs from the 0.9.9 implementation in the following ways:

+ Lack of EVP_PKEY_ASN1_METHOD indicates that the algorithm parameters 
must be hard coded.

+ Lack of BER streaming support indicates that one pass streaming processing 
is supported only if data is detached; setting the streaming flag is
ignored for embedded content.

Note: CMS support is disabled by default and must be explicitly enabled
with the enable-cms configuration option.

- Updated GMP engine glue

This has been updated to perform direct copies between BIGNUM 
and mpz_t when openssl and GMP use the same limb size. Otherwise, the
existing "conversion via a text string export" trick is still used.

    
- AES_wrap_key()and AES_unwrap_key() functions

These functions have been added to implement RFC3394-compatible AES 
key wrapping.
     

- RFC4507 support to OpenSSL

This includes corrections in RFC4507bis. The encrypted ticket format 
is an encrypted encoded SSL_SESSION structure. Therefore, the new session 
features are automatically supported.

If a client application caches session in an SSL_SESSION structure,
the support is transparent because tickets are stored in the encoded
SSL_SESSION.
     
The SSL_CTX structure automatically generates keys for ticket
protection in servers, thereby  making it possible to provide support 
with no application modification.

If a client or server wishes to disable RFC4507 support, the option
SSL_OP_NO_TICKET can be set.

Note: Add a TLS extension debugging callback to allow the contents of 
any client or server extensions to be examined.

- Added the Korean symmetric 128-bit cipher SEED (see
http://www.kisa.or.kr/kisa/seed/jsp/seed_eng.jsp) and
SEED ciphersuites from RFC 4162:

TLS_RSA_WITH_SEED_CBC_SHA      =  "SEED-SHA"
TLS_DHE_DSS_WITH_SEED_CBC_SHA  =  "DHE-DSS-SEED-SHA"
TLS_DHE_RSA_WITH_SEED_CBC_SHA  =  "DHE-RSA-SEED-SHA"
TLS_DH_anon_WITH_SEED_CBC_SHA  =  "ADH-SEED-SHA"

To minimize changes between patchlevels in the OpenSSL 0.9.8
series, SEED remains excluded from compilation unless OpenSSL
is configured with 'enable-seed'.


- In the SSL/TLS server implementation, session ID context matching is  
done(this is required if an application uses a single
external cache for different purposes).  Earlier,
out-of-context reuse was forbidden only if SSL_VERIFY_PEER was
set.This ensured strict client verification. However, with applications 
using a single external cache for different requirements, clients could 
circumvent ciphersuite  restrictions for a given  session ID context by 
starting a session in a different context.
     
- Added a new function PKCS7_set0_type_other() which initializes a PKCS7 
structure of type "other".

- Added support to create self-signed certificates with 'openssl ca'
such that the self-signed certificate becomes part of the
CA database and uses the same mechanisms for serial number generation
as all other certificate signing.  The new flag '-selfsign' enables
this functionality. 
  
- Provided IPv6 support for certificate extensions. The various extensions,
which use the IP:a.b.c.d, can now take IPv6 addresses using the
formats of RFC1884 2.2. Now the IPv6 addresses are also displayed
correctly.
    
- Added ECDSA in new directory crypto/ecdsa/.

- Included some named elliptic curves, and added OIDs from X9.62,
SECG, and WAP/WTLS.  Each curve can be obtained from the new
function EC_GROUP_new_by_curve_name(),
and the list of available named curves can be obtained with
EC_get_builtin_curves().
Also added a 'curve_name' member to EC_GROUP objects, which can be
accessed via EC_GROUP_set_curve_name()and EC_GROUP_get_curve_name()

- The new fixed-window mod_exp implementation is now the default for
RSA, DSA, and DH private-key operations so that the sequence of
squares, multiplies and the memory access patterns are    
independent of the particular secret key.  This mitigates
cache-timing and any related attacks.

- Added support for proxy certificates according to RFC 3820.  

    
Problems fixed in OpenSSL 0.9.8h 
-------------------------------------------------------------------

The following problems were fixed in OpenSSL 0.9.8h: 

- Fixed a flaw that allowed remote attackers to cause a denial of service
via a TLS handshake that omits the Server Key Exchange message, as found
using the Codenomicon TLS test suite.

- Fixed double free in TLS server name extensions, which could lead to
a remote crash, as found by the Codenomicon TLS test suite. 

- Cleared the error queue in SSL_CTX_use_certificate_chain_file() to
ensure that the error entries from older function calls do not interfere     
with the correct operation.
     
- Fixed ASN.1 parsing of malformed ASN.1 structures that could result
in a denial of service. 

- Fixed buffer overflow in the SSL_get_shared_ciphers() function. 
     
- Fixed the SSL client code, which could crash if connected to a
malicious SSLv2 server.  



   New Features in HP SSL Version 1.3 for OpenVMS
-------------------------------------------------------------------

HP SSL Version 1.3 for OpenVMS, based on OpenSSL 0.9.7e, is included 
in OpenVMS Version 8.3. (The previous version of HP SSL was based on 
OpenSSL 0.9.7d.) 
New features in HP SSL Version 1.3 include:

- HP SSL Version 1.3 is now included in the OpenVMS operating system 
as a SIP (system integrated product) . SSL for OpenVMS is installed 
automatically when you install or upgrade to OpenVMS Version 8.3.

- Bug Fixes in OpenSSL 0.9.7e

+ Fixed race condition when CRLs are checked in a multithreaded 
environment.

+ Added Delta CRL to extension code.

+ Fixed s3_pkt.c so alerts are sent properly.

+ Reduced chances of duplicate issuer name and serial numbers (in 
violation of RFC3280) using the OpenSSL certificate creation 
utilities.

+ Removed potential SSL Protocol 2.0 rollback.

+ The functionality of SSL_OP_MSIE_SSLV2_RSA_PADDING (part of 
SSL_OP_ALL) has been removed from 0.9.7e.  This option can be used to 
disable the countermeasure against man-in-the-middle protocol-version 
rollback in the SSL Protocol 2.0 server implementation. See 
http://www.openssl.org/news/secadv_20051011.txt for more information.

   OpenSSL Documentation from The Open Group
-------------------------------------------------------------------

Documentation about the OpenSSL project and The Open Group is 
available at the following URL:

http://www.openssl.org

The OpenSSL documentation was written for UNIX users. When reading 
UNIX-style OpenSSL documentation, note the following differences 
between UNIX and OpenVMS: 

- File specification format

The OpenSSL documentation shows example file specifications in UNIX 
format. For example, the UNIX file specification 
/dka100/foo/bar/file.dat is equivalent to DKA100:[FOO.BAR]FILE.DAT on 
OpenVMS. 

- Directory format 

Directories (pathnames) that begin with a period (.) on UNIX begin 
with an underscore (_) on OpenVMS. In addition, on UNIX, the tilde (~) 
is an abbreviation for SYS$LOGIN. For example, the UNIX pathname 
~/.openssl/profile/prefs.js is equivalent to the OpenVMS directory 
[._OPENSSL.PROFILE]PREFS.JS. 

   Installing HP SSL for OpenVMS Automatically During OpenVMS 
   Installation or Upgrade
-------------------------------------------------------------------

HP SSL Version 1.3 is  included in the OpenVMS operating system as a 
SIP (system integrated product).  Previous versions of HP SSL were 
included in previous versions of OpenVMS as a layered product.

SSL for OpenVMS is now installed automatically  when you install or 
upgrade to OpenVMS Version 8.3, and previous installed versions of HP 
SSL are automatically removed.  You no longer need to install the PCSI 
file separately. 

When the OpenVMS installation or upgrade procedure is complete, you 
must define the HP SSL foreign commands and (optionally) run the 
Certificate Tool before you use HP SSL.  See Section 1.5 for more 
information.

   Downloading and Installing HP SSL for OpenVMS from Web Site
-------------------------------------------------------------------

You can install HP SSL Version 1.3 on versions of OpenVMS earlier than 
8.3.  A PCSI kit of HP SSL for OpenVMS is available for download from 
the HP SSL web site at 

http://h71000.www7.hp.com/openvms/products/ssl/


   Before Installing HP SSL for OpenVMS
-------------------------------------------------------------------
Beginning in HP SSL Version 1.3, the installation procedure 
automatically removes  the previous version of HP SSL before 
installing the new version.  For example, if you have Version 1.2  
installed, it is removed during the installation procedure and the 
product removal is displayed in the installation log. 

The HP SSL Version 1.3 installation procedure also automatically 
removes any old SSL kits that have a kit name beginning with DEC or 
CPQ.  This removal is done silently during the preconfigure phase and 
is not shown in the installation log.  For example, if you have SSL 
Version 1.1-B (kit name CPQ) installed, it is silently removed when 
you install SSL Version 1.3.  

Do not use the PRODUCT REMOVE command to manually remove HP SSL 
Version 1.2 or higher. If you attempt to use PRODUCT REMOVE on these 
versions of HP SSL, you will receive a PCSI error that recommends 
terminating the operation.  If you ignore the warning and continue to 
remove HP SSL, HP strongly recommends that you use PRODUCT INSTALL to 
install the HP SSL Version 1.3 PCSI kit as soon as possible.  Other 
components in OpenVMS require that HP SSL is installed.

Before you begin the installation of HP SSL, perform the following 
steps:

Preserve the SSL configuration files OPENSSL-VMS.CNF and OPENSSL.CNF 
(if you modified them) by copying them to another disk and directory 
before installing HP SSL.

Shut down HP SSL on each node in the cluster before installing HP SSL 
on a common system disk in a cluster.

   Installation Procedure

Install the HP SSL for OpenVMS kit by entering the following command: 

$ PRODUCT INSTALL SSL

Beginning in HP SSL Version 1.3 for OpenVMS, HP SSL is always 
installed into SYS$SYSDEVICE:[VMS$COMMON].  The /DESTINATION qualifier 
is no longer supported.
For a description of the features you can request with the PRODUCT 
INSTALL command when starting an installation, such as running the 
IVP, purging files, and configuring the installation, refer to the 
POLYCENTER Software Installation Utility User's Guide. 

As the deinstallation and installation procedures progress, the system 
displays information similar to the following output. 

Specifying the /HELP  qualifier on the PRODUCT INSTALL command line 
displays additional information about HP SSL.


$ PRODUCT INSTALL SSL/SOURCE=CEDAR$DKA100:[KITS] /HELP

performing product kit validation...

%PCSI-I-VALPASSED, validation of CEDAR$DKA100:[KITS]HP-AXPVMS-SSL-T0104-0310-1.P
CSI$COMPRESSED;1 succeeded


The following product has been selected:
    
    HP AXPVMS SSL V1.4-310                 Layered Product

Do you want to continue? [YES]

Configuration phase starting ...


You will be asked to choose options, if any, for each selected product 
and for any products that may be installed to satisfy software dependency 
requirements.

HP AXPVMS SSL V1.4-310: SSL for OpenVMS Alpha Version 1.4 (Based on OpenSSL 
0.9.8h)

SSL for OpenVMS provides a toolkit that implements SSL V2/V3, TLS 
V1 and a general purpose cryptography library.

© Copyright 2009 Hewlett-Packard Development Company, L.P.

This software is installable on OpenVMS processors using the 
POLYCENTER Software Installation utility.

IMPORTANT LEGAL NOTICE:

Exports of this product are subject to U.S. Export 
Administration Regulations pertaining to encryption items 
and may require that individual export authorization be obtained from the U.S.
Department of Commerce.

Do you want the defaults for all options? [YES]

Do you want to review the options? [NO]

Execution phase starting ...

The following product will be installed to destination:
    HP AXPVMS SSL V1.4-310        DISK$ALPHASYS:[VMS$COMMON.]         


Portion done: 
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been installed:
    HP AXPVMS SSL V1.4-310                 Layered Product

%PCSI-I-IVPEXECUTE, executing test procedure for HP AXPVMS SSL 
V1.4-310 ...
%PCSI-I-IVPSUCCESS, test procedure completed successfully

HP AXPVMS SSL Tv1.4-310: SSL for OpenVMS Alpha Version 1.4 (Based on OpenSSL 
0.9.8h)

There are post installation tasks that you must complete
including the following items that are described in detail:

- ensuring SSL startup and logical names creation files
  are executed

- updating or copying the necessary startup, shutdown and
  configuration files from the installed template files

- running the Installation Verification Program (IVP)

Refer to the SSL release notes and the OpenVMS SSL documentation 
for more information about activities that should be performed once 
the installation has finished.

SSL has created the following directory structure and files in
PCSI$DESTINATION (which defaults to SYS$SYSDEVICE:[VMS$COMMON]):

        [SSL]                 Top-level SSL directory
        [SSL.ALPHA_EXE]       Contains the images for the Alpha platform
        [SSL.COM]             Directory to hold the various command procedures
        [SSL.DEMOCA]          Directory structure to demo SSL’s CA features
        [SSL.DEMOCA.CERTS]    Directory to hold the certificates and keys
        [SSL.DEMOCA.CONF]     Contains the configuration files
        [SSL.DEMOCA.CRL]      Contains revoked certificates and CRLs
        [SSL.DEMOCA.PRIVATE]  Directory for private keys and random data
        [SSL.DOC]             OpenSSL.org provided documentation & information
        [SSL.INCLUDE]         Contains the C Header (.H) files
        [SSL.TEST]            Contains the files used during the IVP
        [SYS$STARTUP]         Startup and shutdown templates and files
        [SYSHLP]              Release notes
        [SYSHLP.EXAMPLES.SSL] SSL crypto and secure session examples
        [SYSLIB]              SSL shareable image files
        [SYSTEST]             SSL$IVP.COM test files


    ...after upgrading from previous SSL versions...

The SSL release notes provide information to verify the SSL startup,
shutdown, and configuration template files. Template files provide the 
user with new features or changes, but do not overwrite existing command 
procedures and configuration files.

A product upgrade or re-installation  will not overwrite or create a new 
file version if the file has been modified. It will only create the template
files. It is suggested that you review these files for any changes.

For more information, refer to the SSL Release Notes and other SSL files
using the system logical name definitions, or the subdirectory of the PCSI 
destination device and directory.

    ...including verifying startup command procedures and logical 
names...

Once the installation is complete, verify that SSL$STARTUP.COM is
located in SYS$MANAGER:SYSTARTUP_VMS.COM file. This will define 
the SSL$ executive mode logical names in the SYSTEM logical name 
table,and install the SSL shareable images in memory that reside in 
the [SYSLIB] directory.

Also, add SSL$SHUTDOWN.COM to the SYS$MANAGER:SYSHUTDWN.COM file 
to remove the installed images and deassign the SSL$ logical name 
definitions.

If you have customized the SSL command files for the site, it is
suggested that you compare the SSL provided template files with 
your existing command procedures and take the appropriate action to 
update your files. A product upgrade or re-installation will not 
overwrite these files.

By default SYS$STARTUP: logical can be used to locate the SSL 
provided startup files.

System managers should modify site-specific requirements in SSL 
files:

       SSL$COM:SSL$SYSTARTUP.COM
       SSL$COM:SSL$SYSHUTDOWN.COM

HP recommends that these site-specific SSL command procedures are 
utilized to tailor the SSL installation specific to the requirements of 
the system or site. These files are located in the SSL$COM: directory.

Refer to SYS$HELP:SSL014.RELEASE_NOTES for more information.

The SSL product release notes contain up to date information 
regarding bug fixes, known problems, and general installation information.

%PCSIUI-I-COMPWERR, operation completed after explicit continuation 
from errors
$

Stopping and Restarting the Installation

Use the following procedure to stop and restart the installation: 

To stop the procedure at any time, press Ctrl/Y. 

Enter the DCL command PRODUCT REMOVE SSL to reverse any changes to the 
system that occurred during the partial installation. This deletes all 
files created up to that point and causes the installation procedure 
to exit. 

To restart the installation, go back to the beginning of the 
installation procedure.


   Postinstallation Tasks
---------------------------------------------------------------------

After the installation is complete, perform the steps in one of the 
following sections, depending on the installation method you used. 

-  After Automatic Installation of HP SSL During OpenVMS Installation 
or Upgrade

If you previously installed HP SSL, the existing file SSL$STARTUP.COM 
has been renamed SSL$STARTUP.COM_OLD.  If you made changes to that 
file, manually incorporate your changes from SSL$STARTUP.COM_OLD into 
the new SSL$STARTUP.COM that was installed with Version 1.3.

Define the foreign commands that use the OpenSSL utility OPENSSL.EXE, 
such as openssl, ca, enc, req, and X509, by entering the following 
command:

$ @SSL$COM:SSL$UTILS

Optionally, start the Certificate Tool by entering the following 
command:

$ @SSL$COM:SSL$CERT_TOOL

This menu-driven tool allows you to create and view certificates and 
certificate requests and to sign certificate requests. 

Beginning in OpenVMS Version 8.3, HP SSL for OpenVMS is automatically 
started when OpenVMS is started.  The HP SSL startup file 
SSL$STARTUP.COM has been added to the OpenVMS command procedure 
VMS$LPBEGIN-050_STARTUP.COM.  Startup of HP SSL Version 1.3 is 
required because other OpenVMS components, such as iCAP and Encrypt, 
are dependent on HP SSL.

-   After Download and Installation of HP SSL from Web Site 

Add the following line to the system startup file, 
SYS$STARTUP:SYSTARTUP_VMS.COM, to set up the HP SSL symbols, logical 
names, and shareable images: 

$ @SYS$STARTUP:SSL$STARTUP

At the DCL command prompt, execute the command that you entered into 
the system startup file so that you can use HP SSL immediately. If you 
installed HP SSL to a common system disk in a cluster, execute this 
command on each node in the cluster.

$ @SYS$STARTUP:SSL$STARTUP

Define the foreign commands that use the OpenSSL utility OPENSSL.EXE, 
such as openssl, ca, enc, req, and X509, by entering the following 
command:

$ @SSL$COM:SSL$UTILS

Optionally, start the Certificate Tool by entering the following 
command:

$ @SSL$COM:SSL$CERT_TOOL


   HP SSL Directory Structure
-------------------------------------------------------------------

After the installation is complete, the HP SSL directory structure is 
as follows: 

[SSL] - Top-level directory created by default in 
SYS$SYSDEVICE:[VMS$COMMON]. 
One of the following three directories:
  [SSL.ALPHA_EXE] - Contains images for the Alpha platform.
  [SSL.IA64_EXE] - Contains images for the Integrity server platform.
  [SSL.VAX_EXE] - Contains images for the VAX platform.
[SSL.COM] - Contains command procedures.
[SSL.DEMOCA] - Contains demos for SSL's CA features
[SSL.DEMOCA.CERTS] - Contains certificates and keys.
[SSL.DEMOCA.CONF] - Contains configuration files.
[SSL.DEMOCA.CRL] - Contains revoked certificates and CRLs.
[SSL.DEMOCA.PRIVATE] - Contains private keys and random data.
[SSL.DOC] - OpenSSL Group-provided documentation and information.
[SSL.INCLUDE] - Contains C header (.H) files.
[SSL.TEST] - Contains files used during the Installation Verification 
Procedure (IVP).
[SYS$STARTUP] - Contains startup and shutdown templates and files.
[SYSHLP] - Contains release notes.
[SYSHLP.EXAMPLES.SSL] - Contains SSL crypto and secure session 
examples.
[SYSLIB] - Contains SSL shareable image files.
[SYSTEST] - Contains SSL$IVP.COM test files.

Note that the HP SSL example programs are located in 
SYS$COMMON:[SYSHLP.EXAMPLES.SSL]. (The logical name SSL$EXAMPLES 
points to this directory.)  


   Building an HP SSL Application
-------------------------------------------------------------------

HP SSL for OpenVMS provides shareable images that contain 64-bit APIs 
and shareable images that contain 32-bit APIs. You can choose which 
APIs to use when you compile your application. 

The file names for these shareable images are as follows:

SYS$SHARE:SSL$LIBSSL_SHR.EXE - 64-bit SSL APIs 
SYS$SHARE:SSL$LIBCRYPTO_SHR.EXE -  64-bit Crypto APIs 
SYS$SHARE:SSL$LIBSSL_SHR32.EXE - 32-bit SSL APIs 
SYS$SHARE:SSL$LIBCRYPTO_SHR32.EXE - 32-bit Crypto APIs 

When you compile your application using HP C, use the /POINTER_SIZE=64 
qualifier to take advantage of the 64-bit APIs. The default value for 
the /POINTER_SIZE qualifier is 32. 

Linking your application is the same for both 64-bit or 32-bit APIs. 
The options file used contains either the 64-bit or 32-bit references 
to the appropriate shareable image. 


   Building an Application Using 64-Bit APIs
-------------------------------------------------------------------

To build (compile and link) an example program using the 64-bit APIs, 
enter the following commands: 

$ CC/POINTER_SIZE=64/PREFIX=ALL SAMPLE.C
$ LINK/MAP SAMPLE,LINKER_OPT/OPTIONS

In these commands, LINKER_OPT.OPT is a simple text file that contains 
the following lines: 

SYS$SHARE:SSL$LIBSSL_SHR/SHARE
SYS$SHARE:SSL$LIBCRYPTO_SHR/SHARE

   Building an Application Using 32-Bit APIs
-------------------------------------------------------------------

To build (compile and link) an example program using the 32-bit APIs, 
enter the 
following commands: 

$ CC/PREFIX=ALL SAMPLE.C
$ LINK/MAP SAMPLE,LINKER_OPT/OPTIONS

In these commands, LINKER_OPT.OPT is a simple text file that contains 
the following lines:

SYS$SHARE:SSL$LIBSSL_SHR32/SHARE
SYS$SHARE:SSL$LIBCRYPTO_SHR32/SHARE

   Release Notes
-------------------------------------------------------------------

This section contains notes on the current release of HP SSL for 
OpenVMS.

This is an issue (man-in-the-middle attack) found with SSL Renegotiation
in OpenSSL 0.9.8H code stream, hence SSL renegotiation feature has been 
disabled in HP SSL Version 1.4 kit. 

Engineering will be releasing the fix for this issue in a future release.


   Legal Caution
-------------------------------------------------------------------

SSL data transport requires encryption. Many governments, including 
the United States, have restrictions on the import and export of 
cryptographic algorithms. Please ensure that your use of HP SSL is in 
compliance with all national and international laws that apply to you. 


   HP SSL APIs Not Backward Compatible
-------------------------------------------------------------------

HP cannot guarantee the backward compatibility of HP SSL for OpenVMS 
until the release of HP SSL for OpenVMS that is based on OpenSSL 1.0.0 
from The Open Group.

The HP SSL Version 1.3 for OpenVMS code is based on the 0.9.7e 
baselevel of OpenSSL. Any OpenSSL API, data structure, header file, 
command, and so on might be changed in a future version of OpenSSL. 

The HP SSL shareable images use EQUAL 1,0 which means that 
applications will have to relink when the idents on the shareable 
images have changed, as they have in HP SSL Version 1.3. 

If you were running a version of HP SSL prior to Version 1.2, you must 
recompile and relink your code after you upgrade to Version 1.3.  You 
must relink your code if you see the following error:

$ run ssl_test

%DCL-W-ACTIMAGE, error activating image SSL$LIBSSL_SHR32
-CLI-E-IMGNAME, image file 
DWLLNG$DKA500:[SYS0.SYSCOMMON.][SYSLIB]SSL$LIBSSL_SHR32.EXE
-SYSTEM-F-SHRIDMISMAT, ident mismatch with shareable image
$

   Changes to APIs in OpenSSL 0.9.7e
-------------------------------------------------------------------

A number of APIs have been changed in HP SSL Version 1.3. See Appendix 
B for a list of new and changed APIs. 

   Preserve Configuration Files Before Manually Uninstalling HP SSL
-------------------------------------------------------------------

Preserving configuration files is not necessary when you perform a 
regular upgrade or reinstallation of HP SSL using the PRODUCT INSTALL 
command. 
Using the PRODUCT REMOVE command to manually uninstall HP SSL is not 
recommended (see the following note).  However, if you made any 
modifications to the HP SSL configuration files, preserve the files by 
backing up these files to a different disk and directory before you 
enter the PRODUCT REMOVE command that removes the HP SSL kit.  
Otherwise, any changes you made to OPENSSL-VMS.CNF and OPENSSL.CNF 
will be lost.  When you have completed the Version 1.3 installation, 
move the saved items back into the HP SSL directory structure.

Warning Against Uninstalling HP SSL from OpenVMS Version 8.3 or 
Higher Using the PRODUCT REMOVE Command
-------------------------------------------------------------------

The POLYCENTER Software Installation utility command PRODUCT REMOVE is 
not supported for HP SSL on OpenVMS Version 8.3 or higher, even though 
there is an apparent option to remove HP SSL.  HP SSL is installed 
together with the operating system and is tightly bound with it. An 
attempt to remove it from Version 8.3 or higher would not work cleanly 
and could create other undesirable side effects. 

If you ignore the warning and continue to remove HP SSL, HP strongly 
recommends that you use PRODUCT INSTALL to install the HP SSL Version 
1.3 PCSI kit as soon as possible.  An attempt to remove HP SSL results 
in the following message:
%PCSI-E-HRDREF, product HP AXPVMS SSL V1.3-xxx is referenced by DEC 
AXPVMS OPENVMS V8.3-xxx

The two products listed above are tightly bound by a software 
dependency.

If you override the recommendation to terminate the operation, the
referenced product will be removed, but the referencing product 
will have an unsatisfied software dependency and may no longer function 
correctly.

Please review the referencing product’s documentation on 
requirements.

Answer YES to the following question to terminate the PRODUCT 
command.However, if you are sure you want to remove the referenced product 
then answer NO to continue the operation.

Terminating is strongly recommended.  Do you want to terminate? [YES]

   SSL$DEFINE_ROOT.COM Removed From SSL$STARTUP.COM
-------------------------------------------------------------------

Beginning in HP SSL Version 1.3, SSL is installed on the system disk 
only.  To reflect this change, the command procedure 
SSL$DEFINE_ROOT.COM has been removed from SSL$STARTUP.COM. 
(SSL$DEFINE_ROOT.COM  was included in HP SSL Version 1.2 to define the 
logical SSL$ROOT.  In Version 1.2, it was possible to install HP SSL 
to locations other than the system disk.)

The logical name SSL$ROOT is now defined in SSL$STARTUP.COM, and 
points to SYS$SYSDEVICE:[VMS$COMMON.SSL.].

   SSL$STARTUP.TEMPLATE Removed From HP SSL Version 1.3
-------------------------------------------------------------------

HP SSL Version 1.3 no longer contains SSL$STARTUP.TEMPLATE.  Before 
overwriting the file, HP SSL copies your existing SSL$STARTUP.COM file 
to SSL$STARTUP.COM_OLD to preserve any changes that you may have made 
to SSL$STARTUP.COM in the past. 

If you are upgrading from a previous version of HP SSL, after the 
installation is complete compare your SSL$STARTUP.COM_OLD file and the 
new SSL$STARTUP.COM file, and add any modifications you made to the 
new file.   (Version 1.3 continues to provide the configuration 
template files OPENSSL.CNF_TEMPLATE and OPENSSL-VMS.CNF_TEMPLATE.  See 
the following note for more information.)  
Use SSL$COM:SSL$SYSTARTUP.COM to make additions or changes to the 
startup of HP SSL.  SSL$COM:SSL$SYSTARTUP.COM is executed from 
SSL$STARTUP.COM.  SSL$STARTUP.COM has been added to the OpenVMS 
command procedure VMS$LPBEGIN-050_STARTUP.COM so that SSL is started 
when OpenVMS is started.

   Configuration Command Procedure Template Files
-------------------------------------------------------------------

The configuration files included in the HP SSL kit are named 
OPENSSL.CNF_TEMPLATE and OPENSSL-VMS.CNF_TEMPLATE.  This prevents PCSI 
from overwriting the .CNF files, and allows you to preserve any 
modifications you made to OPENSSL.CNF and OPENSSL-VMS.CNF if you 
installed a previous release of  HP SSL for OpenVMS. 

If you are upgrading from a previous version of HP SSL, after you 
install the HP SSL kit, compare the new .CNF_TEMPLATE files with your 
existing .CNF files and add any new information as required. 

If you did not previously install an HP SSL for OpenVMS kit, both the 
.CNF_TEMPLATE and .CNF files are provided. 

   HP SSL Requirement to Install on System Disk
-------------------------------------------------------------------

The option to install to a location other than the system disk is no 
longer available beginning in HP SSL Version 1.3.  HP SSL is installed 
on the system disk automatically when you install or upgrade to 
OpenVMS Version 8.3.  If you download HP SSL Version 1.3 from the web 
site and install it as a layered product, it too must be installed on 
the system disk. 

   Shut Down HP SSL Before Installing on Common System Disk
-------------------------------------------------------------------

Before installing HP SSL to a common system disk in a cluster, you 
must first shut down HP SSL by entering the following command on each 
node in the cluster:

$ @SYS$STARTUP:SSL$SHUTDOWN

Shutting down HP SSL deassigns logical names and removes installed 
shareable images that may interfere with the installation.
After the installation is complete, start HP SSL by entering the 
following command on each node in the cluster:

$ @SYS$STARTUP:SSL$STARTUP

Note: If you are installing on a common cluster disk and not a common 
system disk, omit the SYS$STARTUP logical and specify the specific 
startup directory in the shutdown and startup commands. For example:

$ @device:[directory.SYS$STARTUP]SSL$SHUTDOWN
$ @device:[directory.SYS$STARTUP]SSL$STARTUP

   OpenSSL Version Command Displays HP SSL for OpenVMS Version
-------------------------------------------------------------------

Beginning with HP SSL Version 1.2, the OpenSSL command line utility 
command VERSION now includes the HP SSL for OpenVMS version.  The 
OpenSSL VERSION command displays output similar to the following:

$ OPENSSL VERSION
OpenSSL 0.9.7e 25 Oct 2004
SSL for OpenVMS V1.3 May 26 2006

   Shareable Images Containing 64-Bit and 32-Bit APIs Provided
-------------------------------------------------------------------

HP SSL for OpenVMS provides shareable images that contain 64-bit APIs 
and shareable images that contain 32-bit APIs. You can choose which 
APIs to use when you compile your application. For more information, 
see Building an HP SSL Application. 

   Linking with HP SSL Shareable Images
-------------------------------------------------------------------

If you have written an application that links against the OpenSSL 
object libraries, you must make a minor change to your code because HP 
SSL for OpenVMS provides only shareable images. To link your 
application against the shareable images, use code similar to the 
following: 

$ LINK my_app.obj, VMS_SSL_OPTIONS/OPT  

where VMS_SSL_OPTIONS.OPT is a text file that contains the following 
lines:

SYS$SHARE:SSL$LIBCRYPTO_SHR.EXE/SHARE
SYS$SHARE:SSL$LIBSSL_SHR.EXE/SHARE

   Certificate Tool Cannot Have Simultaneous Users
-------------------------------------------------------------------

Only one user/process should use the Certificate Tool at a time. The 
tool does not have a locking mechanism to prevent unsynchronized 
accesses of the database and serial file, which could cause database 
corruption. 

   Protect Certificates and Keys
-------------------------------------------------------------------

When you create certificates and keys with the Certificate Tool, take 
care to ensure that the keys are properly protected to allow only the 
owner of the keys to use them. A private key should be treated like a 
password. You can use OpenVMS file protections to protect the key 
file, or you can use ACLs to protect individual key files within a 
common directory.

   Enhancements to the HP SSL Example Programs
-------------------------------------------------------------------

Beginning with HP SSL Version 1.2, several enhancements and changes 
were made to the HP SSL example programs located in 
SYS$COMMON:[SYSHLP.EXAMPLES.SSL].  These include new examples (for 
example, using HP SSL with QIO, AES encryption, and SHA1DIGEST) and 
additional common callbacks and routines to SSL_EXAMPLES.H includes 
file. Extra calls to free routines have been removed from the examples 
along with general code clean up. 

   SSL$EXAMPLES Logical Name
-------------------------------------------------------------------

The SSL$EXAMPLES logical name has been added to the 
SSL$STARTUP.TEMPLATE command procedure.  This logical points to the 
directory SYS$COMMON:[SYSHLP.EXAMPLES.SSL]. 

   Environment Variables
-------------------------------------------------------------------

OpenSSL environmental variables have two formats, as follows: 

$var
${var}

In order for these variables to be parsed properly and not be confused 
with logical names, HP SSL for OpenVMS only accepts the  ${var} 
format.

   IDEA and RC5 Symmetric Cipher Algorithms Not Supported
-------------------------------------------------------------------

The IDEA and RC5 symmetric cipher algorithms are not available in HP 
SSL for OpenVMS. Both of these algorithms are under copyright 
protection, and HP does not have the right to use these algorithms. 
If you want to use either of these algorithms, HP recommends that you 
contact RSA Security at the following URL for the licensing conditions 
of the RC5 algorithm:

http://www.rsasecurity.com

If you want to use the IDEA algorithm, contact Ascom for their license 
requirements at the following URL:

http://www.ascom.com
Once you have obtained the proper licenses, download the source code 
from the following URL: 

http://www.openssl.org

Build the product using the command procedure named MAKEVMS.COM 
provided in the download.

APIs RAND_egd, RAND_egd_bytes, and RAND_query_egd_bytes Not 
Supported 
-------------------------------------------------------------------

The RAND_egd(), RAND_egd_bytes(), and RAND_query_egd_bytes() APIs are 
not available on OpenVMS. 
To obtain a secure random seed on OpenVMS, use the RAND_poll() API.

   Documentation from the OpenSSL Web Site 
-------------------------------------------------------------------

The documentation on the OpenSSL website is under development. It is 
likely that the API and command line documentation shipped with this 
kit will differ from the documentation on the OpenSSL website at some 
point. If such a situation arises, you should consider the API 
documentation on the OpenSSL website to have precedence over the 
documentation included in this kit.

   Extra Certificate Files — *PEM
-------------------------------------------------------------------

When you sign a certificate request using either the Certificate Tool 
or the OpenSSL utility, you may notice that an extra certificate is 
produced with a name similar to SSL$CRT01.PEM. This certificate is the 
same as the certificate that you produced with the name you chose. 
These extra files are the result of the OpenSSL demonstration 
Certificate Authority (CA) capability, and are used as a CA accounting 
function. These extra files are kept by the CA and can be used to 
generate Certificate Revocation Lists (CRLs) if the certificate 
becomes compromised.

   Known Problem:  Certificate Verification with OpenVMS File 
Specifications
-------------------------------------------------------------------

OpenSSL is unable to properly parse OpenVMS file specifications when 
they are passed in as CApath directories.  If you try to do this, 
OpenSSL returns the following error:

unable to get local issuer certificate

To work around this problem, define a logical that points to the 
OpenVMS directory, as follows:

$ define vms_cert_dir dka300:[ssl.certificates]
$ openssl verify “-CApath” vms_cert_dir –purpose any 
example.crt

   Known Problem:  BIND Error in TCP/IP Application
-------------------------------------------------------------------

If you are running a TCP/IP-based SSL client/server application, the 
server occasionally fails to start up, and displays the following 
error message: 
bind: address already in use

To avoid this error, use setsockopt() with SO_REUSEADDR as follows:

int   on = 1;
ret = setsockopt(listen_sock, SOL_SOCKET, SO_REUSEADDR, (void *)
&on, sizeof(on));

   Known Problem:  Server Hang in HP SSL Session Reuse Example Program
-------------------------------------------------------------------

In HP SSL Version 1.1-B and higher, a server hang problem may occur 
when you are running one of the HP SSL session reuse example programs. 
The server hang occurs when a VAX system acts as a client and the 
server is an Alpha or Integrity server system in this mixed architecture, 
client-server test.

When the client SSL$CLI_SESS_REUSE.EXE program is run on a VAX system, 
and the server SSL$SERV_SESS_REUSE.EXE program is run on an Alpha or 
Integrity server system, the server appears to hang waiting for further
session reconnections, because the loop counts differ.  In fact, the VAX 
client has finished and closed the connection. There is no problem 
when the client server roles are reversed, or if the same system acts 
as both client and server. 

   Known Problem:  Compaq C++ V5.5 CANTCOMPLETE Warnings
-------------------------------------------------------------------

When you compile programs that contain OpenSSL APIs, Compaq C++ 
Version 5.5 issues warnings about incomplete classes. This error 
occurs when you use a structure definition before it has been defined. 
You can resolve these warnings in one of two ways: 

Upgrade to C++ Version 6.0 or higher.

Supply the necessary prototype before using the structure. 

The following is an example of this error:

$ cxx/list/PREFIX=(ALL_ENTRIES) serv.c
        struct CRYPTO_dynlock_value *data;
        ........^
        %CXX-W-CANTCOMPLETE, In this declaration, the incomplete class 

   "unnamed struct::CRYPTO_dynlock_value" 
         cannot be completed because it is declared within a 
    class or a function prototype.
         at line number 161 in file 
    CRYPTO$RES:[OSSL.BUILD_0049_ALPHA_32.INCLUDE.OPENSSL]CRYPTO.H;3

   Problem Corrected:  Possible Errors Using PRODUCT REMOVE
-------------------------------------------------------------------

In HP SSL Version 1.2, when you used the PCSI REMOVE SSL command to 
remove previous versions of HP SSL, certain DCL symbols were not set 
up properly.  This would result in various file not found errors. 
This problem has been corrected in HP SSL Version 1.3.

Problem Corrected:  Error Running OpenSSL Command Line Utility on 
ODS-5 Disks
-------------------------------------------------------------------

In previous versions of HP SSL, an invalid command error was displayed 
when you tried to run OpenSSL commands on an ODS-5 disk with the 
following parsing logicals set:

$ SET PROCESS/PARSE=EXTENDED
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE

This problem has been corrected beginning in HP SSL Version 1.2.  
OpenSSL commands now work on both ODS-2 and ODS-5 disks, regardless of 
the parse settings.

Problem Corrected:  Attempt to Encrypt within SMIME Subutility 
Caused Access Violation
-------------------------------------------------------------------

In versions of HP SSL earlier than Version 1.2, if you entered an 
OpenSSL SMIME command, an access violation was returned. For example:

$ openssl smime -encrypt -in in.txt ssl$certs:server.pem
%SYSTEM-F-ACCVIO, access violation, reason mask=00, virtual 
address=FFFFFFFFF00D2B10, PC=000000000017DD0C, PS=0000001B
Improperly handled condition, image exit forced.

This problem was corrected in OpenSSL 0.9.7d, and has been included 
beginning in HP SSL Version 1.2.

Problem Corrected:  Race Condition When CRLs are Checked in a 
Multithreaded Environment
-------------------------------------------------------------------

In versions of HP SSL earlier than Version 1.2, a race condition would 
occur when CRLs were checked in a multithreaded environment. This 
would happen because of the reordering of the revoked entries during 
signature checking and serial number lookup.

In OpenSSL 0.9.7e and HP SSL Version 1.2 and higher, the encoding is 
cached and the serial number sort is performed under a lock.

-- end of file --

