VSI SSL3 for OpenVMS

This section lists hardware and software requirements for VSI SSL3 for OpenVMS Version 3.0-13:

Documentation for the OpenSSL project and the Open Group is available at http://www.openssl.org.

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

All logical names associated with VSI SSL3 V3.0 are prefixed with "SSL3$". The following is a comparison of system-level logical names that are defined for VSI SSL V1.4 and VSI SSL3 V3.0 (a similar comparison can be made between SSL3 and SSL111):

These logical names get defined by invoking SYS$STARTUP:SSL$STARTUP.COM and SYS$STARTUP:SSL3$STARTUP.COM startup command procedures respectively.

The logical name OPENSSL is mainly used to identify the OpenSSL header file location for building a product against OpenSSL. When VSI SSL V1.4, VSI SSL1, VSI SSL111 V1.1, and VSI SSL3 V3.0 versions co-exist, the OPENSSL logical name will be pointed to the version of product that was started last.

If there are any custom command procedures on your system that use the "SSL$...", "SSL1$...", or "SSL111$..." logical names, ensure that they are modified to use the "SSL3$..." logical names when migrating from VSI SSL V1.4, VSI SSL1, or VSI SSL111 V1.1 to VSI SSL3 V3.0.

The top level directory structure for VSI SSL3 V3.0 is SYS$SYSDEVICE:[VMS$COMMON.SSL3]. The top level directory structures for VSI SSL V1.4, VSI SSL1, and VSI SSL111 V1.1 (if installed) remain as SYS$SYSDEVICE:[VMS$COMMON.SSL], SYS$SYSDEVICE:[VMS$COMMON.SSL1], and SYS$SYSDEVICE:[VMS$COMMON.SSL111] respectively.

VSI SSL3 V3.0 example programs are located in SYS$COMMON:[SYSHLP.EXAMPLES.SSL3] directory.

If there are any custom command procedures on your system that reference the [SSL], [SSL1], or [SSL111] directories, ensure that they are modified to use the new [SSL3] directory when migrating from VSI SSL V1.4, VSI SSL1, or VSI SSL111 V1.1 to VSI SSL3 V3.0.

The relevant command procedure names are prefixed with SSL3 for the VSI SSL3 V3.0 product. For example:

• SYS$STARTUP:SSL3$STARTUP.COM
• SSL3$COM:SSL3$CERT_TOOL.COM

Command procedures for VSI SSL V1.4, VSI SSL1 and VSI SSL111 V1.1 are prefixed with SSL, SSL1, and SSL111 respectively.

If there are any custom command procedures on your system invoking the "SSL$...", "SSL1$...", or "SSL111$..." command procedures, ensure that they are modified to invoke "SSL3$..." command procedures when migrating from VSI SSL V1.4, VSI SSL1, or VSI SSL111 V1.1 to VSI SSL3 V3.0.

Library names for VSI SSL3 V3.0 are prefixed with SSL3$ as follows:

• SYS$SHARE:SSL3$LIBSSL_SHR.EXE
• SYS$SHARE:SSL3$LIBCRYPTO_SHR.EXE
• SYS$SHARE:SSL3$LIBSSL_SHR32.EXE
• SYS$SHARE:SSL3$LIBCRYPTO_SHR32.EXE

Library names for VSI SSL V1.4, VSI SSL1 and VSI SSL111 V1.1 remain unchanged:

• SYS$SHARE:SSL$LIBSSL_SHR.EXE
• SYS$SHARE:SSL$LIBCRYPTO_SHR.EXE
• SYS$SHARE:SSL$LIBSSL_SHR32.EXE
• SYS$SHARE:SSL$LIBCRYPTO_SHR32.EXE

• SYS$SHARE:SSL1$LIBSSL_SHR.EXE
• SYS$SHARE:SSL1$LIBCRYPTO_SHR.EXE
• SYS$SHARE:SSL1$LIBSSL_SHR32.EXE
• SYS$SHARE:SSL1$LIBCRYPTO_SHR32.EXE

• SYS$SHARE:SSL111$LIBSSL_SHR.EXE
• SYS$SHARE:SSL111$LIBCRYPTO_SHR.EXE
• SYS$SHARE:SSL111$LIBSSL_SHR32.EXE
• SYS$SHARE:SSL111$LIBCRYPTO_SHR32.EXE

Applications that are linked with VSI SSL V1.4, VSI SSL1 or VSI SSL111 V1.1 will continue using VSI SSL V1.4, VSI SSL1 or VSI SSL111 V1.1 libraries and applications that are linked with VSI SSL3 V3.0 product will use the new libraries shipped with VSI SSL3 product.

