May 24 ’13

Using OpenSSL to Strengthen the Security of Your z/VSE Environment and Communications

by Joerg Schmidbauer in Enterprise Tech Journal

The ability to port OpenSSL to z/VSE is beneficial to IBM customers and vendors. This article reviews those benefits and offers insight on:

• How OpenSSL on z/VSE is both similar to and different from OpenSSL on other platforms
• What’s involved in creating random numbers and keystores
• How the IPv6/VSE product from IBM/Barnard Software, Inc. (BSI) uses OpenSSL to support the Secure Sockets Layer (SSL) for applications. 

Why Port OpenSSL to z/VSE?

Written in C and available for many operating systems and hardware platforms, OpenSSL is an open source project providing an SSL implementation and key management utilities. You can learn more at Porting OpenSSL to z/VSE:

• Provides SSL for those IP stacks that currently don’t have an SSL implementation—IPv6/VSE and Linux Fast Path (LFP)
• Means that vendors already providing SSL for their stack can now give their customers another alternative such as TCP/IP for VSE/ESA.

On z/VSE 5.1, OpenSSL is part of a new system component, VSE CryptoServices 5686-CF9-17, CLC=51S. It’s installed in PRD1.BASE and includes:

• IJBSSL phase, which is the OpenSSL implementation
• SPEEDTST phase, which invokes the built-in OpenSSL speed test
• NOTICES.Z, which provides license information
• IJBSLVSE.OBJ, which provides access to the Application Program Interfaces (APIs) and must be linked to your application
• IJBSSL.H, which provides function prototypes.

What’s Unique on z/VSE?

Two unique features are available only on z/VSE:

• A z/OS-compatible SSL API. This is described in z/OS Cryptographic Services, SSL Programming (SC24-5901). All existing SSL applications on z/VSE, such as CICS Web Support, VSE Connector Server and WebSphere MQ for z/VSE, can use this feature. Wrapping the native OpenSSL functions with the z/OS SSL API lets existing z/VSE SSL applications run unchanged with OpenSSL.
• Support for IBM System z cryptographic hardware.

Although OpenSSL can perform all encryption algorithms with all key lengths in software, performance is dramatically improved by using hardware cryptographic support. Moreover, hardware functionality can be used that isn’t available in software, such as hardware-based generation of random numbers.    

Creating Random Numbers

Creating random numbers is a sensitive task in every crypto system. In OpenSSL, there are various source modules that use platform-dependent functionality for providing random numbers for all supported operating systems. A new source module for VSE uses the API phase IJBCRLIB to obtain random bytes. The Encryption Facility for z/VSE also uses this function to create encryption keys.

Phase IJBCRLIB is responsible for ensuring the best possible random number generator available on the given hardware is used. With z/VSE 5.1, you can get random numbers using:

• A crypto coprocessor card (CEX2C, CEX3C or CEX4C), which is the best possibility because a crypto card returns true random numbers independent of any seed value.
• The CP Assist for Cryptographic Functions (CPACF)-provided Pseudo Random Number Generator (PRNG), which needs a seed value; this seed can be obtained from various sources of randomness in the system. The PRNG function is available on System z10 and later.
• A pure software-based random number generator in case the first two alternatives aren’t available.

Run-Time Variables

Two variables control how OpenSSL behaves on z/VSE. You can turn crypto hardware on and off via parameter SSL$ICA:

// SETPARM SSL$ICA = [ ‘YES’ | ‘NO’ ]

You can control the debug trace via variable SSL$DBG:

// SETPARM SSL$DBG = [ ‘YES’ | ‘NO’ ]

Creating Keystores

OpenSSL uses the Privacy-Enhanced Mail (PEM) format to store keys and certificates. PEM files may contain an RSA key pair, an SSL certificate or both, and may or may not be password-protected. While other keystore formats are just binary, the PEM file content is base-64 encoded.

You can create a PEM file containing an RSA key pair with OpenSSL-Light on Windows using the following code:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mykey.pem
-out myreq.pem

The –nodes parameter stands for “no DES encryption” and allows you to create the PEM file without a password. While OpenSSL on z/VSE supports password-protected PEM keystores, they aren’t currently exploited by any vendor.

The created certificate request must be signed by a Certificate Authority (CA) to obtain an SSL certificate. For testing purposes, this signing can occur with the Keyman/VSE utility you can download free from the z/VSE homepage.

Converting Keystores Between Different Formats

Sometimes, you will need to convert a given keystore into another format. For example:

• Using SSL client authentication and an SSL client requires a different keystore format than PEM.
• The VSE Connector Client requires a Public-Key Cryptography Standards version 12 (PKCS-12) file (PFX) or Java Key Store (JKS) keystore
• Web browser clients are usually able to import PFX files into their internal keystores.

You can use OpenSSL on a workstation platform to convert PEM to PFX and vice versa. Here’s an example of converting a PEM file into a PFX file:

openssl pkcs12 -export -out mycert.pfx -in mycert.pem

Uploading a Keystore to z/VSE

After creating the PEM file, you must upload it to z/VSE with ASCII-to-EBCDIC translation, either as a VSE library member or as a VSAM file.

