VSI-AXPVMS-SSL111-V0101-1IA-1-RNOTES.PDF

This document provides the Installation Guide and Release Notes for VSI SSL111 Version 1.1-11 for OpenVMS Alpha servers, released in December 2020. It is based on Open Source OpenSSL version 1.1.1i.

Key Information:

1. Prerequisites:

   • Requires approximately 200,000 blocks of disk space for installation (170,000 blocks installed).
   • OpenVMS Alpha server Version 8.4-1H1 or later.
   • No specific account quotas or system parameters are required.

2. Coexistence and Migration (Crucial Points):

   • VSI SSL111 (OpenSSL 1.1.1 stream) is designed to coexist with older VSI SSL V1.4 (OpenSSL 0.9.8) and VSI SSL1 (OpenSSL 1.0.2) on the same system by using distinct naming conventions (e.g., SSL111$ prefixes for logical names, directories, command procedures, and library names).
   • Backward Compatibility: VSI SSL111 V1.1 is not backward compatible with VSI SSL V1.4 or SSL1. Applications dependent on older VSI SSL versions must be recompiled and relinked against the new VSI SSL111 header files and shareable images.
   • Certificate Store Migration: When migrating from older VSI SSL versions, existing certificate stores need to be copied to the new SYS$SYSDEVICE:[VMS$COMMON.SSL111.DEMOCA...] directory. Critically, the certificate hash algorithm has changed from MD5 (V1.4/SSL1) to SHA-1 (SSL111 V1.1). This means existing certificate files, named after their MD5 hash, will cause validation failures. Users must manually rename certificate files to their corresponding SHA-1 hash names.
   • Logical Name OPENSSL: This common logical name will point to the version of the product (SSL, SSL1, or SSL111) that was started last. Care must be taken to ensure it points to SSL111$INCLUDE: before rebuilding applications.
   • Custom Procedures/Configuration: Any custom command procedures or OpenSSL configuration files (OPENSSL.CNF, OPENSSL-VMS.CNF) modified for older SSL versions must be updated and copied to the new SSL111$ directories.

3. Installation & Post-Installation:

   • Installation is performed using the $ PRODUCT INSTALL SSL111 command.
   • VSI SSL111 must be installed on the system disk.
   • For clustered environments, SSL111 must be shut down on all nodes before installation and started on all nodes after.
   • SSL111$STARTUP.COM must be added to SYS$MANAGER:SYSTARTUP_VMS.COM and invoked last to ensure correct logical name definitions.
   • The SSL111$SHUTDOWN.COM should be added to SYS$MANAGER:SYSHUTDWN.COM.
   • An Installation Verification Procedure (@SYS$TEST:SSL111$IVP.COM) and a Certificate Tool (@SSL111$COM:SSL111$CERT_TOOL) are available.

4. Application Development:

   • VSI SSL111 provides separate 64-bit and 32-bit APIs (e.g., SSL111$LIBSSL_SHR.EXE for 64-bit, SSL111$LIBSSL_SHR32.EXE for 32-bit).
   • To use 64-bit APIs, compile with /POINTER_SIZE=64. Linking uses options files to specify the correct shareable images.

5. Release Notes & Limitations:

   • TLS1_ALLOW_EXPERIMENTAL_CIPHERSUITES is enabled.
   • Legal caution regarding cryptographic export restrictions.
   • The Certificate Tool does not have locking mechanisms; only one user/process should use it at a time to prevent database corruption.
   • Certificates and keys must be properly protected using OpenVMS file protections or ACLs.
   • OpenSSL environment variables require the ${var} format.
   • IDEA, RC5, MDC2 symmetric ciphers are not supported due to copyright.
   • RAND_egd, RAND_egd_bytes, and RAND_query_egd_bytes APIs are not available; use RAND_poll() for secure random seeds.
   • OpenSSL documentation on the OpenSSL website should take precedence over the kit's documentation, as it's written for UNIX and may differ.