OpenSSL
This chapter describes the new z/VSE SSL support that is based on OpenSSL and the benefits for customers and vendors. It outlines the functional parts that are common among z/VSE and other platforms and shows the differences between them.
Special issues, such as creating random numbers and keystores, also are described. We also show how the IPv6/VSE product from IBM and Barnard Software, Inc., uses OpenSSL to provide network security for their applications.
This chapter includes the following topics:
5.1 Overview
OpenSSL is an open source project that provides an SSL implementation and key management utilities. OpenSSL is written in C and is available for many operating systems and hardware platforms.
OpenSSL is ported to z/VSE for several reasons. It provides SSL for those IP stacks that lack their own SSL implementation: IPv6/VSE and Linux Fast Path (LFP). Also, vendors that already are providing SSL for their stack can now offer their customers another alternative; for example, TCP/IP for VSE/ESA.
For more information about OpenSSL, see this website:
5.1.1 What is available on z/VSE
The following OpenSSL-based SSL runtime environment is provided since z/VSE 5.1 as part of a new system component:
VSE CryptoServices
5686-CF9-17
CLC=51S (z/VSE 5.1) or 52S (z/VSE 5.2)
The new z/VSE Cryptographic Services component is installed in PRD1.BASE and includes the following features:
•IJBSSL phase (the SSL runtime component, which is based on OpenSSL)
•SPEEDTST phase (starts the built-in OpenSSL speed test)
•NOTICES.Z (license information)
•IJBSLVSE.OBJ (provides access to the APIs and must be linked to your application)
•IJBSSL.H (provides function prototypes)
|
Notes: The initial OpenSSL version on z/VSE 5.1 was 1.0.0.d with APAR DY47397 (PTF UD53864).
An update is provided with APAR DY47472 (PTF UD53952), which removes RC4-based SSL cipher suites because of known security issues.
APAR DY47499 (PTF UD53983) was upgraded OpenSSL 1.0.1e.
Check the Security section on the VSE home page for further OpenSSL updates:
|
On z/VSE 5.1, OpenSSL on z/VSE requires being explicitly supported by an IP stack through linking the IJBSLVSE.OBJ to the stack code. This is done by the IPv6/VSE product from Barnard Software, Inc.
On z/VSE 5.2, OpenSSL on z/VSE can also be used transparently by using the new SSLPHASE parameter in the LE/C Multiplexer EDCTCPMC. Refer to section 5.7, “How OpenSSL is used on z/VSE” on page 173 for details about configuring the SSL phase.
5.1.2 What is unique in z/VSE
he following unique features are available only in z/VSE:
•A z/OS-compatible SSL programming interface
This API was described in z/OS Cryptographic Services, SSL Programming, SC24-5901 and was adapted for z/VSE in z/VSE TCP/IP Support, SC34-2640. It is used by all existing SSL applications on z/VSE, such as CICS Web Support, VSE Connector Server, and WebSphere MQ for z/VSE. Wrapping the native OpenSSL functions by this z/OS SSL API allows existing z/VSE SSL applications to 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 crypto support. Hardware functionality also can be used that is not available in software, such as hardware-based generation of random numbers.
5.1.3 Runtime variables
There are two variables for controlling the behavior of OpenSSL on z/VSE. The use of crypto hardware can be turned on and off by using the SSL$ICA parameter, as shown in the following example:
// SETPARM SSL$ICA = [ 'YES' | 'NO' ]
The debug trace can be controlled by using the SSL$DBG variable, as shown in the following example:
// SETPARM SSL$DBG = [ 'YES' | 'NO' ]
|
Note: These variables can be used only when the SSL application uses the GSK interface. This is the case for IPv6/VSE from Barnard Software, Inc.
|
5.1.4 What is not available in z/VSE
The following functions are not available in z/VSE 5.1:
•The OpenSSL command-line tool. Therefore, key management is done on a workstation (Windows, Linux, and so on). Created keystores are then uploaded to z/VSE. Keystores can be created by using OpenSSL on a workstation or by using the Keyman/VSE utility that can be downloaded from the z/VSE home page.
•Other command line-based functions, such as encryption of files and certificate verification. Encryption of z/VSE files and tapes is provided by Encryption Facility for z/VSE.
•Some algorithms are not available on z/VSE because of legal reasons: IDEA, RC5, MDC2.
•Non-LE/C applications. Because OpenSSL is coded in C, an LE/C-runtime environment is required for callers.
5.2 Access to the OpenSSL API
Because each VSE phase has only one main entry point that can be called after a CDLOAD, a special mechanism is established to provide access to the OpenSSL API functions.
The IJBSLVSE.OBJ file is provided for accessing the API functions in phase IJBSSL. Consider the following points when you are using this file:
•It must be linked to any OpenSSL application on VSE.
•It performs a CDLOAD of the IJBSSL phase.
•It provides access to OpenSSL functions by obtaining the function pointer by calling the OpenSSL main entry point with a specific function ID.
•Unfortunately, the list of callable functions cannot be dynamic; that is, each called function must be contained in the list. For a complete list, see “SSL APIs” on page 221.
A counterpart of IJBSLVSE is linked to phase IJBSSL. This counterpart implements the main entry point of IJBSSL and returns the function pointer of the requested OpenSSL API function by using fetchep().
Figure 5-1 shows how an IP stack accesses the OpenSSL API by using module IJBSLVSE.
Figure 5-1 Access to the OpenSSL API
The IP stack uses IJBSLVSE to access the native OpenSSL API or the IBM GSK API. Phase IJBSSL uses a low-level z/VSE crypto API that is provided by phase IJBCRLIB to perform cryptographic functions on hardware.
5.3 Creating random numbers
Creating random numbers is a sensitive task in every crypto system. There are various random number generators on the different hardware platforms and operating systems. In the following sections, we describe how OpenSSL creates random numbers on z/VSE and which z/VSE interfaces are used.
5.3.1 Characteristics of random number generators
An optimal random number generator has the following characteristics:
•Probability
Random numbers are independent of each other and all possible numbers have the same probability of being generated. That is, each bit of each number has the probability of 0.5 of being ‘1’ or ‘0’.
•Unpredictability
A sequence of numbers must not be predictable. Looking at any part of a random number sequence, no previously generated nor any number to be generated in future can be derived from this part.
•Performance
The generator should provide high output rates at low latency.
•Security
There must be no chance for any attacker to influence the generation process.
Random number generators can be placed into the following categories:
•Hardware-based generators
•Software-based generators
•A mixture of both
Hardware-based generators best fulfill all four requirements, primarily being unpredictable and secure. Software-based generators are deterministic and need some unpredictable seed value to create a sequence of numbers that is usually the same for a seed. Mixed generators try to overcome the disadvantages of pure software-based generators; however, they do not reach the unpredictability and security level of hardware-based generators.
For these reasons, hardware-based generators are often called true random number generators (TRNGs) and all other types are called pseudo random number generators (PRNGs).
Examples of a TRNG are the IBM Crypto Express adapters, while the PRNG function of the CPACF feature is a PRNG.
5.3.2 Random number generation in OpenSSL
When you review the original OpenSSL code, there are various source modules that use platform-dependent functionality for providing random numbers for any supported operating system. In the OpenSSL distribution, these source files are in /crypto/rand.
A new source module is provided for VSE when porting OpenSSL to VSE. It uses the API that is provided by phase IJBCRLIB to obtain random bytes. This function is also used by Encryption Facility for z/VSE for creating encryption keys. Phase IJBCRLIB, in turn, uses the z/VSE crypto device driver to access any available crypto hardware.
5.3.3 Alternatives
In z/VSE 5.1 and later, random numbers can be obtained by using one of the following methods:
•Using a crypto coprocessor card (PCIXCC, CEX2C, CEX3C, or CEX4C)
This is the best possibility because a crypto card returns true random numbers that are independent of any seed value. The cards provide built-in statistic tests transparently checking the random number quality. It is possible to obtain 8 KB (8192 bytes) of random output per request.
•Using the CPACF-provided pseudo random number generator (PRNG)
The PRNG function is a mixture of a hardware-based generator and the need of a software-provided seed value. It is up to the user to obtain this seed value from various sources of randomness in the system. The PRNG function is available on System z10 and later. It needs a 32-byte input parameter block and some clear text with the same length as the wanted number of random bytes.
•Using a pure software-based random number generator
This is the weakest alternative and is used only if the other methods are unavailable. It has deficiencies in probability, predictability, and security.
Phase IJBCRLIB transparently checks for hardware availability and always uses the best possible random number generator that is available on your system.
Example 5-1 is an extract from the IJBSSL trace that shows the available random number generators and which generator was used. Apparently, there was no Crypto Express coprocessor card available and the random bytes were generated by using CPACF.
Example 5-1 Extract from IJBSSL trace that shows the used random number generator
-> ijbslcry.c, get_bytes, num=32
Crypto lib not yet initialized ...
Check for CPACF and CEX2C ...
Using FUNC_RANDOM_GEN ...
rc from IJBCRLIB : 0
used generator : 2
highest available : 2
(3 = CEXnC, 2 = CPACF/PRNG, 1 = SW)
<- ijbslcry.c, get_bytes, rc=0, outlen=32
...
5.3.4 Considerations for the z/VSE crypto device driver
The z/VSE crypto device driver runs as subtask IJBCRYPT as part of the Basic Security Manager (BSM) security server (SECSERV), which runs by default in partition FB. It controls access to any installed crypto cards.
For more information about configuring crypto cards and the z/VSE crypto device driver, see Security on IBM z/VSE, SG24-7691, which is available at this website:
The crypto device driver includes the following performance relevant parameters:
•The polling time interval. This is the time interval in 1/300 fractions of seconds to check for a reply from a crypto card. The default value is 1/300 of a second. Specifying zero minimizes the elapsed job time, but increases CPU cycles. You can specify the polling time interval with the APWAIT command, as shown in the following example:
msg fb,data=apwait=n
•The AP interrupts setting. With z10 BC/EC or later, crypto cards can notify a caller when an enqueued crypto request is processed and is available in the card’s output queue. This removes the need for polling. AP interrupts are not supported by z/VM. Therefore, this is possible only when z/VSE is run in an LPAR. By default, AP interrupts are disabled. The commands to enable and disable AP interrupts are APEAI (enable) and APDAI (disable), as shown in the following example:
msg fb,data=[apeai | apdai]
For more information about the commands, see z/VSE Administration, SG34-2627, which is available at this website:
There is no general statement possible about which setting, polling, or interrupts is better for your environment. Tests showed that this depends on the type of workload.
|
Note: If you are using an External Security Manager (ESM), such as TopSecret or Alert, you can run the crypto device driver separately as phase IJBCRYPT in any static or dynamic partition. For more information about supporting an ESM, see z/VSE Administration, SG34-2627.
|
5.3.5 Performance
Performance tests that use a Crypto Express3 coprocessor card on a z10 EC with z/VSE 5.1 that is running under z/VM showed the influence of the crypto device driver polling time interval and internal card processor burden when different amounts of random numbers were requested. As this system ran under z/VM, AP interrupts were not supported. We left the polling time interval at 1/300 second.
Figure 5-2 shows the performance results that generated random output from 128 bytes up to 8 KB per request.
Figure 5-2 Random number generation performance with Crypto Express3
The results show that the card works optimally when it is requesting 4 - 8 KB random bytes per request because this minimizes the number of calls.
5.4 Keystore considerations
Before any SSL application can be run, you need a keystore that contains the RSA public/private key pair and the SSL certificates. Two types of keystores are available.
The following keystore formats are relevant for z/VSE:
•PFX
The Personal Information Exchange (PFX) format was defined by RSA Security and conforms to the PKCS#12 standard. PFX files can contain multiple keys and certificates and usually are password-protected. PFX files are supported by web browsers, such as Microsoft Internet Explorer and Mozilla Firefox. Sometimes, the file extension p12 is also used for the PFX format.
•JKS
The Java keystore (JKS) format is provided by Oracle and is the standard keystore format for Java applications. JKS files are mostly protected by a password. JKS files often cannot be handled by web browsers. Part of each Java installation is the keytool.exe, which also can be used for maintaining JKS keystores. In a VSE environment, JKS files are used by the VSE Connector Client.
•VSE keyring members
This type of keystore was created by Connectivity Systems International. It consists of three VSE library members with the same member name, but different member types: PRVK (contains the RSA key pair), ROOT (contains the SSL root certificate), and CERT (contains the SSL server certificate). Although other formats store all keys and certificates in one file, the CSI keyring format uses one separate VSE library member for each item. You can optionally protect the PRVK member with a custom passphrase by cataloging a CIALEXIT phase.
•PEM
The Privacy-enhanced mail (PEM) format is used by OpenSSL, but also by applications, such as FileZilla server. A PEM file can contain an RSA key pair, an SSL certificate, or both. It might be password protected. Although other keystore formats are binary only, the PEM file contents is base-64 encoded.
In the following sections, we describe how PEM keystores can be used on VSE with OpenSSL.
5.4.1 Creating a PEM keystore
Creating a PEM file is described in 3.7.2, “Creating the keystore” on page 71. Use Keyman/VSE because this is the simplest way to create a PEM file for use on z/VSE.
5.4.2 Exporting PEM to PFX
By using OpenSSL, the certificates in a PEM file can be exported into a PFX file, which can then be imported, for example, into web browsers, as shown in the following command:
openssl pkcs12 -export -out mycert.pfx -in mycert.pem
During this process, you are prompted to specify an export password. Earlier versions of Keyman/VSE did not allow reading a PFX file without a password. With Keyman/VSE, build January 2013 and later, this ability is now supported.
5.4.3 Importing PFX to PEM
By using the following command, you can import the certificates from a PFX file into a PEM file:
openssl pkcs12 -in mycert.pfx -out mycert.pem
During the process, you are prompted to specify an import password and a PEM passphrase. The import password is the password that was specified when the PFX was created with Keyman/VSE or the PFX was exported from another PEM.
|
Note: When you are editing the created PEM file, you see that it contains some information lines between the certificate and key data. We removed these lines before the PEM file was sent to VSE.
|
5.4.4 Password-protected keystores
By using OpenSSL, you can protect the key in a PEM file by using a passphrase. The use of a passphrase makes the key more secure; however, each server or client that is using this PEM must specify this passphrase every time it is started. If you do not want a password, specify the -nodes parameter (no DES encryption) when you are creating the PEM file. When this parameter is included, the private key is not encrypted.
Because only the key is protected by the passphrase, a PEM file can be created with a protected key. Certificates can be added later by editing the file by using a text editor.
The following command does not specify the -nodes parameter. Therefore, it creates a PEM with a password protected private key:
openssl req -x509 -days 365 -newkey rsa:4096 -keyout rsa4096p.pem -out rsa4096p.pem
The encrypted key is now indicated in the PEM file by BEGIN/END ENCRYPTED PRIVATE KEY, as shown in Figure 5-3.
Figure 5-3 PEM file with an encrypted private key
OpenSSL requires a password length of 4 - 511 characters. Private keys and encrypted private keys cannot be processed further by Keyman/VSE.
|
Note: You should not use a PEM passphrase because IPv6/VSE does not support password protected PEM files.
|
5.5 Programming
By using one of the following methods, you can write z/VSE applications by using OpenSSL:
•The use of the native OpenSSL API
The OpenSSL API is described on the OpenSSL website (http://www.openssl.org/) and consists of several hundred functions. On z/VSE, a subset of this API is provided by IJBSLVSE.OBJ that you link to your application to access the functions in the IJBSSL phase. For more information about supported native OpenSSL functions, see “OpenSSL API” on page 222.
•Using the z/OS SSL API
This method is the suggested method to use OpenSSL on z/VSE. The API is described in Chapter 9 of z/OS Cryptographic Services, SSL Programming, SC24-5901. The C data structures are defined in the include file gskssl.h, which is part of LE/C and included with PRD2.SCEEBASE. The object file IJBSLVSE must be linked to your application when the z/OS SSL API is used.
Although this API is now outdated on z/OS and should not be used by new z/OS applications, it is still the SSL API for z/VSE. All existing VSE SSL applications use this API because TCP/IP for VSE/ESA provides this exact API.
For more information about an API description of the GSK functions, see “z/OS SSL API” on page 221.
The following sections provide details about the use of the z/OS SSL API and switching between the two APIs. There is much literature on using the OpenSSL API on the Internet, including the following website:
5.5.1 Include files
The following SSL-related include files are provided with VSE:
•sslvse.h: Shipped with the CSI SSL-implementation in the TCP/IP lib.sublib
•gskssl.h: Shipped with the LE/C socket interface in PRD2.SCEEBASE
OpenSSL and OpenSSL applications must be compiled against gskssl.h because function prototypes in sslvse.h are defined with #pragma linkage OS, which causes errors in passing parameters to the GSK functions. Even more important is the fact that OpenSSL cannot have any dependency to vendor software.
As a consequence of the use of gskssl.h, the GSK API functions use return codes that are described in the z/OS API. These return codes are different from the codes that are used by the CSI SSL implementation. For example, the VSE Connector Server is compiled against gskssl.h, but there might be customer applications that use the CSI include file.
5.5.2 Passed socket number
The socket number as passed by a gsk-application (int s) is not necessarily the socket number only. VSE applications, such as CICS Web Support (CWS), VSE Connector Server, and WebSphere MQ pass a pointer to a private struct that contains the socket somewhere in the struct.
Example 5-2 shows how to pass the socket number as part of a C structure.
Example 5-2 Using a C structure for passing the socket number
typedef struct _mysock {
int somefield;
char* someptr;
int socketno;
} MYSOCK;
#pragma linkage (skread,OS)
int skread(int s, void * data, int len)
{
int rc;
MYSOCK* mys = (MYSOCK*)s;
rc = recv(mys->socketno, data, len, 0);
return(rc);
}
Routine skread uses this C structure to access the socket number. The application then specifies the function pointers of skread and skwrite in the sk_soc_init_data structure, as shown in Example 5-3.
Example 5-3 gsk_soc_init_data structure
typedef struct _gsk_soc_init_data { /* Secure soc init data */
int fd; /* file descriptor */
gsk_handshake hs_type; /* client or server handshake */
char * DName; /* keyring entry Distinguished */
/* name. When NULL, the default */
/* keyring entry is used */
char * sec_type; /* Type of application */
/* 0 CLIENT */
/* 1 SERVER */
/* 2 SERVER_WITH_CLIENT_AUTH */
/* 3 CLIENT_NO_AUTH */
char * cipher_specs; /* SSLV2 not used by VSE */
char * v3cipher_specs; /* SSLV3 cipher suites */
int (* skread) /* User supplied READ routine */
(int fd, void * buffer, int num_bytes);
int (* skwrite) /* User supplied WRITE routine */
(int fd, void * buffer, int num_bytes);
unsigned char cipherSelected[3]; /* SSLV2 not used by VSE */
unsigned char v3cipherSelected[2]; /* Cipher Spec used */
int failureReasonCode; /* failure reason code */
gsk_cert_info * cert_info; /* This information is read from*/
/* from the client certificate */
/* when client authentication is*/
/* enabled */
gsk_init_data * gsk_data; /* Pointer to init data */
} gsk_soc_init_data;
When the function pointers are specified, fetchep must be used, as shown in the following example:
typedef void (*FETCH_PTR)(int);
init_data.skread = (int (*) (int,void*,int))fetchep((FETCH_PTR)skread);
init_data.skwrite = (int (*) (int,void*,int))fetchep((FETCH_PTR)skwrite);
The reason for this is that the skread and skwrite functions are implemented by the application, but are called from phase IJBSSL.
5.5.3 Socket calls
When the GSK API is used, the caller specifies a read and a write callback routine that is used for sending data over the socket. This means that the SSL component never accesses the socket directly. It also means that the GSK API has no way of using other socket calls, such as givesocket, takesocket, and ctrl.
Unfortunately, OpenSSL performs socket calls. The low-level socket functions are defined in eos.h, where for VSE these #defines are used, as shown in Example 5-4.
Example 5-4 Low-level socket functions
#define get_last_socket_error() errno
#define clear_socket_error() errno=0
#define ioctlsocket(a,b,c) ioctl(a,b,c)
#define closesocket(s) close(s)
#define readsocket(s,b,n) read((s),(b),(n))
#define writesocket(s,b,n) write((s),(b),(n))
This causes OpenSSL to use the application-specified read/write routines (skread/skwrite). As of this writing, we do not have a solution or other socket calls because the GSK API considers these two routines only.
The GSK API implementation, in turn, implements the vse_readsocket and vse_writesocket routines and calls the application-specified read/write routines, as shown in Example 5-5.
Example 5-5 Specifying socket call functions
int (*skread)(int s, void* b, int n);
int (*skwrite)(int s, void* b, int n);
int vse_readsocket(int s, void* b, int n)
{
return skread(s, b, n);
}
int vse_writesocket(int s, void* b, int n)
{
return skwrite(s, b, n);
}
5.5.4 Switching between GSK and OpenSSL socket calls
So that applications can use both APIs (GSK and native OpenSSL) dynamically, gsk_initialize() sets a global variable ssl_use_gsk_callbacks in Phase IJBSSL, which causes the OpenSSL code to use the GSK callbacks. There are only two OpenSSL modules (bssconn.c and bsssock.c) that perform socket calls. The following change is made for VSE:
if (ssl_use_gsk_callbacks)
ret=vse_readsocket(b->num,out,outl);
else
// original openssl code ...
The global variable is reset in gsk_uninitialize().
The following sections describe some z/VSE specific aspects, such as how to specify the name and location of your keyring file and the list of SSL ciphers to be used by your application.
5.5.5 Specifying the key ring
Depending on whether you uploaded the PEM file as a VSE library member or as a VSAM file, there are two ways to specify the keyring in a GSK application. In both cases, the keyring location is specified when the gsk_initialize() function is called and the keyring name is specified when the gsk_secure_soc_init() function is called.
When an empty string for lib.sublib is specified, the GSK wrapper expects the keyring label (DName) to be a VSAM file name. When valid values are specified for lib and sublib, the keyring label is handled as a VSE library member name. The member type must be PEM in this case.
Keyring type Librarian
For Librarian type keyrings, a VSE library and sublibrary are specified in the gsk_initialize() call, as shown in Example 5-6.
Example 5-6 Specifying a Librarian type keyring
char * keyring = "CRYPTO.KEYRING";
gsk_init_data init_data;
...
init_data.keyring = keyring;
rc = gsk_initialize(&init_data);
The member name of the PEM file is specified in the gsk_secure_soc_init() call as the DName parameter, as shown in Example 5-7. The member type PEM is implicitly assumed.
Example 5-7 Specifying the DName for a Librarian-type keyring
gsk_soc_data * socdata;
gsk_soc_init_data sock_init_data;
...
sock_init_data.DName = "MYKEY"; // VSE library member name
socdata = gsk_secure_soc_init(&sock_init_data);
Keyring type VSAM
For VSAM type keyrings, specify an empty string for parameter “keyring” in the gsk_initialize() call, as shown in Example 5-8.
Example 5-8 Specifying a VSAM type keyring
char * keyring = "";
gsk_init_data init_data;
...
init_data.keyring = keyring;
rc = gsk_initialize(&init_data);
The keyring name (DName) as specified in the gsk_secure_soc_init() call is then considered to be a VSAM file label. As shown in Example 5-9, the DName variable specifies the VSAM file label.
Example 5-9 Specifying the DName for a VSAM-type keyring
gsk_soc_data * socdata;
gsk_soc_init_data sock_init_data;
...
sock_init_data.DName = "MYKEY"; // VSAM file label
socdata = gsk_secure_soc_init(&sock_init_data);
5.5.6 Using a password-protected keyring
As described in 5.4.4, “Password-protected keystores” on page 159, a PEM file can be password protected. When password-protected keyrings are used, each client or server must specify the PEM passphrase when the keystore is accessed.
When the GSK API is used, you specify the keyring password in the gsk_init_data structure when gsk_initialize() is called, as shown in Example 5-10.
Example 5-10 Specifying a keyring password
char * keyring = "";
gsk_init_data init_data;
...
init_data.keyring = keyring;
init_data.keyring_pw = "ssltest";
rc = gsk_initialize(&init_data);
OpenSSL on z/VSE now makes the following assumptions:
•The PEM file was created on an ASCII platform; therefore, the password is ASCII-encoded.
•The GSK application specifies the password in EBCDIC.
Therefore, before the related OpenSSL function for opening the PEM file is called, the password is translated to ASCII.
|
Note: Depending on the password characters, there might be an issue with the EBCDIC to ASCII translation. As of this writing, it is not possible to specify code pages.
|
5.5.7 Supported cipher suites
OpenSSL provides more cipher suites than are available with TCP/IP for VSE/ESA. Similar to TCP/IP for VSE/ESA, OpenSSL allows keywords, such as DEFAULT, ALL, and HIGH. Hardware support is available only for cipher suites that use the RSA algorithm for the SSL handshaking, AES, DES, or Triple-DES for encryption, and SHA-1, SHA-224, and SHA-256 as the hash algorithm.
An application that uses the GSK API must specify a list of hex codes as was done when the CSI implementation was used. The list of hex codes is then internally translated into an OpenSSL-readable list of cipher suites. For more information, see 5.5.8, “Specifying cipher suites” on page 166 for details.
Table 5-1 shows the list of cipher suites that are recommended for use with OpenSSL and the CSI SSL-implementation. Refer to section 5.10, “Considerations about Diffie-Hellman” on page 176 for setting up Diffie-Hellman and section 5.12, “Considerations on Elliptic Curve Cryptography” on page 184 for setting up Elliptic-Curve-based cipher suites.
Table 5-1 Recommended SSL cipher suites
|
Hex code
|
OpenSSL notation
|
TCP/IP for VSE/ESA notation
|
|
0A
|
DES-CBC3-SHA
|
SSL_RSA_WITH_3DES_EDE_CBC_SHA
|
|
2F
35
|
AES128-SHA
AES256-SHA
|
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
|
|
3C
3D
|
AES128-SHA256 a
AES256-SHA256 a
|
-
|
|
15
16
33
39
67
6B
|
EDH-RSA-DES-CBC-SHA b
EDH-RSA-DES-CBC3-SHA b
DHE-RSA-AES128-SHA b
DHE-RSA-AES256-SHA b
DHE-RSA-AES128-SHA256 b
DHE-RSA-AES256-SHA256 b
|
-
|
|
C011
C012
C013
C014
C027
|
ECDHE-RSA-RC4-SHA c
ECDHE-RSA-DES-CBC3-SHA c
ECDHE-RSA-AES128-SHA c
ECDHE-RSA-AES256-SHA c
ECDHE-RSA-AES128-SHA256 c
|
-
|
a These cipher suites belong to TLSv1.2 and require OpenSSL 1.0.1e or later.
b These cipher suites require the setup of DH parameters when VSE is the server.
c These cipher suites require the setup of DH parameters and an EC key when VSE is the server.
|
Note: For more information about OpenSSL cipher suites, see this website:
For a description of the cipher suites, see RFCs 2246 and 3268.
|
5.5.8 Specifying cipher suites
Your C program specifies the list of cipher suites as required by the GSK API. The list that is shown in Example 5-11 is then translated into an OpenSSL readable form.
Example 5-11 Specifying the SSL cipher suites
char * ciphers = "2F350A09";
...
sock_init_data.v3cipher_specs = ciphers;
...
socdata = gsk_secure_soc_init(&sock_init_data);
In this example, the following string is passed internally to OpenSSL:
AES128-SHA:AES256-SHA:DES-CBC3-SHA:DES-CBC-SHA
5.5.9 Supported RSA key lengths
On VSE, the RSA key length is limited to 4096 bits because this is current upper limit of what is supported by crypto cards. OpenSSL can process RSA keys up to 16384 bits. For VSE, the change in the include file rsa.h (as shown in Example 5-12) was made.
Example 5-12 Limiting the RSA key size to 4096 bits
#ifndef OPENSSL_RSA_MAX_MODULUS_BITS
//# define OPENSSL_RSA_MAX_MODULUS_BITS 16384
# define OPENSSL_RSA_MAX_MODULUS_BITS 4096
#endif
Removing this restriction and the use of software-based encryption does not make sense because software performance is limited when compared to the use of cryptographic hardware. For more information about OpenSSL performance, see 5.6, “Performing the OpenSSL speed test” on page 170.
5.5.10 Debugging
OpenSSL has different built-in debug capabilities. Debugging is enabled by recompiling the sources with related compiler debug switches. However, the SSL data structure (see typedef ssl_st in OpenSSL include file ssl.h) has an int field “debug”, which is used for internal debugging purposes.
Using the GSK API
When the z/OS GSK API is used, you can use the JCL variable SSL$DBG = [YES | NO] to turn the debug trace on and off. The variable is evaluated in the gsk_initialize() function, so it is usable with the z/OS GSK interface only.
Using both APIs
On VSE, debugging can be turned on and off without recompiling any source modules by the following new functions that are provided in modules IJBSLVSE and IJBSLACC:
extern int debug=0;
void ssl_enable_debug(void);
void ssl_disable_debug(void);
Enabling debugging causes a static global variable debug to be set to 1; disabling debugging resets the value to zero. The two functions can be used by any VSE GSK or OpenSSL application.
Debug output from phase IJBSSL is printed to SYSLST when debugging is enabled. You might consider enabling your GSK or OpenSSL application for debugging by providing a DEBUG parameter in the PARM string when your application is called, as shown in the following example:
// EXEC MYAPP,PARM='DEBUG'
The application code reads the parameter and calls the related function to enable or disable debugging.
5.5.11 Hardware crypto support
Hardware crypto support is provided transparently for existing VSE SSL applications because they use the z/OS GSK API. Depending on which API your application uses, the following possibilities apply.
Using the GSK API
When the z/OS GSK API is used, you can use the JCL variable SSL$ICA = [YES | NO] to turn hardware crypto support on and off. The variable is evaluated in the gsk_initialize() function; therefore, it is usable with the z/OS GSK interface only.
Using both APIs
Hardware crypto support can be turned on and off without recompiling any source modules by the following new functions that are provided in modules IJBSLVSE and IJBSLACC:
extern int ssl_use_ibmca=1;
void ssl_enable_ibmca(void);
void ssl_disable_ibmca(void);
Enabling hardware crypto support causes a static global variable ssl_use_ibmca to be set to 1, calling ssl_disable_ibmca() resets the value to zero. The two functions can be used by any VSE GSK or OpenSSL application.
Consider providing a parameter IBMCA in the PARM string when your application is called, as shown in the following example:
// EXEC MYAPP,PARM='IBMCA'
Your application code reads the parameter and calls the related function to enable or disable hardware crypto support.
5.5.12 Programming example
This section provides an example of a C program that uses OpenSSL.
Include files
In addition to the standard header files, you must include the statements that are shown in Example 5-13.
Example 5-13 Includes
#include <stdio.h>
#include <features.h>
#include <socket.h>
#include <stdlib.h>
#include <types.h>
#include <in.h>
#include <inet.h>
#include <ioctl.h>
#include <iconv.h> // for ASCII to EBCDIC translation
#include <gskssl.h>
Include file gskssl.h is part of the LE/C run time and normally is in PRD2.SCEEBASE.
Prototypes
The function prototypes that are shown in Example 5-14 allow enabling and disabling the OpenSSL debug trace and hardware crypto support.
Example 5-14 z/VSE provided functions
void ssl_enable_debug(void);
void ssl_disable_debug(void);
void ssl_enable_ibmca(void);
void ssl_disable_ibmca(void);
Data types and variables
The declarations that are shown in Example 5-15 are necessary to use the C socket API.
Example 5-15 Declarations for using the C socket API
typedef struct sockaddr_in SOCKADDR_IN;
typedef struct sockaddr SOCKADDR;
Callback routines
When the GSK API is used, the caller specifies a read and a write routine that is to be used for sending data over the socket. This means that the SSL component never accesses the socket directly. It also means that the GSK API has no way of using other socket calls, such as givesocket, takesocket, and ctrl.
Unfortunately, OpenSSL performed socket calls. The low-level socket functions that are defined in OpenSSL include file e_os.h where the following #defines are used for VSE:
#define readsocket(s,b,n) read((s),(b),(n))
#define writesocket(s,b,n) write((s),(b),(n))
This causes OpenSSL to use the application-specified read/write routines (skread/skwrite). As of this writing, we do not have a solution or other socket calls because the GSK API considers these two routines only.
The socket number as passed by the application (int s) is not necessarily the socket number. VSE applications, such as CWS, VSE Connector Server, and WebSphere MQ, pass a pointer to a private struct that contains the socket somewhere in the struct.
To be flexible, you write your code as shown in Example 5-16 and put the socket number into a data structure.
Example 5-16 Handling the socket number in a user application
typedef struct _mysock {
int somefield;
char* someptr;
int socketno;
} MYSOCK;
Your callback functions then resemble the functions that are shown in Example 5-17.
Example 5-17 Socket callback functions
/* I/O routine to perform a read function for SSL VSE */
#pragma linkage (skread,OS)
int skread(int fd, void * data, int len)
{
int rc;
MYSOCK* mysocket = (MYSOCK*)fd;
rc = recv(mysocket->socketno, data, len, 0);
return(rc);
}
/* I/O routine to perform a write function for SSL VSE */
#pragma linkage (skwrite,OS)
int skwrite (int fd, void * data, int len)
{
int rc;
MYSOCK* mys = (MYSOCK*)fd;
rc = send(mysocket->socketno, data, len, 0);
return(rc);
}
The addresses of the two callback routines skread() and skwrite() are specified in the gsk_soc_init_data structure before gsk_secure_soc_init() is called, as shown in Example 5-3 on page 161.
5.6 Performing the OpenSSL speed test
OpenSSL provides a built-in speed test with which you can check the speed of your system when cryptographic algorithms are performed, such as RSA, AES, SHA, or DES. On z/VSE, this test is included in phase IJBSSL and can be started with JCL, as shown in the following statement:
// EXEC SPEEDTST,PARM='OPENSSL'
For a list of supported parameters, see the original OpenSSL documentation on the Internet (http://www.openssl.org/) or enter the following command on a workstation with OpenSSL installed:
# openssl speed ?
5.6.1 Test parameters
On other platforms, this test is started with the speed parameter of the openssl.exe, as shown in the following command:
# openssl speed
You can run the speed test with specific parameters, as shown in the following command:
# openssl speed rsa
This command performs the RSA tests only. On VSE, you specify the following parameters:
// EXEC SPEEDTST,PARM='OPENSSL RSA'
or simply
// EXEC SPEEDTST,PARM='RSA'
RSA includes RSA512, RSA1024, RSA2048, and RSA4096.
You can display the available speed test parameters on Windows, as shown in Example 5-18.
Example 5-18 Speed test parameters
C:Program FilesOpenSSL-Win32in>openssl speed ?
Error: bad option or value
Available values:
mdc2 md4 md5 hmac sha1 sha256 sha512 whirlpoolrmd160
idea-cbc seed-cbc rc2-cbc bf-cbc
des-cbc des-ede3 aes-128-cbc aes-192-cbc aes-256-cbc aes-128-ige aes-192-ige aes-256-ige
camellia-128-cbc camellia-192-cbc camellia-256-cbc rc4
rsa512 rsa1024 rsa2048 rsa4096
dsa512 dsa1024 dsa2048
ecdsap160 ecdsap192 ecdsap224 ecdsap256 ecdsap384 ecdsap521
ecdsak163 ecdsak233 ecdsak283 ecdsak409 ecdsak571
ecdsab163 ecdsab233 ecdsab283 ecdsab409 ecdsab571
ecdsa
ecdhp160 ecdhp192 ecdhp224 ecdhp256 ecdhp384 ecdhp521
ecdhk163 ecdhk233 ecdhk283 ecdhk409 ecdhk571
ecdhb163 ecdhb233 ecdhb283 ecdhb409 ecdhb571
ecdh
idea seed rc2 des aes camellia rsa blowfish
Available options:
-engine e use engine e, possibly a hardware device.
-evp e use EVP e.
-decrypt time decryption instead of encryption (only EVP).
-mr produce machine readable output.
On VSE, you omit the first parameter “speed” because this is implied by starting the test by using the SPEEDTST phase, as shown in the following examples:
// EXEC SPEEDTST,PARM='AES-128-CBC'
// EXEC SPEEDTST,PARM='SHA1'
// EXEC SPEEDTST,PARM='DES-EDE3 SHA256 AES-128-CBC'
In addition to these openssl speed test parameters, you can use the two VSE-specific parameters IBMCA and DEBUG. Although the use of DEBUG does not make sense in a speed test, IBMCA enables hardware crypto support, as shown in the following example:
// EXEC SPEEDTST,PARM='AES-128-CBC IBMCA'
5.6.2 Test results
We performed the speed test on a zEnterprise 196 (2817-729 51) with z/VSE 5.1 running in an LPAR. The following sections describe the performance test results for CPU Assist for Cryptographic Function (CPACF) and Crypto Express3.
CPACF results
The CPACF feature accelerates symmetric crypto algorithms, such as AES, DES, and TDES and hash functions, such as SHA.
AES is one of the most important algorithms for SSL. It is faster and more secure than the formerly used DES or Triple-DES algorithms. Figure 5-4 shows the AES results for different blocks of plaintext data. For each key length (128, 192, and 256 bits), five test runs were performed with data block sizes from 16 bytes up to 8 KB. The chart in Figure 5-4 shows the number of operations with a specific key length and block size can be performed per second.
Figure 5-4 Software versus hardware performance results for AES
The results show that, for small blocks of data (less than 64 bytes), software performance is slightly better than hardware performance because of the processor burden of starting the CPACF function. However, this changes with increasing block sizes, where CPACF performs up to 16 times faster than software.
Crypto Express3 results
Crypto cards accelerate RSA operations that are part of each SSL handshake. Therefore, this pays off when there are workloads with many SSL handshakes in a certain time interval.
Examples are secure FTPs, Telnet sessions, and web browser connections to CICS Web Support. Figure 5-5 shows that RSA-1024 was performed 40 - 60 times faster when compared to software. This factor increases to 112 up to 122 for RSA-2048, and to over 300 for RSA-4096.
Figure 5-5 Software versus hardware performance results for RSA
On a z196, you need more than 1 second to create one signature with RSA-4096 when software is used. With a Crypto Express3 card, you can create 242 signatures per second for RSA-4096.
For RSA-512, the software and hardware results are equal because requests with this key length are not sent to a crypto card. Instead, they are always performed in software. In practice, RSA-512 was not used for decades, which tells us that without having Crypto Express adapters, it does not make sense to use RSA keys with a key length of more than 1024 bits.
5.7 How OpenSSL is used on z/VSE
In z/VSE 5.1, the only user for OpenSSL is the IPv6/VSE product from Barnard Software, Inc. (BSI), as of this writing. IPv6/VSE can be licensed through IBM or directly from BSI. The BSI stack provides two servers that provide SSL for VSE server and client applications. Both servers provide SSL/TLS transparently to the application. They also support batch and CICS applications that are written in any supported API, including applications that use the ASM SOCKET macro, EZASMI, EZASOKET, and LE/C APIs.
In z/VSE 5.2, an enhancement in the LE/C Multiplexer allows you to use any combination of IP stack (TCP/IP for VSE/ESA, IPv6/VSE, or LFP) and SSL implementation (OpenSSL, or the CSI-provided SSL implementation that is part of the CSI stack).
Skeleton EDCTCPMC in ICCF library 62 is an example of how to configure the use of TCP/IP socket and SSL APIs. The newly introduced parameter SSLPHASE allows specifying the phase implementing the SSL API independently from the phase implementing the TCP/IP socket API.
Example 5-19 shows how the new parameter is used:
•SYSID=’00’: TCP/IP for VSE/ESA using its own SSL implementation
•SYSID=’01’: Linux Fast Path using OpenSSL
•SYSID=’02’: IPv6/VSE using OpenSSL
However, every combination is possible.
The new parameter SSLPHASE is optional. If you omit it, the phase specified by the PHASE parameter is also assumed to implement the SSL API as shown in Example 5-19.
Example 5-19 LE Multiplexer example with new SSLPHASE parameter
* $$ JOB JNM=EDCTCPMC,CLASS=A,DISP=D,LDEST=*,PDEST=*
// JOB EDCTCPMC - GENERATE TCP/IP MULTIPLEXER CONFIG PHASE
// LIBDEF *,CATALOG=PRD2.CONFIG
// LIBDEF *,SEARCH=(PRD2.SCEEBASE,PRD1.BASE)
// OPTION ERRS,SXREF,SYM,NODECK,CATAL,LISTX
PHASE EDCTCPMC,*,SVA
// EXEC ASMA90,SIZE=(ASMA90,64K),PARM='EXIT(LIBEXIT(EDECKXIT)),SIZE(MAXC
-200K,ABOVE)'
EDCTCPMC CSECT
EDCTCPMC AMODE ANY
EDCTCPMC RMODE ANY
*
EDCTCPME SYSID='00',PHASE='$EDCTCPV',SSLPHASE='$EDCTCPV'
EDCTCPME SYSID='01',PHASE='IJBLFPLE',SSLPHASE='IJBSSLLE'
EDCTCPME SYSID='02',PHASE='BSTTTCP6',SSLPHASE='IJBSSLLE'
*
END
/*
// IF $MRC GT 4 THEN
// GOTO NOLINK
// EXEC LNKEDT,PARM='MSHP'
/. NOLINK
/*
/&
* $$ EOJ
For more information about how IPv6/VSE uses OpenSSL, see 3.7, “Setting up SSL” on page 71.
5.8 OpenSSL vulnerabilities
National Vulnerabilities Database (NVD) is the US government repository of standards-based vulnerability management data that uses the Security Content Automation Protocol (SCAP). This data enables automation of vulnerability management, security measurement, and compliance. NVD includes databases of security checklists, security-related software flaws, misconfigurations, product names, and impact metrics.
For more information, see this website:
On the NVD home page, click Vulnerabilities and search for SSL. You see a list of items that you can check against the current z/VSE OpenSSL version.
A list of recent security issues and available fixes is also provided on the OpenSSL website:
Check the newsflash section for recent updates. Available security fixes are regularly provided for z/VSE as IBM PTFs. Check the security section on the VSE home page for latest information and available security-related PTFs:
5.9 Considerations on TLSv1.2
As of this writing, TLSv1.2 is the newest SSL protocol version. It introduces new SSL cipher suites that use the SHA-256 hash algorithm instead of the SHA-1 function, which adds significant strength to the data integrity. For more information about TLSv1.2, see this website:
The following new SSL cipher suites and their related hexadecimal values are available:
0x3B TLS_RSA_WITH_NULL_SHA256
0x3C TLS_RSA_WITH_AES_128_CBC_SHA256
0x3D TLS_RSA_WITH_AES_256_CBC_SHA256
TLSv1.2 is supported with OpenSSL 1.0.1e, which is the current code level on z/VSE.
z/VSE needs TLSv1.2 for the following reasons:
•In NIST Special Publication 800-131A, dated January 2011, entitled “Transitions: Recommendation for Transitioning the Use of Cryptographic Algorithms and Key Lengths”, Table 9 shows that the use of the SHA-1 hash function is not allowed after December 31, 2013, except for non-digital signature applications.
•The IBM global security policy enforces all IBM products to be compliant with NIST Special Publication 800-131.
For more information and examples of how to set up and use TLSv1.2 with the IPv6/VSE product, see 3.7.15, “Using TLSv1.2” on page 110.
5.10 Considerations about Diffie-Hellman
The Diffie-Hellman (DH) key agreement method is an alternative to the traditional way of negotiating encryption keys during the SSL handshaking process using RSA. Diffie-Hellman does not provide authentication, and is therefore usually used together with an additional authentication mechanism, for example RSA. Diffie-Hellman is described in RFC 2631.
In the following, we compare DH with RSA in terms how an SSL session key is created and exchanged, not how the communication partners are authenticated.
•The main advantage of DH over RSA is the fact that a session key is never sent over the network, and therefore provides “perfect forward secrecy” (PFS). With PFS, it is not possible to decrypt a recorded SSL session in future when the RSA private key potentially got compromised or broken.
•The main disadvantage of DH is its higher CPU consumption. Establishing an SSL session by using DH consumes approximately 30% more CPU than compared to RSA.
The next sections explain how exchanging session keys works using RSA and show how DH differs from RSA.
5.10.1 RSA
Exchanging the session key by protecting it with an RSA public key is the way SSL worked on z/VSE with TCP/IP for VSE/ESA, but also with IPv6/VSE based on OpenSSL. Figure 5-6 on page 177 shows the SSL session key exchange using RSA.
The client first contacts the server. Second, the server sends its public RSA key, wrapped into a digital SSL certificate that is signed with the server’s private RSA key. In a third step, the client can verify the server’s signature with the help of a certificate authority (CA). Now comes the weak point: In step 4 the client creates a random session key, encrypts it with the server’s public key, and sends it to the server. Because of this, the session key is part of the SSL session data. Finally, in step 5, the server confirms using this session key and they can start transferring encrypted data.
Figure 5-6 SSL session key exchange using RSA
The important point is that the secret session key is part of the SSL session data, because the key is sent from the client to the server, encrypted by using the server’s public RSA key. If the server’s private RSA key is ever compromised, stolen, or broken, the session key is no longer secure. It is then possible to decrypt and read the complete session data if the session was recorded and stored.
5.10.2 Diffie-Hellman
Using Diffie-Hellman, the session key is never sent over the network and is therefore never part of the network session data. Figure 5-7 shows how the session key is negotiated using DH. Therefore, we do not talk about “exchanging a session key”, but rather talk about “agreeing on a common session key” through the DH key agreement process.
Like we started before with RSA, the client contacts the server in a first step. The server now sends its Diffie-Hellman parameters to the client. These DH parameters consist of a large prime number (p) and a so called generator (g) where 0 < g < p. For OpenSSL, g is always equal to 2. In a second step, both communication partners generate a random number in the range {1 ... p-2}. These two random numbers are kept secret and not sent over the line. They are called the DH private keys. In a third step, both parties perform certain calculations to derive two values A and B, which are exchanged over the insecure medium. Both parties can now derive the same secret session key.
Figure 5-7 SSL session key agreement using Diffie-Hellman
The important point is that the encryption key is created independently on both sides. Therefore, it is not possible to unveil the session key from a given recorded network session later.
For simplification, Figure 5-7 does not show how the two communication partners are authenticated. In practice, DH is mostly used together with authentication by using RSA.
5.10.3 Variants of Diffie-Hellman
There are three main variants of Diffie-Hellman in SSL/TLS:
•Anonymous mode
Anonymous mode does not use authentication and is therefore vulnerable to man-in-the-middle attacks. You should not use anonymous Diffie-Hellman.
•Static mode
Static Diffie-Hellman reuses at least one of the two DH private keys (see Figure 5-7 on page 178) unchanged for all connections. When both DH private keys are reused, the term “static-static” is used. When only one side uses the same key, the term is “ephemeral-static”. In some implementations, it might make sense to have one static DH private key, especially on the server side, for performance reasons.
•Ephemeral mode
Ephemeral Diffie-Hellman generates a new temporary DH private key for every connection, which enables PFS. When both sides always create new DH private keys for new connections, this is called “ephemeral-ephemeral”.
On z/VSE, only ephemeral mode is supported, so the VSE side always creates a new DH private key for a new connection. It is not possible to provide a pre-generated DH private key to the API. The related SSL cipher suites are all prefixed with DHE-RSA. The next section shows how to set up and use DHE-RSA on z/VSE.
5.11 Using DHE-RSA with OpenSSL on z/VSE
With z/VSE 5.2 onwards, OpenSSL can be used together with all IP stacks on z/VSE by configuring the SSLPHASE by using the LE/C Multiplexer. It can still be used with IPv6/VSE and its utilities BSTTATLS and BSTTPRXY.
|
Note: DHE-RSA is supported by APAR DY47545.
|
The next sections show how to use the DHE-RSA-based SSL cipher suites in practical examples.
5.11.1 Generating DH parameters
The first task for setting up Diffie-Hellman is generating a set of DH parameters that consist of two numbers p (a large prime number) and g (the generator value, which is always 2 for OpenSSL). Parameter generation is CPU expensive, and is therefore normally done once in advance.
You have two options for generating the parameters:
•Using openssl on your workstation.
•Using the Keyman/VSE tool.
Based on these parameters, different temporary session keys are then created for your SSL connections.
Using openssl on your workstation
The following openssl command generates a .pem file that contains the new DH parameters:
openssl dhparam -out dhparam.pem 1024
The parameters are stored in Base64-encoded text form and look similar to Example 5-20.
Example 5-20 Sample DH parameters
D:>type dhparam.pem
-----BEGIN DH PARAMETERS-----
MIGHAoGBANclzZUHl2R0NYH5D4cIHcfM8ATuk75NeO2iaV3FhcAAfs9ljlOuJaVn
UDH9qdl9A4YrDi3VPm55r/YHA4v3wx42Xaq4YfbljeGOKfT6HuhIVS9/n3ZjwNFe
2IAJeiV4VCRAmjVrgZcUodpEK+jEH4tULNS3NO3p6BbvU/6gyCQLAgEC
-----END DH PARAMETERS-----
To enable the DHE-RSA-based SSL cipher suites on VSE, just copy and paste this text form to the end of your .pem file.
Using the Keyman/VSE tool
The Keyman/VSE tool provides an even more convenient method of creating DH parameters and adding them to your .pem file.
|
Note: You need Keyman/VSE, build May 2014 or later for this function. You can download it from:
|
Keyman/VSE from May 2014 or later provides a new tool bar button for generating the DH parameters as shown in Figure 5-8.
Figure 5-8 Generate DH parameters in Keyman/VSE
Clicking Generate new DH Params displays the dialog box shown in Figure 5-9.
Figure 5-9 Generate Diffie-Hellman Parameters dialog box in Keyman/VSE
It is a restriction in Java that the maximum key length for DH parameter generation is 1024 bits for all Java versions before Java 8. If you need a longer key length, you must use either Java 8 or use openssl directly, as shown in “Using openssl on your workstation” on page 179, and import them by using the clipboard.
It does not matter whether you create (or import by using the clipboard) the DH parameters before or after the RSA key and your SSL certificates. Figure 5-10 shows a complete set of items: RSA key, CA root certificate, SSL server certificate, and DH parameters.
Figure 5-10 Complete set of items in Keyman/VSE
When uploading the .pem file to VSE, you now have the choice for including the DH parameters into your .pem file as shown in Figure 5-11. This enables the use of the DHE-RSA-based cipher suites on VSE. Select File → Save as PEM file on VSE.
Figure 5-11 Upload PEM file to VSE
Clicking Upload uploads all items into a new .pem file on VSE. The .pem file can either be a VSE/Librarian member or a VSAM file. Make sure that the VSE Connector Server is started at this time. The DH parameters are added at the end of the .pem file on VSE as shown in Example 5-21.
Example 5-21 PEM file with DH parameters on VSE
DITTO/ESA for VSE LE - Library Member Edit
Member DHPARMS.PEM Library CRYPTO.KEYRING Col 1 Format CHAR
SYSIPT data NO
1...5...10....5...20....5...30....5...40....5...50....5...60....5...70..
00066 9w0BAQUFAAOCAQEAlWLl5WIoiWGfS90yJaSJmcMKsUNujXSMnH2cSm8jnIuCwCKb
00067 vKBaYOeiX3QAJdW9z0NO68E7nDgEQ8IPrWz4bOj2EhffFPLZfNTwgX0iUj/AImhd
00068 cqoRVaQgmWAjj6qMY9FZWNK6RNb310umEexZVPas35wIUIOZtjrXAhpo0c9nMWrd
00069 4QVnc7Nx4JYK1Z1h8mKDc5UeSCpdIfa/+OnMXw9SbjoYTt9Hm2LpbqaQr0D3Z6Ur
00070 9FUaUSUcnBOOYLeUiO5iWofy4p2A3EOj4nuEIch+wwrf4E7GwoeniE/wCAAGiwxg
00071 dJa0lPAL2QLudmDs94L2RvgOpV36cBLEl0XmJw==
00072 -----END CERTIFICATE-----
00073 -----BEGIN DH PARAMETERS-----
00074 MIGHAoGBANclzZUHl2R0NYH5D4cIHcfM8ATuk75NeO2iaV3FhcAAfs9ljlOuJaVn
00075 UDH9qdl9A4YrDi3VPm55r/YHA4v3wx42Xaq4YfbljeGOKfT6HuhIVS9/n3ZjwNFe
00076 2IAJeiV4VCRAmjVrgZcUodpEK+jEH4tULNS3NO3p6BbvU/6gyCQLAgEC
00077 -----END DH PARAMETERS-----
00078 **** End of data ****
|
Note: You must include DH parameters in your .pem file only if VSE is the server. When VSE is the client (for example, as LDAP or FTP client), the remote server is responsible for providing the DH parameters during the session setup, and OpenSSL on VSE uses DHE-RSA transparently if required by the server.
|
5.11.2 Using DHE-RSA with Java-based connector
Java supports all DHE-RSA related SSL cipher suites, but uses different names than OpenSSL. Java uses the underline character ‘_’ to separate the parts within a cipher suite name, whereas OpenSSL uses dashes ‘-’. Table 5-2 shows the corresponding cipher suite names for OpenSSL and Java.
Table 5-2 DHE-RSA cipher suite names for OpenSSL and Java
|
Hex code
|
OpenSSL
|
Java
|
|
0x15
0x16
0x33
0x39
0x67 (1)
0x6B (1)
|
EDH-RSA-DES-CBC-SHA
EDH-RSA-DES-CBC3-SHA
DHE-RSA-AES128-SHA
DHE-RSA-AES256-SHA
DHE-RSA-AES128-SHA256
DHE-RSA-AES256-SHA256
|
SSL_DHE_RSA_WITH_DES_CBC_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
|
(1) Cipher suites 67 and 6B require TLSv1.2
|
Note: Support for DHE-RSA in the VSE Connector Client is added by using an APAR. Check for the latest connector client version.
|
The following sections use VSE Connector Server and VSE Navigator as an example of how to configure DHE-RSA for Java-based connector.
Client-side configuration
For VSE Navigator, make following changes in the SSL properties file:
KEYRINGFILE=c:\vsecon\samples\dhparms.pem
SSLVERSION=TLSv1.2
CIPHERSUITES=TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA
|
Note: The use of AES-256 in Java requires the unlimited security strength files for Java. You can download these files from the following website:
|
VSE-side configuration with IPv6/VSE
IPv6/VSE does not allow choosing specific SSL cipher suites. Therefore, the use of DHE-RSA depends on the configuration of the remote server or client:
•If VSE is the server, a client can request specific cipher suites.
•If VSE is the client, all supported cipher suites are sent to the server for negotiation.
To enable Diffie-Hellman support, the DH parameters must be available in the .pem file as specified by using the KEYFILE parameter for BSTTATLS or BSTTPRXY. The OpenSSL trace shows whether DH support is available:
*** DH parameters read successfully. DHE-RSA cipher suites are available.
VSE-side configuration with LE/C Multiplexer
In the VSE Connector Server’s SSL configuration member (SKVCSSSL in ICCF library 59), specify SSL version, .pem file name, and SSL cipher suites by using the already provided parameters. However, with OpenSSL there are more parameter values:
SSLVERSION = SSL30 | SSLV3 | TLS31 | TLSV1(1) | TLSV1.2(1) | ALL(1)
KEYRING = CRYPTO.KEYRING
CERTNAME = DHPARMS <- The name of your .pem file
SESSIONTIMEOUT = 86400
AUTHENTICATION = SERVER
(1) These parameters are only available with OpenSSL.
To enable DHE-RSA for VSE Connector Server, you must add the DHE-RSA cipher suites to the CIPHERSUITES parameter:
CIPHERSUITES = ; COMMA SEPARATED LIST OF NUMERIC VALUES
0A, ; RSA1024_3DESCBC_SHA
2F, ; TLS_RSA_WITH_AES_128_CBC_SHA (SINCE TCP/IP 1.5E)
35, ; TLS_RSA_WITH_AES_256_CBC_SHA (SINCE TCP/IP 1.5E)
3C, ; TLS_RSA_WITH_AES_128_CBC_SHA256 (requires TLSv1.2)
39, ; TLS_DHE_RSA_WITH_AES_256_CBC_SHA (requires Diffie-Hellman)
67 ; TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 (requires TLSv1.2 and DH)
The DH parameters must be available in the .pem file.
5.12 Considerations on Elliptic Curve Cryptography
Elliptic Curve Cryptography (ECC) is an encryption technique that provides public-key encryption similar to RSA. While the security strength of RSA is based on very large prime numbers, ECC uses the mathematical theory of elliptic curves and achieves the same security level with much smaller keys. The mathematical background of ECC is described in RFC 6090:
The use of ECC in SSL/TLS is described in RFC 4492.
In practice, ECC is often used with Diffie-Hellman to speed up performance. ECC does not replace RSA for authenticating the communication partners, but is used for generating the ephemeral DH session key with the help of an EC private key. RSA is still used for providing authentication. The related SSL cipher suites all have ECDHE-RSA in their names and complement the plain DHE-based cipher suites.
The main advantage of Elliptic Curve Cryptography with Diffie-Hellman (ECDHE-RSA) over plain Diffie-Hellman (DHE-RSA) is better performance and the same level of security with less key bits. A disadvantage is the additional effort for creating and maintaining the EC key.
The next section shows how to set up and use ECDHE-RSA on z/VSE.
5.13 Using ECDHE-RSA with OpenSSL on z/VSE
This section shows how to use the ECDHE-RSA-based SSL cipher suites on z/VSE.
|
Note: ECDHE-RSA is supported by APAR DY47545.
|
There are two different ECC implementations in OpenSSL, version 1.0.0 and later:
•A 32-bit implementation that is used on z/VSE.
•A 64-bit implementation that provides better performance, but requires latest 64-bit ecc compiler support and cannot be used on z/VSE. The OpenSSL code on z/VSE is compiled using OPENSSL_NO_EC_NISTP_64_GCC_128.
The next sections show how to create an EC key and upload it to VSE for use by OpenSSL.
5.13.1 Generating the EC key
Generating the EC key must be done using openssl on your workstation. At the time of writing, the Keyman/VSE utility does not provide support for generating and uploading EC keys. For our tests, we used these commands:
openssl ecparam -out ecparam.pem -name prime256v1
openssl genpkey -paramfile ecparam.pem -out ecdhkey.pem
The EC key is now contained in file ecdhkey.pem and looks as shown in Example 5-22.
Example 5-22 Generated EC key
D:>type ecdhkey.pem
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg0PvMUyVFylSlfwx8
H0q1Er8ve9pgcvs6Ezfty8yq6qKhRANCAAS9d/zL/ZIwydd5EvLoLF3+GnUHQ/pu
PiN945ucTiLTj08YjZ7SCIWbGskb+DH32viG6+4goAoZQT3Tzoi3EYz8
-----END PRIVATE KEY-----
The EC key has the same string delimiters as an RSA private key, and therefore cannot be stored in the same PEM file together with the RSA key.
5.13.2 Uploading the EC key to VSE
You can upload the PEM file that contains the EC key to VSE by using FTP or any other file transfer mechanism that provides ASCII to EBCDIC translation. You can even use copy/paste into a new DITTO created file by using your Terminal Emulator. The target file on VSE must be a VSE/Librarian member. The member contents on VSE must look identical to the character representation on your workstation. Example 5-23 shows the uploaded member in DITTO.
Example 5-23 Uploaded EC key in VSE/Librarian
DITTO/ESA for VSE LE - Library Member Edit
Member ECDHKEY.PEM Library PRD2.CONFIG Col 1 Format CHAR
SYSIPT data NO
1...5...10....5...20....5...30....5...40....5...50....5...60....5...70..
00000 **** Top of data ****
00001 -----BEGIN PRIVATE KEY-----
00002 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg0PvMUyVFylSlfwx8
00003 H0q1Er8ve9pgcvs6Ezfty8yq6qKhRANCAAS9d/zL/ZIwydd5EvLoLF3+GnUHQ/pu
00004 PiN945ucTiLTj08YjZ7SCIWbGskb+DH32viG6+4goAoZQT3Tzoi3EYz8
00005 -----END PRIVATE KEY-----
00006 **** End of data ****
The following section shows how to use ECDHE-RSA with the Java-based connector.
5.13.3 Using ECDHE-RSA with Java-based connector
Java supports all ECDHE-RSA related SSL cipher suites, but uses different names than OpenSSL. Table 5-3 shows the supported cipher suites on z/VSE with their corresponding names for Java.
Table 5-3 ECDHE-RSA cipher suite names for OpenSSL and Java
|
Hex code
|
OpenSSL
|
Java
|
|
0xC012
0xC013
0xC014
0xC027 (1)
|
ECDHE-RSA-DES-CBC3-SHA
ECDHE-RSA-AES128-SHA
ECDHE-RSA-AES256-SHA
ECDHE-RSA-AES128-SHA256
|
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
|
(1) Cipher suite C027 requires TLSv1.2
|
Note: ECDHE-RSA cipher suites with SHA-384 are currently not supported on z/VSE due to the general restriction of SHA-384 and SHA-512 in OpenSSL on z/VSE.
|
Client-side configuration
For VSE Navigator, make the following changes in the SSL properties file:
KEYRINGFILE=c:\vsecon\samples\ecdh.pem
SSLVERSION=TLSv1.2
CIPHERSUITES=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
Specify your PEM file that contains the RSA key and DH parameters here. The EC key is not needed on the client side. It is only on VSE in a second file, ECDHKEY.PEM.
VSE-side configuration for IPv6/VSE
IPv6/VSE does not allow selecting specific SSL cipher suites. Instead, the string returned by gsk_get_cipher_info is passed back to OpenSSL when calling the gsk_secure_soc_init API function. This string contains all supported ECDHE-RSA based cipher suites.
To enable Elliptic Curve support, an EC key must be available in VSE library member ECDHKEY.PEM in the same VSE sublibrary specified by using the KEYRING parameter for BSTTATLS or BSTTPRXY. The OpenSSL trace shows whether an EC key is available and can be used:
*** EC Private Key read successfully.
*** EC key set. ECDHE-RSA cipher suites are available.
VSE-side configuration for LE/C Multiplexer
OpenSSL in general is available for TCP/IP for VSE/ESA and Linux Fast Path (LFP) only by using the LE/C Multiplexer. The availability of ECDHE-RSA depends on the related application. For example, when using the VSE Connector Server, specify the ECDHE cipher suites in the server’s SSL config member (SKVCSSSL):
SSLVERSION = TLSV1.2
KEYRING = CRYPTO.KEYRING
CERTNAME = ECDHSSL
SESSIONTIMEOUT = 86400
AUTHENTICATION = SERVER
The EC key must be contained in a second member ECDHKEY.PEM in the VSE sublibrary specified by the KEYRING parameter. The CIPHERSUITES parameter includes the ECDHE-related cipher suites:
CIPHERSUITES = ; COMMA SEPARATED LIST OF NUMERIC VALUES
2F, ; TLS_RSA_WITH_AES_128_CBC_SHA
35, ; TLS_RSA_WITH_AES_256_CBC_SHA
67, ; TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
6B, ; TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
C013, ; TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
C014, ; TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
C027, ; TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
|
Note: Support for ECDHE-RSA cipher suites in the VSE Connector Server by using the LE/C Multiplexer is added by using APAR. Check for the latest connector server version.
|
5.14 Restrictions
This section describes the restrictions and a known problem with OpenSSL on z/VSE.
5.14.1 No SHA-512 support
Apparently, the VSE C-compiler is unable to compile the SHA-512 related modules. The OpenSSL FAQ.txt file says:
“OpenSSL SHA-512 implementation depends on compiler support for 64-bit integer type. Few elder compilers [ULTRIX cc, SCOcompiler to mention a couple] lack support for this and, therefore, are incapable of compiling the module in question. The suggestion is to disable SHA-512 by adding no-sha512 to ./config [or ./Configure] command line. Another possible alternative might be to switch to GCC.”
As of this writing, the VSE code is compiled by using the OPENSSL_NO_SHA512 option. This might change by using SHA-512, which is provided by CPACF.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.