When creating the PEM file on Windows, there’s a problem with the line-end characters. The openssl.exe creates UNIX-style line breaks just with “line-feed” (hex 0A). Windows normally uses Carriage-Return/Line-Feed (CRLF) (hex 0D0A). You can fix this easily by editing the file using the Wordpad editor and saving it to disk without any further changes. Wordpad will save the file with correct line endings.

Note: In addition to PFX and JKS files, the Keyman/VSE utility will be updated to support the PEM keystore format. This will greatly simplify the process of creating and uploading PEM files, as you will no longer need to have OpenSSL installed on your workstation. Check out the VSE Connectors download page at for the latest information.

Figure 1 shows a PEM file stored in a VSAM file.

How Is OpenSSL Exploited on z/VSE?

The IPv6/VSE product from BSI is among the first to exploit OpenSSL on z/VSE. You can license IPv6/VSE via IBM or directly from BSI. The BSI stack includes two servers, providing SSL for VSE server and client applications. These servers provide SSL/TLS transparently to the application. They support both batch and CICS applications written in any supported API, including applications using the ASM SOCKET macro, EZASMI, EZASOKET and LE/C APIs:

• SSL Proxy Server (BSTTPRXY) is a simple proxy server that allows only a single PROXY command. To proxy multiple connections, you must run multiple BSTTPRXY partitions. BSTTPRXY performs IPv4-to-IPv6 or IPv6-to-IPv4 translation.
• AT-TLS Server (BSTTATLS). Automatic Transport Layer Security is a facility similar to the z/OS Application Transparent-Transport Layer Security (AT-TLS) facility. However, BSTTATLS does much more than BSTTPRXY. It allows many AT-TLS definitions and monitors incoming and outgoing connections, intercepting and converting sockets from clear text to SSL or vice versa as necessary. However, BSTTATLS won’t perform IPv4-to-IPv6 or IPv6-to-IPv4 translation.

So, there are advantages to each application. BSTTPRXY is a proxy server application while BSTTATLS is really an extension of the APIs to handle interception and conversion of sockets to or from SSL.

Figure 2 shows how the IPv6/VSE stack uses phase IJBSSL. In this example, the VSE Navigator connects to secure port 2894, where BSTTATLS converts the traffic into plain text and forwards it to port 2893, where the VSE Connector Server is listening.

Running the OpenSSL Speed Test

OpenSSL provides a built-in speed test that lets you check the speed of your system when performing cryptographic algorithms such as RSA, Advanced Encryption Standard (AES), Secure Hash Algorithm (SHA) or Data Encryption Standard (DES). On z/VSE, this test is included in phase IJBSSL and you can invoke it with Job Control Language (JCL) similar to this:


For a list of supported parameters, refer to the original OpenSSL documentation or simply enter the following command on a workstation with OpenSSL installed:

#openssl speed ?

Performance Test Results

We performed the OpenSSL speed test on a zEnterprise 196 (2817-729 51) with z/VSE 5.1 running in an LPAR and a Crypto Express3 coprocessor card installed.

Test results for CPACF show some overhead in hardware performance when using small blocks of data caused by internal initializations, but a huge performance boost when using data blocks with 1 KB or bigger. In this case, CPACF performs about 16 times faster than software (see Figure 3).

Crypto cards accelerate RSA operations that are part of each SSL handshake. This pays off when you have workloads with many SSL handshakes in a certain time interval; examples include secure FTP or secure Telnet sessions as well as secure Web browser connections to CICS Web Support. Because the RSA algorithm requires much more computational effort than AES, the performance increase is dramatically greater as shown for AES. RSA with a key length of 1,024 bits performed 40 to 60 times faster compared to software. This factor increases to 110 up to 120 for RSA-2048, and finally to more than 300 for RSA-4096 (see Figure 4).

These performance test results show that you shouldn’t rely on software-based encryption in a production environment. The overall crypto speed is greatly improved using hardware support while CPU cycles are much lower compared to software. Processor cycles on a crypto card aren’t counted for capacity measurement pricing.  

Required PTFs

Figure 5 shows the required PTFs for OpenSSL support on z/VSE 5.1.


As we’ve shown here, OpenSSL on z/VSE provides numerous functions and benefits. However, it currently lacks the following functionality in z/VSE 5.1:  

• The openssl command line tool isn’t available on z/VSE, so key management occurs on a workstation (Windows, Linux, etc.). Keystores are then uploaded to z/VSE.
• The IDEA, RC5 and MDC2 algorithms aren’t available for legal reasons (patent issues).
• Non-LE/C applications currently aren’t supported. Because OpenSSL is coded in C, an LE/C run-time environment is required for callers.


OpenSSL on z/VSE is a powerful resource that can help you strengthen the security of your z/VSE environment and communications. Try it, if you haven’t already, and follow the tips provided here to ensure successful implementation and use. A good place to start is by downloading the VSE Connector Client and Keyman/VSE at You can also learn more at these Websites:

• OpenSSL:
• BSI:
• VSE:

Acknowledgement: Special thanks to Jeff Barnard from Barnard Software, Inc. for his help in the development phase as well as for providing suggestions for coding in the GSK API layer, and for doing a great deal of testing.