VSI SSL3 for OpenVMS V3.0-7 Release Notes December 2022 Based on OpenSSL 3.0.7 VSI SSL3 V3.0-7 for OpenVMS Integrity server VSI-I64VMS-SSL3-V0300-7-1.PCSI ---------------------------------------------------------- VMS Software, Inc. is pleased to provide you with the latest release of VSI SSL3 for OpenVMS. VSI SSL3 (Secure Sockets Layer) is based on the 3.0.7 release from the OpenSSL Group. The VSI SSL3 product is designed to co-exist with VSI SSL 1.4, VSI SSL1 and VSI SSL111 so that applications and components dependent on either version will run on the same system. Below is the snapshot of co-existing VSI SSL V1.4, SSL1, SSL111 and VSI SSL3: $ product show product ssl* ------------------------------------ ----------- --------- PRODUCT KIT TYPE STATE ------------------------------------ ----------- --------- VSI I64VMS SSL V1.4-503 Full LP Installed VSI I64VMS SSL1 V1.0-2UA Full LP Installed VSI I64VMS SSL111 V1.1-1M Full LP Installed VSI I64VMS SSL3 V3.0-7 Full LP Installed ------------------------------------ ----------- --------- 3 items found For more information related to coexistence in terms of using directory structures, command procedure names, libraries, and logical names refer to SSL3_I64_INSTALL_RELEASE_NOTES.TXT "Installation Guide and Release Notes" found in the SYS$COMMON:[SSL3.DOC] directory. See http://www.openssl.org for information about OpenSSL. There are post installation activities that need to be performed. This includes the following items that are described in detail: - Ensuring SSL3 startup and logical name creation files are executed - Updating or copying the necessary startup, shutdown, and configuration files from the installed template files - Running the Installation Verification Procedure (IVP) The SSL3 installation creates the following directory structure and files in PCSI$DESTINATION, which defaults to SYS$SYSDEVICE:[VMS$COMMON]: [SSL3] - Top-level SSL3 directory [SSL3.IA64_EXE] - Contains the images for the Integrity server platform* [SSL3.COM] - Directory to hold the various command procedures [SSL3.DEMOCA] - Directory structure to demo SSL3's CA features [SSL3.DEMOCA.CERTS] - Directory to hold the certificates and keys [SSL3.DEMOCA.CONF] - Contains the configuration files [SSL3.DEMOCA.CRL] - Contains revoked certificates and CRLs [SSL3.DEMOCA.PRIVATE] - Directory for private keys and random data [SSL3.DOC] - OpenSSL.org provided documentation and information [SSL3.INCLUDE] - Contains the C Header (.H) files [SSL3.LIB] - Contains static libraries (.OLB) files [SSL3.MODULES] - Contains dynamically loadable OpenSSL modules [SSL3.TEST] - Contains the files used during the IVP [SSL3.TEST.EVP_DATA] - Contains resources for tests of a high level interface [SYS$STARTUP] - Startup and shutdown templates and files [SYSHLP] - Release notes [SYSHLP.EXAMPLES.SSL3] - SSL3 crypto and secure session examples [SYSLIB] - SSL3 shareable image files [SYSTEST] - SSL3$IVP.COM test file * Note: Each system will have only one xxx_EXE.DIR, depending on the architecture of the system. SSL3 startup, shutdown, and logical names ------------------------------------------- Add SSL3$STARTUP.COM to SYS$MANAGER:SYSTARTUP_VMS.COM to define SSL3$ logical names and install shareable images. If there is already a SSL$STARTUP.COM and/or SSL1$STARTUP.COM present in SYSTARTUP_VMS.COM you can either comment these out or conditionalize the command procedure as appropriate. For example: $ if f$search("sys$startup:ssl$startup.com") .nes. "" $ then $ @sys$startup:ssl$startup.com $ endif $ if f$search("sys$startup:ssl1$startup.com") .nes. "" $ then $ @sys$startup:ssl1$startup.com $ endif $ if f$search("sys$startup:ssl111$startup.com") .nes. "" $ then $ @sys$startup:ssl111$startup.com $ endif $ if f$search("sys$startup:ssl3$startup.com") .nes. "" $ then $ @sys$startup:ssl3$startup.com $ endif The SSL3$STARTUP.COM, SSL111$STARTUP.COM, SSL1$STARTUP.COM and SSL$STARTUP.COM startup command procedures in the above example will automatically define the SSL3$, SSL111$, SSL1, and SSL$ executive-mode logical names in the SYSTEM logical name table and will install into memory the SSL3, SSL111, SSL1, and SSL 1.4 shareable images that reside in the [SYSLIB] directory. Ensure that the SSL3$STARTUP.COM command procedure is invoked after invoking SSL$STARTUP.COM, SSL1$STARTUP.COM or SSL111$STARTUP.COM. The command procedures define a common logical "OPENSSL" that points to the include (header) file directory used when building applications using OpenSSL. Invoking SSL3$STARTUP.COM last ensures that the logical is defined to correctly point to the latest VSI SSL3 3.0 header files. Also, add SSL3$SHUTDOWN.COM to SYS$MANAGER:SYSHUTDWN.COM to remove installed images and deassign the SSL3$ logical names at system shutdown. If there is a SSL$SHUTDOWN.COM and/or SSL1$SHUTDOWN.COM already present in SYS$MANAGER:SYSHUTDWN.COM, conditionalize the script as appropriate. For example: $ if f$search("sys$startup:ssl$shutdown.com") .nes. "" $ then $ @sys$startup:ssl$shutdown.com $ endif $ if f$search("sys$startup:ssl1$shutdown.com") .nes. "" $ then $ @sys$startup:ssl1$shutdown.com $ endif $ if f$search("sys$startup:ssl111$shutdown.com") .nes. "" $ then $ @sys$startup:ssl111$shutdown.com $ endif $ if f$search("sys$startup:ssl3$shutdown.com") .nes. "" $ then $ @sys$startup:ssl3$shutdown.com $ endif Please refer to "Logical names" under section "Coexistence and major changes between VSI SSL V1.4, VSI SSL1, VSI SSL111 and VSI SSL3" in VSI SSL3 installation guide. Apply SSL specific changes to SSL3 files ------------------------------------------ If this is the first time using a system with VSI SSL3 V3.0 and there exist site-specific changes to VSI SSL V1.4, VSI SSL1 or VSI SSL111 files then it may be necessary to migrate those changes to the SSL3 environment. Examples: - Copy any manual changes done to the site-specific startup command procedures SSL$COM:SSL$SYSTARTUP.COM, SSL1$COM:SSL1$SYSTARTUP.COM or SSL111$COM:SSL111$SYSTARTUP.COM to SSL3$COM:SSL3$SYSTARTUP.COM. - If SYS$STARTUP:SSL$STARTUP.COM, SYS$STARTUP:SSL1$STARTUP.COM or SSL111$COM:SSL111$SYSTARTUP.COM have any manual changes, ensure that these changes are copied to the site-specific startup command procedure SSL3$COM:SSL3$SYSTARTUP.COM. This command procedure will be invoked by SYS$STARTUP:SSL3$STARTUP.COM. - Copy any manual changes done to the site-specific shutdown command procedures SSL$COM:SSL$SYSHUTDOWN.COM, SSL1$COM:SSL1$SYSHUTDOWN.COM or SSL111$COM:SSL111$SYSHUTDOWN.COM to SSL3$COM:SSL3$SYSHUTDOWN.COM. - If SYS$STARTUP:SSL$SHUTDOWN.COM or SYS$STARTUP:SSL1$SHUTDOWN.COM have any manual changes, ensure that these changes are copied to the site-specific shutdown command procedure SSL3$COM:SSL3$SYSHUTDOWN.COM. This command procedure will be invoked by SYS$STARTUP:SSL3$SHUTDOWN.COM. - Copy any manual changes done to the OpenSSL configuration files SSL$ROOT:[000000]OPENSSL.CNF, SSL1$ROOT:[000000]OPENSSL.CNF or SSL111$ROOT:[000000]OPENSSL.CNF to SSL3$ROOT:[000000]OPENSSL.CNF. - Copy any manual changes done to the OpenSSL configuration files SSL$ROOT:[000000]OPENSSL-VMS.CNF, SSL1$ROOT:[000000]OPENSSL-VMS.CNF or SSL111$ROOT:[000000]OPENSSL-VMS.CNF to SSL3$ROOT:[000000]OPENSSL-VMS.CNF. - If any other of *.CNF files from previous releases are intended to be used with VSI SSL3 V3.0, insert ".pragma dollarid:on" statement as the first line in order to make the '$' sign without '{}' treated as usual character (not as substitution template) in VMS paths. - Migrate any SSL certificates store content to VSI SSL3 V3.0 by following the steps highlighted under "Migrate certificate store from VSI SSL V1.4, VSI SSL1 or VSI SSL111 to VSI SSL3 V3.0" to SSL3 V3.0". SSL3 Symbols -------------- SSL3 foreign symbols are defined with the SSL3 command procedure SSL3$COM:SSL3$UTILS.COM as follows: $ @SSL3$COM:SSL3$UTILS.COM Installation Verification Procedure (IVP) ----------------------------------------- The base installation verification procedure checks for presence of all the required files and logical names. The procedure also initiates the executable image to check if shareable images are accessible. Normally the base Installation Verification Procedure (IVP) is executed when SSL3 is installed. To run the SSL3 base IVP manually, type the following command: $ @SYS$TEST:SSL3$IVP.COM Note that the IVP would not be executed at installation time if the PCSI qualifier /NOTEST was utilized. Meanwhile, the directory [SSL3.TEST] additionally contains the binary tests pack that verifies the most common algorithms and interfaces. The tests can be run manually as part of the post-installation procedure via: $ @SSL3$ROOT:[TEST]SSL3$TESTS.COM The extended IVP should take a few minutes to run, depending on the processor speed. Removing SSL3 --------------- To remove SSL3 from the system disk or destination directory, type the following command: $ PRODUCT REMOVE SSL3 Note that some files may remain and will not be removed when the VSI SSL3 product is removed. These are generated files such as SSL3$IVP.LOG that gets created by running the IVP test program and other files such as certificates that have been created in the SSL3$CERTS directory. Migrate certificate store from VSI SSL V1.4, VSI SSL1 or VSI SSL111 V1.1 ------------------------------------------------------------------------ to VSI SSL3 V3.0: ---------------- - The top level directory structure of VSI SSL3 V3.0 is modified to SYS$SYSDEVICE:[VMS$COMMON.SSL3] from SYS$SYSDEVICE:[VMS$COMMON.SSL], SYS$SYSDEVICE:[VMS$COMMON.SSL1] or SYS$SYSDEVICE:[VMS$COMMON.SSL111] (Which are the top level directories for VSI SSL 1.4, VSI SSL1 and VSI SSL111 V1.1 respectively). In case there is a certificate store manually created in SYS$SYSDEVICE:[VMS$COMMON.SSL.DEMOCA...], SYS$SYSDEVICE:[VMS$COMMON.SSL1.DEMOCA...] or SYS$SYSDEVICE:[VMS$COMMON.SSL111.DEMOCA...], copy the certificate store to SYS$SYSDEVICE:[VMS$COMMON.SSL3.DEMOCA...]. - In a certificate store, the certificate files will have names of the form "hash.0" or will have symbolic links to names of this form (where "hash" is the hashed certificate subject name; see the -hash option of the openssl x509 utility). From VSI SSL V1.4 or VSI SSL1 to VSI SSL3 V3.0, this hash is modified from the MD5 to the SHA-1 algorithm. Due to this modification, validation of certificates will fail with SSL3 if we use the same hash names. Manually rename the certificate file name to use the new hash. An example of moving a certificate from VSI SSL V1.4 to VSI SSL3 V3.0 is as follows: a) Assume we have VSI SSL V1.4 installed and had created a certificate store in SSL$ROOT:[DEMOCA.CERTS]. b) Assume we have a certificate file 438F16D6.0 in SSL$ROOT:[DEMOCA.CERTS]. The name "438F16D6" of this certificate file is the MD5 hash of the certificate subject. $ @SSL$COM:SSL$UTILS $ openssl x509 -hash -in SSL$ROOT:[DEMOCA.CERTS]438F16D6.0 438F16D6 -----BEGIN CERTIFICATE----- MIIB9zCCAWACCQC1TifkDidaxTANBgkqhkiG9w0BAQUFADBAMQswCQYDVQQGEwJV UzELMAkGA1UECgwCSFAxDTALBgNVBAsMBFNUU0QxFTATBgNVBAMMDENBIEF1dGhv cml0eTAeFw0xNTExMjYyMTI3NThaFw0yMDExMjQyMTI3NThaMEAxCzAJBgNVBAYT AlVTMQswCQYDVQQKDAJIUDENMAsGA1UECwwEU1RTRDEVMBMGA1UEAwwMQ0EgQXV0 aG9yaXR5MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC3v+0ecrW2nbQ7ASwe 6hNeCPyixt6FdqnADVTVAws7TG70JFtVPK6pbc81grwJZPbJn1oAxTGMLLiANr/Y XPlU73OUG+rrSiirq5fhWjVrD6M+yK9XHo6qnjMVUuwXITc8Sxr1xzDb/nOBX1+L qkzGIX/4hvc4ko4OZ8mhKkEauwIDAQABMA0GCSqGSIb3DQEBBQUAA4GBAJetkXxW YSi/crNHg+vSPiK1QA/KwLKDSNFDNazyvM9toswa9yA6U6ZBal0WCTj9efOi8Rbd l1AH7HEUXUTccIrjlzOVsO4safWGt/wpyHNMZGAxA25Dd8fQbf9GpAvooaSPrdJU u23fgeoXF3GcLYd/hog/yhpOq1w+BsA+nVi+ -----END CERTIFICATE----- $ b) Now after installing VSI SSL3 V3.0, executing the "openssl x509 -hash" command from SSL3 gives "37d8de08" which is a SHA-1 hash of the certificate subject. $ @SSL3$COM:SSL3$UTILS $ openssl x509 -hash -in SSL$ROOT:[DEMOCA.CERTS]438F16D6.0 37d8de08 -----BEGIN CERTIFICATE----- MIIB9zCCAWACCQC1TifkDidaxTANBgkqhkiG9w0BAQUFADBAMQswCQYDVQQGEwJV UzELMAkGA1UECgwCSFAxDTALBgNVBAsMBFNUU0QxFTATBgNVBAMMDENBIEF1dGhv cml0eTAeFw0xNTExMjYyMTI3NThaFw0yMDExMjQyMTI3NThaMEAxCzAJBgNVBAYT AlVTMQswCQYDVQQKDAJIUDENMAsGA1UECwwEU1RTRDEVMBMGA1UEAwwMQ0EgQXV0 aG9yaXR5MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC3v+0ecrW2nbQ7ASwe 6hNeCPyixt6FdqnADVTVAws7TG70JFtVPK6pbc81grwJZPbJn1oAxTGMLLiANr/Y XPlU73OUG+rrSiirq5fhWjVrD6M+yK9XHo6qnjMVUuwXITc8Sxr1xzDb/nOBX1+L qkzGIX/4hvc4ko4OZ8mhKkEauwIDAQABMA0GCSqGSIb3DQEBBQUAA4GBAJetkXxW YSi/crNHg+vSPiK1QA/KwLKDSNFDNazyvM9toswa9yA6U6ZBal0WCTj9efOi8Rbd l1AH7HEUXUTccIrjlzOVsO4safWGt/wpyHNMZGAxA25Dd8fQbf9GpAvooaSPrdJU u23fgeoXF3GcLYd/hog/yhpOq1w+BsA+nVi+ -----END CERTIFICATE----- $ c) You will have to use a certificate file name having "37d8de08" if you wish to use this certificate store with VSI SSL3 V3.0: $ COPY SSL$ROOT:[DEMOCA.CERTS]438F16D6.0 - SSL3$ROOT:[DEMOCA.CERTS]37d8de08.0 OR $ openssl x509 -hash -in SSL$ROOT:[DEMOCA.CERTS]438F16D6.0 -out SSL3$ROOT:[DEMOCA.CERTS]37d8de08.0 (Here we are assuming that SSL3$ROOT:[DEMOCA.CERTS] is the new certificate store directory used with VSI SSL3 V3.0) d) Repeat steps b) and c) for all certificates in the certificate store. e) Certificate verification (using either the "openssl verify" command or verifying the certificate using OpenSSL API's) will work with VSI SSL3 V3.0, only if (for the above example) the certificate name in the certificate store is "37d8de08.0" f) Once you have stopped using the VSI SSL V1.4 certificate store you can delete the older certificate files having MD-5 hash file names. - For more information, see help on openssl x509 -hash, -subject, -subject_hash_old, -issuer, -issuer_hash_old option - https://www.openssl.org/docs/man3.0/man1/x509.html openssl verify -CApath option - https://www.openssl.org/docs/man3.0/man1/openssl-verify.html