IBM z® zERTJSSE Provider Guide, v 8

IBM z® zERTJSSE

Introduction

zERT-enabled Java Secure Socket Extension (ZERTJSSE) is a security provider that enables secure Internet communications and gathers security information about those communications for reporting to z/OS Encryption Readiness Technology (zERT). ZERTJSSE is a z/OS-specific provider supported in 31-bit and 64-bit releases of IBM® SDK for z/OS®, Java™ Technology Edition, Version 8.

Overview

ZERTJSSE wraps the IBMJSSE2 provider and notifies zERT when there is a change to the state of a secure session managed by IBMJSSE2. ZERTJSSE does not implement any JSSE functionality itself, but instead uses the IBMJSSE2 provider to perform JSSE operations. ZERTJSSE merely monitors the secure sessions managed by IBMJSSE2, and the flow of data between the user and the IBMJSSE2 provider remains unchanged. Please see the Documentation section for information regarding the underlying JSSE implementation.

Dependencies

ZERTJSSE has the following stack dependencies:

ZERTJSSE depends on the underlying IBMJSSE2 provider to provide all JSSE functionality provided by ZERTJSSE. Please see the Documentation section for information regarding the underlying JSSE implementation.
ZERTJSSE depends on the zERT Java API to notify the zERT Discovery/Recording component. See the Configuration And Migration section for more information.

Limitations

Lack of support for SSLEngines:

Since SSLEngines are transport-independent, ZERTJSSE has no way of associating the zERT information with a TCP connection. Therefore, the SSLEngines provided by ZERTJSSE do not include zERT support.

Renegotiation Notification Timing Issues:

Since renegotiation events are reported to zERT in separate threads, timing issues may occur where subsequent renegotiations trigger different threads that notify zERT out of order.

Clear communication under layered SSLSockets:

A layered SSLSocket is created when an application wraps an existing Socket with an SSLSocket to create a secure connection. When a layered SSLSocket is created, the underlying Socket is still available to the application. If the application continues to transmit data via the underlying Socket, zERT may report the connection as secure when unencrypted data is still being transferred over the TCP connection.

Unavailable Attributes:

The SECATTRi_TLS_Handshake_Type attribute requested by zERT has no way of being discovered by ZERTJSSE. Therefore, ZERTJSSE does report the SECATTRi_TLS_Handshake_Type attribute.

System properties:

System properties used in IBMJSSE2 are set upon loading of the ZERTJSSE provider. Any change in these system properties between being set in ZERTJSSE and IBMJSSE2 could result in unexpected behavior.

Configuration and Migration

For zERT to be enabled for JSSE functionality, ZERTJSSE must be specified as the JSSE provider to use.

Configuring the default JSSE provider in the java.security file

Users can specify ZERTJSSE as the default JSSE provider to use by placing com.ibm.zertjsse.ZERTJSSE before any other JSSE providers in the provider list in the java.security file. The java.security file is located at $JAVA_HOME/lib/security.

Configuring the ZERTJSSE provider on calls to SSLContext.getInstance()

To explicitly specify ZERTJSSE as the JSSE provider to use, users can hardcode ZERTJSSE on calls to SSLContext.getInstance([Protocol], “ZERTJSSE”). If ZERTJSSE is neither specified as the default provider nor explicitly specified on a call to SSLContext.getInstance(), ZERTJSSE will not be chosen as the JSSE provider to use, and zERT functionality for JSSE functionality will not be enabled. Likewise, if a user specifies a different JSSE provider on a call to SSLContext.getInstance(), ZERTJSSE will not be used.

zERT Java API Configurations

ZERTJSSE requires the use of the zERT Java API which was released in APAR PI88041. This APAR must be installed on the system, and the application must meet the following requirements:

The EZBCPP.jar file must be included in the classpath. EZBCPP.jar is installed in the directory /usr/include/java_classes.
If the code using ZERTJSSE runs in a 31-bit JVM, then libEZBCPP.so must be located in $LIBPATH so the JNI methods can be found. libEZBCPP.so is installed in the directory /usr/lib.
If the code using ZERTJSSE runs in a 64-bit JVM, then libEZBCPP64.so must be located in $LIBPATH so the JNI methods can be found. libEZBCPP64.so is installed in the directory /usr/lib.
The zERT Java API runs on z/OS V2R3 or later.
The Java Virtual Machine (JVM) must be Java 8 or later.

IBMJSSE2 Configurations

To configure JSSE functionality, please follow the configuration options for IBMJSSE2. For more information about configuring IBMJSSE2, please see the Documentation section.

Documentation

For information about the JSSE Standard API, see: JSSE Standard API

For detailed JSSE2 for z/OS documentation, see: JSSE2 z/OS Unique Considerations

For documentation on the underlying JSSE2 functionality, see: IBMJSSE2 Provider

For information about zERT, see: z/OS Encryption Readiness Technology (zERT)

For information about Java Security providers, see: General information about IBM security providers

Trademarks

IBM is a trademark or registered trademark of International Business Machines Corporation in the United States, or other countries, or both.

Oracle and Java are registered trademarks of Oracle and/or its affiliates.

Other company, product, or service names may be trademarks or service marks of others.

IBM z® zERTJSSE Provider Guide

for the Java^TM SDK, Standard Edition, v 8

(Last Updated October, 2018)

Table Of Contents