Release Notes

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 2:...

Installation and Release Notes

Building an HP SSL Application

Overview of SSL

Release Notes

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

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 for OpenVMS code is based on the 0.9.7d baselevel of OpenSSL, with security fixes included in 0.9.7e. 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.2.

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.2. You have not relinked 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 SSL APIs in OpenSSL 0.9.7d

A number of SSL and CRYPTO APIs have been changed in HP SSL Version 1.2. The differences in APIs are the result of changes made to OpenSSL between the 0.9.6 and 0.9.7 streams. See Appendix B for a list of new SSL APIs and changes to existing SSL APIs. See openssl.org for information about changes to the CRYPTO APIs.

Preserve Configuration Files Before Removing Previous Version

If you made any modifications to the HP SSL configuration files, preserve the files before you enter the PRODUCT REMOVE command that manually removes the HP SSL kit. Otherwise, any changes you made to OPENSSL-VMS.CNF and OPENSSL.CNF will be lost. HP recommends that you back up these files to either a different disk and directory or to tape. When you have completed the Version 1.2 installation, move the saved items back into the HP SSL directory structure. Then you can delete the backed up configuration files.

Preserving configuration files is not necessary when you perform a regular upgrade or reinstallation of HP SSL using the PRODUCT INSTALL command.

Remove Previous Kits Before Installing Version 1.2

Because the HP SSL Version 1.2 PCSI filename has changed from a CPQ to an HP prefix, PCSI considers Version 1.2 to be a separate product from earlier kits, and does not automatically remove the earlier kits. Therefore, HP recommends that you manually remove any previously installed versions of HP SSL before you install Version 1.2. (You must also remove the T1.2 field test kit, if it is installed, before you install Version 1.2.)

To manually remove previously installed versions of HP SSL, enter the following command:

$ PRODUCT REMOVE SSL

SSL$DEFINE_ROOT.COM Moved to Enable Installation on Non-System Disk

The file SSL$DEFINE_ROOT.COM is created during the installation of HP SSL. It defines a logical that points to the directory in which HP SSL was installed. In previous versions of HP SSL, this file was located in SYS$SPECIFIC:[SYS$STARTUP]. Because Version 1.2 allows HP SSL to be installed on a non-system disk or a system disk, during the installation of Version 1.2 the file SSL$DEFINE_ROOT.COM is now created in SYS$COMMON:[SYS$STARTUP].

If you have previously installed the T1.2 field test kit, you must manually remove it before installing Version 1.2 so that PCSI can perform the proper clean up of files and install new files in their correct locations.

To manually remove previously installed versions of HP SSL, enter the following command:

$ PRODUCT REMOVE SSL

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

New UNIQUE_SUBJECT Variable in the OPENSSL-VMS.CNF Configuration File

In versions earlier than HP SSL Version 1.2, it was not possible to have two certificates with the same subject name in the database. This made it difficult to issue new certificates when the old certificates were about to expire. In Version 1.2, you can now have multiple certificates with the same subject name. This behavior is controlled by the UNIQUE_SUBJECT variable found in the OPENSSL-VMS.CNF configuration file.

If UNIQUE_SUBJECT is set to YES, then certificates must have unique subject names. If it is set to NO, then certificates can have duplicate subject names, and are distinguished from one another by the serial number that is assigned to them.

The default behavior for HP SSL Version 1.2 is for UNIQUE_SUBJECT to be set to YES so that certificates are required to have unique subject names.

After a CA and its database is created, the UNIQUE_SUBJECT variable should not be changed. If at a later time you want to change the setting, you must recreate the entire database.

When you run the Certificate Tool (by entering SSL$COM:SSL$CERT_TOOL.COM, described in Chapter 3), and you choose the Create Certification Authority option, the question "Unique Subject Names?" is displayed, and a yes or no response is needed. This response is saved in the Certificate Tool configuration file, and all certificate signings will utilize the response.

Startup and Shutdown Command Procedure Template Files

The SYS$STARTUP:SSL$STARTUP.COM and SYS$STARTUP:SSL$SHUTDOWN.COM command procedures included in the HP SSL kit are named SYS$STARTUP:SSL$STARTUP.TEMPLATE and SYS$STARTUP:SSL$SHUTDOWN.TEMPLATE. This prevents PCSI from overwriting the .COM files, and allows you to preserve any modifications you made to SSL$STARTUP.COM and SSL$SHUTDOWN.COM 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 .TEMPLATE files with your existing SSL$STARTUP.COM and SSL$SHUTDOWN.COM files and add any new information as required.

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

