Q: Where do I get OpenSSL Libraries from and how do I set them up for VA Smalltalk 8.6.2 and above?
Problem
Beginning with VA Smalltalk 8.6.2, a cryptographic feature is available alongside enhanced SSL/TLS support, both of which depend on the OpenSSL library. However, VA Smalltalk 8.6.2 and beyond will no longer ship with OpenSSL as part of the product.
Users not familiar with OpenSSL, and/or native library connectivity in VAST Platform / VA Smalltalk, might be left wondering where to get OpenSSL and how to set it up for use with VAST/ VA Smalltalk.
Solution
The recommended approach is to compile OpenSSL yourself. This allows you to configure your specific needs.
For Windows, you can download pre-built Open SSL from third party providers. For example, the following third parties have proved useful:
Ultimately, it is up to you to choose a vendor with whom you are comfortable.
For Linux, OpenSSL is usually available in the package management system of the Linux distribution.
The following are instructions on how to set up and configure OpenSSL for use with VA Smalltalk / VAST Platform. They serve as a starting point.
Support Level:
• VA Smalltalk 8.6.2 and above supports OpenSSL version 1.0.x. Anything below this version level is not just unsupported; it is known to be incompatible.
• VA Smalltalk 8.6.3 and above supports OpenSSL version 1.1.0.
• VA Smalltalk 9.1 and above supports OpenSSL version 1.1.1.
• VAST Platform 2022 and above supports OpenSSL version 3.0.
TLS support depends on the version of OpenSSL. For example, TLS 1.2 support started in 1.0.1 and 1.0.2. TLS 1.3 support started in 1.1.1 as you can read in Wikipedia:
OpenSSL.
Some background and a general description of what needs to be done to connect VAST Platform and VA Smalltalk to OpenSSL gets you comfortable with how this works, but the impatient may wish to skip down to the
setup of the specific platform sections.
Background
OpenSSL is an open-source implementation of the SSL/TLS protocols written in C and distributed as two shared libraries.
The first library is generally referred to as the cryptographic library and includes a rich set of cryptographic primitives. Examples of cryptographic primitives are message digests, symmetric ciphers, public/private key algorithms, and secure random number generators. This shared library is used by VAST/VA Smalltalk's Cryptographic Support feature.
For Windows:
This is named libeay32.dll for OpenSSL version <1.1.0 and libcrypto.dll for OpenSLL versions >= 1.1.0.
For Linux (UNIX):
This is named libcrypto.so.
The second library implements the SSL/TLS protocol used for secure digital communications, such as HTTPS, and depends on the functionality from the cryptographic library.
For Windows:
This is named ssleay32.dll for OpenSSL version <1.1.0 and libssl.dll for OpenSLL versions >= 1.1.0.
For Linux (UNIX):
This is named libssl.so.
Connecting VAST to OpenSSL
Before describing how to acquire and set up OpenSSL for a specific platform, consider how this connection is made, since the concepts are identical across all platforms.
VAST looks to the configuration file (i.e. abt.ini) to figure out how to form a connection with both the cryptographic and SSL/TLS libraries. Specifically, in the section called [PlatformLibrary Name Mappings] there are two entries of interest. The first one is called CRYPTO_LIB and should reference the name of the cryptographic library. The second one is SSL_LIB and should reference the name of the SSL/TLS library.
Notice that in a default installation of VAST, these names are already mapped. This means that if these libraries are located in your image directory, VAST's binary directory (i.e. where the abt executable lives) or any of the system's default library paths, then VAST will find it. An easy way to ensure this is the case is to make a copy of the cryptographic and SSL/TLS libraries and place them in VAST's Binary directory. This ensures you know exactly what library versions VAST will be using and requires no modifications to the abt.ini file.
In other situations, multiple versions of OpenSSL libraries may be installed on your system, and you may wish to reference a specific version. In this case you can map a platform library name to an absolute path. For example,
CRYPTO_LIB=/usr/lib/ssl/libcrypto.1.0.1.so
Warning:
Be sure that both SSL_LIB and CRYPTO_LIB are using the same version of the OpenSSL library. Undefined behavior (most likely a random crash) can occur if you set the CRYPTO_LIB=/usr/lib/ssl/libcrypto.1.0.1.so but then set SSL_LIB=/usr/lib/ssl/libssl.0.9.8.so.
Set up
This section describes how to 1) acquire OpenSSL for each platform and 2) set up VA Smalltalk / VAST Platform to connect to OpenSSL. The recommended way is summarized as follows:
• Acquire the OpenSSL cryptographic and SSL/TLS shared libraries. It must be OpenSSL version >= 1.0.0
i.e. libeay32.dll and ssleay32.dll on Windows if using OpenSSL version < 1.1.0
i.e. libcrypto.dll and libssl.dll on Windows if using OpenSSL version >= 1.1.0
i.e. libcrypto.so and libssl.so on Unix/Linux
• Copy both these libraries to VAST's Binary Directory
e.g., C:\Program Files (x86)\Instantiations\VA Smalltalk\8.6 on Windows
e.g., /usr/local/VASmalltalk/8.6/bin on Unix/Linux
• Make sure the library names match what is referenced in abt.ini.
For Linux (UNIX):
The version may appear as part of the name. In this case, discard the version in the abt.ini entry. For example, rename libcrypto.so.1.0.1 to libcrypto.so.
The .dll or .so extension is implied in the abt.ini, so it is sufficient if the abt.ini entry just says libcrypto.
Windows
Note:
VAST / VA Smalltalk 32-bit requires 32-bit OpenSSL libraries. VAST / VA Smalltalk 64-bit requires 64-bit OpenSSL libraries.
Example (VAST Platform 64-bit):
• This example relies on pre-built libraries.
• Acquire the libraries.
From a web browser, go to one of the
pre-built libraries or your own choice.
For this example,
Download the latest zip distribution for OpenSSLon Windows (64-bit libraries).
At the time of writing, this is openssl-3.6.1-win64.zip
• Unzip the downloaded file and copy libcrypto-3-x64.dll and libssl-3-x64.dll to VAST’s Binary Directory.
e.g., C:\Program Files\Instantiations\VASTPlatform\14.1.0x64
• Make sure the library names match what is referenced in abt.ini .
Ensure the following values are set in the abt.ini file:
CRYPTO_LIB=libcrypto-3-x64
SSL_LIB=libssl-3-x64
Linux
There are many different distributions of Linux making it difficult to provide the exact commands for downloading OpenSSL; however, the good news is that OpenSSL is readily available from the package management system of any given Linux distribution.
Note:
If you have a 64-bit Linux distribution and you are running VAST / VA Smalltalk 32-bit, you will need to specifically request that the OpenSSL 32-bit libraries be installed.
This is a common library issue on Linux with a package manager specific solution. The recommended approach is to perform a simple web search for installing OpenSSL on your specific flavor/bitness of Linux. Here are a few examples:
• (OpenSSL 32-bit on Ubuntu 32-bit) apt-get install openssl.
• (OpenSSL 32-bit on Ubuntu 64-bit) apt-get install openssl:i386.
• (OpenSSL 32-bit on Fedora 32/64-bit) dnf install openssl.i686 .
Assuming you have installed OpenSSL on your Linux distribution, the next step is to locate libcrypto and libssl. This step is necessary in order to copy them to the binary directory of VAST / VA Smalltalk. Again, since the locations of these libraries are going to be Linux distribution specific, it is difficult to say exactly where they are located. For example,
• on Fedora 22 32-bit, they are located in /usr/lib,
• on Ubuntu 15.04 64-bit, the 32-bit OpenSSL libraries are located in /lib/i386-linux-gnu.
The universal approach is to use the 'find' command starting at the root directory. For example, the following can be used across all Unix/Linux flavors to identify where libssl is located:
find / -name libssl* 2>/dev/null'
libcrypto should be in the same directory as libssl. Below is a complete example on Ubuntu 15.04 64-bit.
Example (VA Smalltalk 32-bit on Ubuntu 15.04 64-bit):
• Acquire the libraries.
Install the OpenSSL 32-bit library:
sudo apt-get install openssl:i386
• Copy the library to VA Smalltalk's Binary Directory
• Copy libcrypto.so.1.0.0 to VA Smalltalk's Binary Directory and rename the copy to libcrypto.so.
cp /lib/i386-linux-gnu/libcrypto.so.1.0.0 /usr/local/VASmalltalk/8.6/bin/libcrypto.so
• Copy libssl.so.1.0.0 to VA Smalltalk's Binary Directory and rename the copy to libssl.so.
cp /lib/i386-linux-gnu/libssl.so.1.0.0 /usr/local/VASmalltalk/8.6/bin/libssl.so
• Ensure the following values are set in the abt.ini file:
CRYPTO_LIB=libcrypto
SSL_LIB=libssl
Test connectivity
Once you have completed all the
steps, you can test VAST / VA Smalltalk's connectivity with OpenSSL by performing the following:
• Launch a VAST Image.
• Load the Socket Communications interface feature
From System Transcript -> Tools Menu -> Load/Unload Features...
Choose ST: Socket Communications Interface to be loaded and press Ok.
• Execute the following Smalltalk Code:
OSSslVersion printStatusCheck.
OSSslVersion printSslStatusCheck.
• Check the Transcript to see if any errors were reported. (Nothing is printed if everything is ok).
• Optionally, inspect the result of the following Smalltalk code to check what version of the OpenSSL libraries VAST is using:
OSSslVersion getLibraryVersion.
• Finally, try to fetch a URL. To do this, first load the z.ST: Server Smalltalk (SST) – HTTP feature.
'https://www.google.com' sstAsUrl fetch
Common Problems
• The abt.ini file does not accurately reflect the exact names of the shared libraries.
e.g.. Some Windows binaries name the shared libraries libcrypto-1_1.dll and libssl-1_1.dll instead of libcrypto.dll and libssl.dll. In this case, be sure that the name is accurately reflected in the .ini file like so:
CRYPTO_LIB=libcrypto-1_1
SSL_LIB=libssl-1_1
• Using precompiled OpenSSL binaries on Windows that link to Microsoft Visual Studio Runtime.
e.g., Some precompiled OpenSSL binaries on Windows have a dependency on versions of msvcrt.dll that you may not have installed on the system. In this case, the libraries will simply fail to load because of this missing dependency. Ensure that your system has the appropriate MSVC Runtime installed, if necessary.
OpenSSL deprecations and unsupported versions
OpenSSL defined a "Release Strategy" in which establishes how old versions get deprecated or unsupported. The full explanation with the latest update done in 7th January 2020 is defined here:
openssl.org policies release strategy. The relevant bits for VAST are:
• Version 1.0.2 is no longer supported. Extended support for 1.0.2 to gain access to security fixes for that version is available.
• Versions 1.1.0, 1.0.1, 1.0.0 and 0.9.8 are no longer supported.
That means that all those versions are no longer officially supported by OpenSSL. Official support starts with version 1.1.1 and beyond. You could potentially still use the "latest" release available for those branches, but it is at your own risk to use unsupported versions.
VA Smalltalk <= 8.x, does not support 1.1.1. That means you must upgrade to 9.x in order to have a supported OpenSSL version. If you are using 9.x, just be sure to be using version >= 1.1.1 of OpenSSL.
Trouble shooting
Sometimes it can be difficult to determine if the OpenSSL has been properly initialized:
• you may have specified libraries in your .ini file but they weren't found';
• you may not have specified a physical name in the .ini file for the libraries;
• for some reason, you may not even have the logical name in the .ini file.
New with VAST Platform 2021 (v10.0.0), you can display the configuration of CRYPTO_LIB and SSL_LIB by executing the Smalltalk expression:
EmSystemConfigurationDumper new dumpOn: Transcript.
The result of this expression below indicates success. Failures are indicated by the string "******** NON FOUND ********".
For Windows:
OpenSSL Crypto Lib:
CRYPTO_LIB mapped to: libeay32
CRYPTO_LIB Status Check Result: true
CRYPTO_LIB library version: 1.0.2u Release
CRYPTO_LIB loaded: Z:\Common\Dev\VAST\10.0.0x64\libeay32.DLL
OpenSSL SSL Lib:
SSL_LIB mapped to: ssleay32
SSL_LIB Status Check Result: true
SSL_LIB library version: 1.0.2u
SSL_LIB loaded: Z:\Common\Dev\VAST\10.0.0x64\ssleay32.DLL
For Linux (UNIX):
OpenSSL Crypto Lib:
CRYPTO_LIB mapped to: libcrypto
CRYPTO_LIB Status Check Result: true
CRYPTO_LIB library version: 1.1.1 Release
CRYPTO_LIB loaded: /usr/lib/i386-linux-gnu/libcrypto.so.1.1
OpenSSL SSL Lib:
SSL_LIB mapped to: libssl
SSL_LIB Status Check Result: true
SSL_LIB library version: ******** NON FOUND ********
SSL_LIB loaded: /usr/lib/i386-linux-gnu/libssl.so.1.1
(This is still a success, VAST has no way to get ssl version on Linux)