IBM z® zERTJSSE Provider Guide, v 11

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 only the 64-bit release of IBM® Semeru Runtime Certified Edition for z/OS®, Version 11.0.

Overview

ZERTJSSE wraps the SunJSSE provider and notifies zERT when there is a change to the state of a secure session managed by SunJSSE. ZERTJSSE does not implement any JSSE functionality itself, but instead uses the SunJSSE provider to perform JSSE operations. ZERTJSSE merely monitors the secure sessions managed by SunJSSE, and the flow of data between the user and the SunJSSE 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 SunJSSE 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 SunJSSE are set upon loading of the ZERTJSSE provider. Any change in these system properties between being set in ZERTJSSE and SunJSSE 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.

ZERTJSSE Runtime JVM Arguments

ZERTJSSE requires specific runtime JVM arguments to have access to necessary java.base files. The following commands are required at runtime:

--add-exports java.base/sun.security.ssl=zertjsse
--add-opens java.base/sun.security.ssl=zertjsse

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/conf/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 PH47010. This APAR must be installed on the system, and the application must meet the following requirements:

The EZBCPPMJ.jar file must be included in the classpath. EZBCPPMJ.jar is installed in the directory /usr/include/java_classes.
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 V2R4 or later.
The Java Virtual Machine (JVM) must be IBM® Semeru Runtime Certified Edition for z/OS®, Version 11.0 or later.

SunJSSE Configurations

To configure JSSE functionality, please follow the configuration options for SunJSSE. For more information about configuring SunJSSE, 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: SunJSSE 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 IBM® Semeru Runtime Certified Edition for z/OS®, Version 11.0

(Last Updated September, 2022)

Table Of Contents