The logical name "OPENSSL" is used commonly by VSI SSL3 V3.0, VSI SSL111 V1.1, VSI SSL1, and VSI SSL V1.4. Care must therefore be taken to identify that this logical name is defined to the appropriate path (SSL3$INCLUDE:, SSL111$INCLUDE:, SSL1$INCLUDE: or SSL$INCLUDE:) before rebuilding applications.

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. To avoid this, 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:

For more information, refer to https://www.openssl.org/docs/man3.0/man1/x509.html and https://www.openssl.org/docs/man3.0/man1/openssl-verify.html

All logical names associated with VSI SSL3 V3.0 are prefixed with SSL3$. The following is a comparison of system-level logical names that are defined for VSI SSL111 V1.1 and VSI SSL3 V3.0:

VSI SSL111 V1.1.1M Logicals                             VSI SSL3 V3.0-13 Logicals

"OPENSSL" = "SSL111$INCLUDE:"                           "OPENSSL" = "SSL3$INCLUDE:"
"SSL111$CERT" = "SSL111$ROOT:[DEMOCA.CERTS]"            "SSL3$CERT" = "SSL3$ROOT:[DEMOCA.CERTS]"
"SSL111$CERTS" = "SSL111$ROOT:[DEMOCA.CERTS]"           "SSL3$CERTS" = "SSL3$ROOT:[DEMOCA.CERTS]"
"SSL111$COM" = "SSL111$ROOT:[COM]"                      "SSL3$COM" = "SSL3$ROOT:[COM]"
"SSL111$CONF" = "SSL111$ROOT:[DEMOCA.CONF]"             "SSL3$CONF" = "SSL3$ROOT:[DEMOCA.CONF]"
"SSL111$CRL" = "SSL111$ROOT:[DEMOCA.CRL]"               "SSL3$CRL" = "SSL3$ROOT:[DEMOCA.CRL]"
"SSL111$EXAMPLES" =                                     "SSL3$EXAMPLES" = 
        "SYS$COMMON:[SYSHLP.EXAMPLES.SSL]"                      "SYS$COMMON:[SYSHLP.EXAMPLES.SSL3]"
"SSL111$EXE" = "SSL111$ROOT:[X86_64_EXE]"               "SSL3$EXE" = "SSL3$ROOT:[X86_64_EXE]"
"SSL111$INCLUDE" = "SSL111$ROOT:[INCLUDE]"              "SSL3$INCLUDE" = "SSL3$ROOT:[INCLUDE]"
"SSL111$KEY" = "SSL111$ROOT:[DEMOCA.CERTS]"             "SSL3$KEY" = "SSL3$ROOT:[DEMOCA.CERTS]"
"SSL111$KEYS" = "SSL111$ROOT:[DEMOCA.CERTS]"            "SSL3$KEYS" = "SSL3$ROOT:[DEMOCA.CERTS]"
"SSL111$LIB" = "SSL111$ROOT:[LIB]"                      "SSL3$LIB" = "SSL3$ROOT:[LIB]"
                                                        "SSL3$MODULES" = "SSL3$ROOT:[MODULES]"
"SSL111$PRIVATE" = "SSL111$ROOT:[DEMOCA.PRIVATE]"       "SSL3$PRIVATE" = "SSL3$ROOT:[DEMOCA.PRIVATE]"
"SSL111$ROOT" = "SYS$SYSDEVICE:[VMS$COMMON.SSL.]"       "SSL3$ROOT" = "SYS$SYSDEVICE:[VMS$COMMON.SSL3.]"

These logical names get defined by invoking SYS$STARTUP:SSL111$STARTUP.COM and SYS$STARTUP:SSL3$STARTUP.COM startup command procedures respectively.

The logical name OPENSSL is mainly used to identify the OpenSSL header file location for building a product against OpenSSL. When VSI SSL3 V3.0 and VSI SSL111 V1.1 versions co-exist, the OPENSSL logical name will point to the version of product that was started last.

If there are any custom command procedures on your system that use the SSL111$... logical names, ensure that they are modified to use the SSL3$... logical names when migrating from VSI SSL111 V1.1 to VSI SSL3 V3.0.

The top level directory structure for VSI SSL3 V3.0 is SYS$SYSDEVICE:[VMS$COMMON.SSL3]. The top level directory structures for VSI SSL111 V1.1 (if installed) remain as SYS$SYSDEVICE:[VMS$COMMON.SSL111].

VSI SSL3 V3.0 example programs are located in the SYS$COMMON:[SYSHLP.EXAMPLES.SSL3] directory.

If there are any custom command procedure files on your system that reference the [SSL111] directories, ensure that they are modified to use the new [SSL3] directory when migrating from VSI SSL111 V1.1 to VSI SSL3 V3.0.