Configuration files are provided in the same fashion -- both .CNF and .CNF_TEMPLATE files are included in HP SSL for OpenVMS.

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.7d 17 Mar 2004
SSL for OpenVMS V1.2 Nov 3 2004

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

Version 1.2 includes several enhancements and changes 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].

DES_CBC_CKSUM Return Value Changed to Match Kerberos

The return value of the DES_CBC_CKSUM API has changed to match its intended compatibility with MIT Kerberos. The DES_CBC_CKSUM routine returns the upper longword of a quadword. The quadword itself was calculated correctly, and has not been changed.

Prior to the change (in Compaq SSL V1.0-B and earlier), the API returned the value in the wrong order. For example:

Return value from des_cbc_cksum = 0xaedc29b6

The return value now is as follows:

Return value from des_cbc_cksum = 0xb629dcae

This change has been accepted by OpenSSL.org, and is available in the 0.9.7a (and higher) releases of OpenSSL.

DES Image Included

HP SSL contains a standalone image, DES.EXE, that provides functionality that is not present in the DES subcommand in the OPENSSL command line interface, most notably the ability to enable uuencoding and uudecoding. The DES.EXE image is located in the SSL$EXE directory. Create a foreign symbol to access this image, as follows:

$ DES :== $SSL$EXE:DES.EXE

Following is the help text for the DES command and the DES subcommand in the OPENSSL command line interface, which illustrates the differences between the commands.

$ DES -?
'?' unknown flag
des <options> [input-file [output-file]]
options:
-v         : des(1) version number
-e         : encrypt using SunOS compatible user key to DES key conversion.
-E         : encrypt
-d         : decrypt using SunOS compatible user key to DES key conversion.
-D         : decrypt
-c[ckname] : generate a cbc_cksum using SunOS compatible user key to
             DES key conversion and output to ckname (stdout default,
             stderr if data being output on stdout).  The checksum is
             generated before encryption and after decryption if used
             in conjunction with -[eEdD].
-C[ckname] : generate a cbc_cksum as for -c but compatible with -[ED].
-k key     : use key 'key'
-h         : the key that is entered will be a hexadecimal number
             that is used directly as the des key
-u[uuname] : input file is uudecoded if -[dD] or output uuencoded data if -[eE]
             (uuname is the filename to put in the uuencode header).
-b         : encrypt using DES in ecb encryption mode, the default is cbc mode.
-3         : encrypt using triple DES encryption.  This uses 2 keys
             generated from the input key.  If the input key is less
             than 8 characters long, this is equivalent to normal
             encryption.  Default is triple cbc, -b makes it triple ecb.
 
$ OPENSSL DES -?
unknown option '-?'
options are
-in <file>     input file
-out <file>    output file
-pass <arg>    pass phrase source
-e             encrypt
-d             decrypt
-a/-base64     base64 encode/decode, depending on encryption flag
-k             key is the next argument
-kfile         key is the first line of the file argument
-K/-iv         key/iv in hex is the next argument
-[pP]          print the iv/key (then exit if -P)
-bufsize <n>   buffer size
-engine e      use engine e, possibly a hardware device.
Cipher Types
des     : 56 bit key DES encryption
des_ede :112 bit key ede DES encryption
des_ede3:168 bit key ede DES encryption
rc2     :128 bit key RC2 encryption
bf      :128 bit key Blowfish encryption
 -rc4   :128 bit key RC4 encryption
 -des-ecb      -des-cbc      -des-cfb      -des-ofb      -des  (des-cbc)
 -des-ede      -des-ede-cbc  -des-ede-cfb  -des-ede-ofb  -desx -none
 -des-ede3     -des-ede3-cbc -des-ede3-cfb -des-ede3-ofb -des3 (des-ede3-cbc)
 -rc2-ecb      -rc2-cbc      -rc2-cfb      -rc2-ofb      -rc2  (rc2-cbc)
 -bf-ecb       -bf-cbc       -bf-cfb       -bf-ofb       -bf   (bf-cbc)
 -cast5-ecb    -cast5-cbc    -cast5-cfb    -cast5-ofb    -cast (cast5-cbc)

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

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: 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 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 previous versions of HP SSL, 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 has been corrected in OpenSSL 0.9.7e, and has been included in HP SSL Version 1.2.

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

In previous versions of HP SSL, 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, the encoding is cached and the serial number sort is performed under a lock.

Building an HP SSL Application

Overview of SSL