FAQ : Communications (TCP/IP, MQ, APPC, HLLAPI, CICS) : Q: Where do I get OpenSSL Libraries from and how do I set them up for VA Smalltalk 8.6.2 and above?
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 VA Smalltalk, might be left wondering where to get OpenSSL and how to set it up for use with VA Smalltalk.
Solution
The following are instructions on how to setup and configure OpenSSL for use with VA Smalltalk.
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:https://en.wikipedia.org/wiki/OpenSSL.
Some background and a general description of what needs to be done to connect 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 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 VA Smalltalk to OpenSSL
Before describing at how to acquire and setup OpenSSL for a specific platform, consider how this connection is made, since the concepts are identical across all platforms.
VA Smalltalk 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 VA Smalltalk, these names are already mapped. This means that if these libraries are located in your image directory, VA Smalltalk's binary directory (i.e. where the abt executable lives) or any of the system's default library paths, then VA Smalltalk 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 VA Smalltalk's Binary directory. This ensures you know exactly what library versions VA Smalltalk 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) setup VA Smalltalk 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 VA Smalltalk'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
Windows binaries can be found from links at the following location: https://www.openssl.org/community/binaries.html
Note:
VA Smalltalk 32-bit requires 32-bit OpenSSL libraries. VA Smalltalk 64-bit requires 64-bit OpenSSL libraries.
Example (VA Smalltalk 32-bit):
Acquire the libraries.
Click on the second link to: https://indy.fulgan.com/SSL/
Download the latest zip distribution for i386 (32-bit libraries).
At the time of writing, this is openssl-1.0.2d-i386-win32.zip
Unzip the downloaded file and copy libeay32.dll and ssleay32.dll to VA Smalltalk's Binary Directory.
e.g.. C:\Program Files (x86)\Instantiations\VA Smalltalk\8.6
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=libeay32
SSL_LIB=ssleay32
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 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 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 VA Smalltalk's connectivity with OpenSSL by performing the following:
Launch a VA Smalltalk Image
Load the Socket Communcations 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 VA Smalltalk 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: https://www.openssl.org/policies/releasestrat.html. The relevant bits for VA Smalltalk 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 supports 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 that 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 below result of this expression indicate success. Failures are indicated by the string "******** NON FOUND ********".
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
 
Linux:
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)
 
Last modified date: 04/26/2022