The names of the command procedures relevant for VSI SSL3 V3.0 are prefixed with SSL3, for example:

• SYS$STARTUP:SSL3$STARTUP.COM
• SSL3$COM:SSL3$CERT_TOOL.COM

The names of the command procedures relevant for VSI SSL111 V1.1 are prefixed with SSL111.

If there are any custom command procedure files on your system that invoke the SSL111$... command procedures, ensure that they are modified to invoke the SSL3$... command procedures when migrating from VSI SSL111 V1.1 to VSI SSL3 V3.0.

Library names for VSI SSL3 V3.0 are prefixed with SSL3$ as follows:

• SYS$SHARE:SSL3$LIBSSL_SHR.EXE
• SYS$SHARE:SSL3$LIBCRYPTO_SHR.EXE
• SYS$SHARE:SSL3$LIBSSL_SHR32.EXE
• SYS$SHARE:SSL3$LIBCRYPTO_SHR32.EXE

Library names for VSI SSL111 V1.1 remain unchanged:

• SYS$SHARE:SSL111$LIBSSL_SHR.EXE
• SYS$SHARE:SSL111$LIBCRYPTO_SHR.EXE
• SYS$SHARE:SSL111$LIBSSL_SHR32.EXE
• SYS$SHARE:SSL111$LIBCRYPTO_SHR32.EXE

Applications that are linked with VSI SSL111 V1.1 will continue using VSI SSL111 V1.1 libraries and applications that are linked with VSI SSL3 V3.0 product will use the new libraries shipped with VSI SSL3 product.

The logical name OPENSSL is used commonly by VSI SSL3 V3.0 and VSI SSL111 V1.1. Care must therefore be taken to identify that this logical name is defined to the appropriate path (SSL3$INCLUDE: or SSL111$INCLUDE:) before rebuilding applications.

The top level directory structure of VSI SSL3 V3.0 is modified to SYS$SYSDEVICE:[VMS$COMMON.SSL3] from SYS$SYSDEVICE:[VMS$COMMON.SSL111], which is the top level directory for VSI SSL111 V1.1).

In case there is a certificate store manually created in 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).

VSI SSL3 V3.0 for OpenVMS is based on the 3.0.13 base-level of the OpenSSL release. Some of the OpenSSL API, data structures, and commands have changed from the previous VSI SSL111 V1.1 product versions.

VSI cannot guarantee the backward compatibility of VSI SSL3 V3.0 with VSI SSL111 V1.1.

Applications will have to be recompiled and re-linked in order to make use of the latest VSI SSL3 V3.0 header files and shareable images.

Note that the VSI SSL3 shareable images names are different from VSI SSL111 V1.1.

VSI SSL 3.0-13 for OpenVMS x86-64 supports a FIPS module based on the Open-Source OpenSSL 3.0 FIPS module – /docs/man3.0/man7/fips_module.html. Note that the FIPS module is not enabled by default, so applications using OpenSSL 3.0.13 are not forced to use only FIPS-compliant algorithms, and all applications using SSL 3.0.13 should run without any errors. However, it is possible that some applications may fail if the FIPS module is enabled; any such applications will need to include support for FIPS-compliant algorithms to operate correctly with the FIPS module enabled.

To enable the FIPS module and force all applications to use only FIPS-compliant algorithms, the FIPS module configuration file named SSL3$ROOT:[000000]FIPSMODULE.CNF_AUTOGEN should be generated (as it is not generated automatically during system installation) and the OPENSSL_CONF logical name should be defined to point to a pre-made OpenSSL configuration file named SSL3$ROOT:[000000]OPENSSL-FIPS.CNF. To do so, the following commands can be used:

$ MCR SSL3$EXE:OPENSSL fipsinstall -out -
_$ "SSL3$ROOT:[000000]FIPSMODULE.CNF_AUTOGEN" -module SSL3$MODULES:FIPS.EXE
$ DEFINE OPENSSL_CONF SSL3$ROOT:[000000]OPENSSL-FIPS.CNF

Preserving configuration files is not necessary when you perform a regular upgrade or reinstallation of VSI SSL3 using the PRODUCT INSTALL command. However, if you intend to uninstall VSI SSL3 and wish to preserve any modifications to the VSI SSL3 configuration files you should back up these files to a different disk or directory before you enter PRODUCT REMOVE to remove the VSI SSL3 kit. If you do not create a backup, any changes you made to OPENSSL-VMS.CNF and OPENSSL.CNF will be lost.

When you have completed the reinstallation of VSI SSL3, move the saved items back into the VSI SSL3 directory structure.

The configuration files included in the VSI SSL3 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 VSI SSL3 for OpenVMS.

If you are upgrading from a previous version of VSI SSL3, after you install the VSI SSL3 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 a VSI SSL3 for OpenVMS kit, both the .CNF_TEMPLATE and .CNF files are provided.

