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.

	NOTE: 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. For more information about the example programs, see Chapter 5.

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:

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

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.