The option to install to a location other than the system disk is no longer available. If you download VSI SSL3 and install it as a layered product, it must be installed on the system disk.

Before installing VSI SSL3 to a common system disk in a cluster, you must first shutdown VSI SSL3 by entering the following command on each node in the cluster:

$ @SYS$STARTUP:SSL3$SHUTDOWN

Shutting down VSI SSL3 deassigns logical names and removes installed shareable images that may interfere with the installation.

After the installation is complete, start VSI SSL3 by entering the following command on each node in the cluster:

$ @SYS$STARTUP:SSL3$STARTUP

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

The OpenSSL command line utility command version includes the VSI SSL3 for OpenVMS version. The OpenSSL version command displays output similar to the following:

OpenSSL> version
OpenSSL 3.0.13 xx xxx xxxx (Library: OpenSSL 3.0.13 xx xxx xxxx)
SSL3 for OpenVMS V3.0(xx) xxx xx xxxx (Library: SSL3 for OpenVMS V3.0(xx) xxx xx xxxx)

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.

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.

Generally, the OpenSSL environmental variables can exist in one of two formats: $var or ${var}

In order for these variables to be parsed properly and not be confused with logical names, VSI SSL3 for OpenVMS only accepts the ${var} format. Additionally, *.CNF files must contain .pragma dollarid:on, which allows using of dollar sign in variable names.

The IDEA, RC5, and MDC2 symmetric cipher algorithms are not provided. These algorithms are under copyright protection, and VSI does not have the right to use these algorithms.

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.

The documentation on the OpenSSL website is located at https://www.openssl.org/docs/. 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.

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.

To install the VSI SSL3 V3.0 for OpenVMS kit, enter the following command:

$ PRODUCT INSTALL SSL3

You will see an output similar to the following:

Performing product kit validation of signed kits ...
%PCSI-I-CANNOTVAL, cannot validate $1$DGA85:[username.ReleaseBuilds.SSL3.3013.X86.X86KIT]VSI-X86VMS-SSL3-V0300-13-1.PCSI$COMPRESSED;1
-PCSI-I-NOTSIGNED, product kit is not signed and therefore has no manifest file
The following product has been selected:
    VSI X86VMS SSL3 V3.0-13                Layered Product [Installed]
Do you want to continue? [YES]

Answer YES (the default option) to the Do you want to continue? prompt to start the installation.

During the installation, you will be asked to choose the installation options for the product. The output that you will see on your screen will be similar to the following:

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.
Configuring VSI X86VMS SSL3 V3.0-13: SSL3 for OpenVMS X86-64 V3.0-13 (Based on OpenSSL 3.0.13)
    Copyright 2024 VMS Software, Inc.
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:
    VSI X86VMS SSL3 V3.0-13                DISK$V921_EOWYN:[VMS$COMMON.]
Portion done: 0%...30%...60%...70%...80%...90%...100%
The following product has been installed:
    VSI X86VMS SSL3 V3.0-13                Layered Product
%PCSI-I-IVPEXECUTE, executing test procedure for VSI X86VMS SSL3 V3.0-13 ...
%PCSI-I-IVPSUCCESS, test procedure completed successfully
VSI X86VMS SSL3 V3.0-13: SSL3 for OpenVMS X86-64 V3.0-13 (Based on OpenSSL 3.0.13)
    Insert the following lines in SYS$MANAGER:SYSTARTUP_VMS.COM:
        @SYS$STARTUP:SSL3$STARTUP.COM
    Insert the following lines in SYS$MANAGER:SYSHUTDWN.COM:
        @SYS$STARTUP:SSL3$SHUTDOWN.COM
    Review the Installation Guide and Release Notes for post install directions.
    Review the Installation Guide and Release Notes for post upgrade verification suggestions.
    Refer to SYS$HELP:SSL30-13-X86.RELEASE_NOTES for more information.

You can stop the installation procedure at any moment by pressing Ctrl/Y. Note, however, that before restarting the installation, you will have to manually reverse any changes to the system that occurred during the aborted installation. To do that, enter the following command:

$ PRODUCT REMOVE SSL3

After all traces of SSL3 have been removed, start the installation as described in Section 5, “Installing VSI SSL3 for OpenVMS”.

After the installation is complete, perform the tasks described in this section to fully configure VSI SSL3.

The VSI SSL3 features the following directory structure:

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:SSL3$LIBSSL_SHR/SHARE
SYS$SHARE:SSL3$LIBCRYPTO_SHR/SHARE

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:SSL3$LIBSSL_SHR32/SHARE
SYS$SHARE:SSL3$LIBCRYPTO_SHR32/SHARE