z/OS Java Security Frequently Asked Questions

(last updated September, 2010)



IBMJCECCA FAQ

IBMJSSE2 FAQ

JAAS and SAF FAQ


IBMJCECCA FAQ


Why would I install the z/OS JCE "hardware provider" (IBMJCECCA)?

The IBMJCECCA provider extends the JCE capability with the use of hardware cryptography via the IBM Common Cryptographic Architecture (CCA) APIs provided by ICSF on z/OS.

The IBMJCECCA provider gives Java programmers the significant security advantages afforded by secure hardware cryptographic devices with minimal changes to existing Java applications. In most cases, the only changes needed to a Java application are that method invocations that specify the IBMJCE provider be changed to specify the IBMJCECCA provider. If method invocations accept the default JCE provider, it is only necessary to configure the JVM so that the IBMJCECCA provider has precedence over the IBMJCE provider.


How do I install the IBMJCECCA provider?

- Installing the IBMJCECCA provider statically

The java.security file is a flat text file that is used to configure various security settings used by the JVM. Among other things, the java.security file contains the list of installed providers and specifes a preference order among them. When a provider is not specified explicitly on a Java API call (that is, on a Java API call that supports such a parameter), then the preference order in java.security is used to search for the first provider that implements the requested service and algorithm.

The java.security file is located in the ${java-home}/lib/security directory. The provider list in the java.security file will have the following form:

security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
security.provider.2=com.ibm.crypto.provider.IBMJCE
security.provider.3=com.ibm.security.jgss.IBMJGSSProvider
security.provider.4=com.ibm.security.cert.IBMCertPath
security.provider.5=com.ibm.security.sasl.IBMSASL

To register a new provider, an entry must be added to specify the provider subclass name and the preference order for that provider. The entry has the following format:

security.provider.n=className

where:

The precedence order of the IBMJCECCA provider should always be higher than the IBMJCE provider. If this is not the case, any request for Java crytographic services that does not explicitly specify a provider will always be routed to the IBMJCE provider because the IBMJCE provider supports a superset of the algorithms supported by the IBMJCECCA provider. In such a scenario, a Java program will not exploit the benefits of hardware cryptography, as provided by the IBMJCECCA provider, unless the IBMJCECCA provider is explicitly specified on a Java API call.

To update java.security to install the IBMJCECCA provider, you add a line for the IBMJCECCA provider and increase the precedence order of the providers that will be at lower precedence. For example, to add the IBMJCECCA provider to the provider list shown above, update it as follows. (Emphasis is shown only to highlight the changes.)

security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
security.provider.2=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
security.provider.3=com.ibm.crypto.provider.IBMJCE
security.provider.4=com.ibm.security.jgss.IBMJGSSProvider
security.provider.5=com.ibm.security.cert.IBMCertPath
security.provider.6=com.ibm.security.sasl.IBMSASL

Providers registered via the java.security file are instantiated when the JVM is initialized. The provider settings will be in effect for any JVM that is created using that Java installation configuration.


- Installing the IBMJCECCA provider dynamically

A provider can be dynamically added, removed, or its preference order can be dynamically changed by a Java application. This can be accomplished by the addProvider(), insertProviderAt(), or removeProvider() methods from the class java.security.Security. The changes are only in effect for applications running in the same JVM as the Java application that dynamically alters the installed providers list.

See the Java API documentation for more information about the APIs that dynamically alter the security provider list.


How can I get the z/OS Unique Considerations document and the hwkeytool - Key and Certificate Management Tool document?

The z/OS Unique Considerations document and the documentation for hwkeytool are contained in the jceccaDocs.jar file. The Hardware Crytography IBMJCECCA Overview explains how to obtain jceccaDocs.jar and extract the files. The z/OS Unique Considerations documentation is contained in the file named "zOSHWCryptoRefGuide.html". The hwkeytool documentation is contained in the file named "hwkeytool.html".

For Java SDK 6, see Hardware Cryptography IBMJCECCA Overview.

For Java SDK 5, see Hardware Cryptography IBMJCECCA Overview.


What if I install the IBMJCECCA provider and the required cryptographic devices are not installed, configured and operational?

If the required hardware cryptographic devices are not available, some of the IBMJCECCA services can fail. In such cases, there is no failover capability.

In other words, if the hardware needed to service a request is not available, the service will fail. Unless the application making the request does its own failover, there will be no retry invoking a software implementation of the same service.


What are the security policy files?

A policy file is a flat text (ASCII) file distributed in a jar file. Policy files are used by the SecurityManager to grant access to Java Permissions. When running with a security manager, if access to a resource is required but it is not defined by a policy file, then access is denied.


What are the unrestricted policy files and how do I install them?

Due to export restrictions, the IBM Java SDKs ship with a set of restricted policy files that limit the size of the cryptographic keys that are supported. To overcome these restrictions, the user will need to obtain the "unrestricted policy files" and substitute them for files that are supplied with the Java SDK. The security files are located in the ${java-home}/lib/security directory and are named:

The unrestricted policy files are the same for the IBM Java SDK 1.4.2, IBM Java SDK 5 and IBM Java SDK 6. These files can be downloaded from the Using IBMJCECCA section of the web site, see Hardware Cryptography IBMJCECCA Overview.


What is the IBMJCE4758 provider?

The IBMJCE4758 provider was the cryptography provider in Java SDK 1.4 and Java SDK 5 supporting hardware cryptography on z/OS. This provider is deprecated and has been superceded by the IBMJCECCA provider. It should no longer be used.


What services are supported by the IBMJCECCA provider?

For an overview of services provided by the IBMJCECCA provider, see Hardware Cryptography IBMJCECCA Overview.

For more details, see the z/OS Unique Considerations document for your version of the Java JVM, available as described in How can I get the z/OS Unique Considerations document and the hwkeytool - Key and Certificate Management Tool document?


What access permissions are required to use IBMJCECCA hardware provider with ICSF?

See the "CSFSERV Access Permissions Required for ICSF Services Used by IBMJCECCA Provider" subheading of the section Using IBMJCECCA in Hardware Cryptography IBMJCECCA Overview.


How do I set up my RACF keyring permissions for use with the JCECCARACFKS and JCERACFKS keystores?

Refer to z/OS Security Server RACF Command Language Reference, SA22-7687, to determine the RACF authorizations needed to access your keyring as a Java keystore. The authority of your RACF administrator is required to issue the necessary RACDCERT commands.

Additional information about the JCECCARACFKS and JCERACFKS keystores is provided in the RedBook Java Security on z/OS - The Complete View,
SG24-7610.


What are the differences between JCERACFKS and JCECCARACFKS keystores?

Both these keystore types are used to represent a RACF keyring as a Java keystore. The differences between them are the provider that supports them and the type of keys they can contain:

Additional information about JCERACFKS and JCECCARACFKS keystores is provided in the RedBook Java Security on z/OS - The Complete View,
SG24-7610.


How do I convert a JCECCAKS keystore to a JCECCARACFKS keystore?

You cannot convert a keystore from one type to another, you can only copy the keys and certificates stored in one keystore into another keystore where the target keystore is a different type. To do this:

In Java 6 and later, the IBMJCECCA utility hwkeytool command -importkeystore can be used instead. For details about what commands are supported by hwkeytool in your version of the Java SDK, see hwkeytool - Key and Certificate Management Tool, available as described in How can I get the z/OS Unique Considerations document and the hwkeytool - Key and Certificate Management Tool document?

Note that the JCECCAKS keystore supports both symmetric keys and asymmetric keys and certificates while the JCECCARACFKS keystore supports only asymmetric keys and certificates. As a consequence, you can copy the entries in a JCECCARACFKS keystore into a JCECCAKS keystore but you might not be able to copy all the entries in a JCECCAKS keystore into a JCECCARACFKS keystore.


What changes are necessary to convert an application from using a JCECCAKS keystore to using a JCECCARACFKS keystore?

See "Usage examples -- using Java keystores on z/OS" in the RedBook Java Security on z/OS - The Complete View, SG24-7610.


What are the differences between JCECCAKS and JCECCARACFKS keystores?

The IBMJCECCA provider supports keystores types of both JCECCAKS and JCECCARACFKS. The primary difference between the two types is that the persistent data for a JCECCAKS keystore is a file and the persistent data for a JCECCARACFKS keystore is in a RACF database.

Additional differences:


When (and how) can I control whether crypto operations are performed in hardware?

For ease of use, the IBMJCECCA provider includes a DES and DESede software implementation. You can control whether DES and DESede encrypt and decrypt operations are performed on hardware or software. For information about how to assert this control, see What is "ibm.DES.usehdwr.size" and how do I use it?


What is "ibm.DES.usehdwr.size" and how do I use it?

"ibm.DES.usehdwr.size" is a Java system property used to specify the size at which hardware cryptography is used for DES/CBC, DES/ECB, DESede/CBC, or DESede/ECB. (For other algorithms or modes this property is ignored.) If the first (or only) data segment passed for encryption/decryption is less than the value of this property, IBMJCECCA will perform the operation in software.

Notable values for "ibm.DES.usehdwr.size":

You can set the value of "ibm.DES.usehdwr.size" on the command line or in a program.


In what situations would I want to control when crypto operations are performed in hardware?

For DES or DESede, the IBMJCECCA provider selects either the hardware path or the software path when the first encryption or decryption operation is performed. This means that, if data for an encryption operation is passed using one or more calls to update() followed by a call to doFinal(), the decision is based on the size of the first data processed.

For example, if you are encrypting or decrypting the contents of a tape image, the tape header will be smaller than the subsequent data blocks. If the data blocks are large, you may prefer that the encryption or decryption be processed using hardware. However, if your application passes first the tape header data and then the data blocks, the default behavior of IBMJCECCA might select the software path based on the size of the header.

See What is "ibm.DES.usehdwr.size" and how do I use it? for information about how to specify that the hardware path should be selected, regardless of data size, whenever it is available.


What keytool support is available on z/OS?

keytool is a command line utility to manage and to manipulate a keystore. On z/OS, keytool is provided for keystore types supported by the IBMJCE provider and hwkeytool is provided for keystore types supported by the IBMJCECCA provider. Both include the functions defined by the Java specification, and both include extensions to that specification.

For more information about keytool, see Java SDK 5 keytool or Java SDK 6 keytool documentation.

For more information about hwkeytool, see hwkeytool - Key and Certificate Management Tool, available as described in How can I get the z/OS Unique Considerations document and the hwkeytool - Key and Certificate Management Tool document?


What information should I collect before contacting the IBM service team with a problem related to the hardware provider (IBMJCECCA)?

You might reduce the time required to resolve your problem if you include the results of the following command in your PMR:

java -version

If the service team is not able to resolve the issue from your description of the failing scenario and the symptoms of the failure, the next step will be to get trace data for the failure. In order to generate the trace, specify the following option
-Djava.security.auth.debug=all when you run your application. This causes trace data to be printed to stderr. To capture it, you must redirect the output to a trace file.

For example, the following command creates a security trace of the program MyTest and stores it in the file MyTest_trace.log:

java -Djava.security.auth.debug=all MyTest >MyTest_trace.log 2>&1

If the trace is needed, the service team will give you instructions on how to transmit it.


What does NoSuchProviderException mean?

You will see this error when an application issues a

Service.getInstance(algorithm,provider)

and the specified provider is not installed in the JVM. The installation instructions provided in How do I install the IBMJCECCA provider? can be used to install any provider as long as you know the package and class name.


What does NoSuchAlgorithmException mean?

You will see this error when an application issues a

Service.getInstance(algorithm,provider)

and the specified provider does not support the specified algorithm for the specified Service.

You will also see this error when an application issues a

Service.getInstance(algorithm)

and no installed provider supports the specified algorithm for the specified Service.

Verify that you have specified the algorithm, or the algorithm and the provider name, correctly.


How can I query what algorithms are supported by a particular Provider?

In general, it is better not to specify a provider name when you get an instance of a security object. This allows the Java Security Framework to select the first provider (in the provider list of the current java.security file) that registered for the service,algorithm pair you are requesting.

However, it is possible to query a provider for a list of the algorithms it supports. The following code snippet queries the IBMJCECCA provider:

String provName = "IBMJCECCA";
    Provider prov = null;
    Set<Provider.Service> algorithms = null; 

    prov = Security.getProvider( provName );
    algorithms = prov.getServices();        

    Iterator<Provider.Service> iter = algorithms.iterator();
        
    System.out.println( "  " );
    System.out.println( "Algorithms supported by " + provName + ":" );
    while( iter.hasNext() )
    {
       Provider.Service thisAlg = iter.next();
       System.out.println( "    service: " + thisAlg.getType());
       System.out.println( "    algorithm: " + thisAlg.getAlgorithm() );
       System.out.println( " " );
    }

What does "UnsupportedOperationException: Hardware error - function getPrivateExponent() has no meaning in hardware" mean?

You might see this error during JVM initialization if the unrestricted policy files are not installed when the IBMJCECCA provider is loaded by the Java Security Framework.

See What are the unrestricted policy files and how do I install them?


What does "Error encrypting private key (java.lang.SecurityException: Unsupported keys)" mean?

    com.ibm.security.pkcsutil.PKCSException: Error encrypting private key
 (java.lang.SecurityException: Unsupported keys)
    com.ibm.security.pkcsutil.PKCSException: Error encrypting private key
 (java.lang.SecurityException: Unsupported keysize or algorith)
      at com.ibm.security.pkcs8.EncryptedPrivateKeyInfo.(Unknown Source)
      at com.ibm.security.pkcs8.EncryptedPrivateKeyInfo.(Unknown Source)
      at com.ibm.crypto.tools.KeyTool.b(Unknown Source)
      at com.ibm.crypto.tools.KeyTool.a(Unknown Source)
      at com.ibm.crypto.tools.KeyTool.run(Unknown Source)
      at com.ibm.crypto.tools.KeyTool.main(Unknown Source)

This message usually means that the unrestricted policy files are needed for the key you are attempting to use.

See What are the unrestricted policy files and how do I install them?


What does "Hardware error from call CSNDPKB return code 8 reason code 11000" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "The value specified for length parameter for a key token, key, or text field is not valid". In general, this means that you have requested an algorithm or operation not available on your current hardware platform.

For example,


What does it mean when hwkeytool returns "InvalidAlgorithmParameterException: Params must be instance of RSAKeyGenParameterSpec"?

This usually means that you have not specified the -storetype option on your hwkeytool command. Unless you have changed the value of keystore.type in the java.security file, the default keystore type is JKS. The hwkeytool utility does not support JKS keystores.

If you want your keystore to be type JKS, use the keytool utility instead of the hwkeytool utility.

If you want your keystore to support hardware keys, then specify one of the following, depending on which type of keystore you prefer:


If I use hwkeytool but do not specify -keystore, what keystore name is used?

If you use the hwkeytool utility, the default keystore is .HWkeystore in the home directory of the current userid.


What does it mean when hwkeytool returns "java.lang.Exception: Key pair not generated, alias <mykey> already exists"?

If you do not specify the -alias option to hwkeytool, the default value of mykey is used.

This message means that the keystore already contains an entry with the alias "mykey". This entry might have been created using hwkeytool either without the
-alias option or with -alias mykey specified. This entry also might have been created programatically using a Java KeyStore API.

Do one of the following:


What does "Hardware error from call CSNDDSV returnCode 8 reasonCode 11008" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "The public or private key values are not valid. (For example, the modulus or exponent is zero.) You cannot use the key."

This definition suggests that the key object is itself corrupted or improperly formed, and that may be the case. However, there is another possible cause for this error: in some cases, specifying the wrong key can cause this message.

For example, suppose you generate an RSA key pair, create a Signature object (sig) and pass the RSA private key to sig.sign(). If you then pass the RSA public key to sig.verify() the expected result is true. If you instead pass the RSA public key from a different RSA key pair to sig.verify() then you are passing a valid key that is the wrong key. In this case the expected result from sig.verify() is false. However, in some cases, you might instead get an exception with the message "Hardware error from call CSNDDSV returnCode 8 reasonCode 11008".

IBMJSSE2 FAQ


How can I debug 'Exception in thread "main" javax.net.ssl.SSLHandshakeException: handshake failure'?

This error can be caused by attempting to use RACF certificates with JSSE2 and specifying a null password when loading the RACFInputStream and the key manager factory. If this is the case, specify a password for the RACFInputStream and key manager factory and restart your application.

If this does not resolve your issue, the next step is to determine what might be causing the handshake failure by getting trace data for the SSL handshake. In order to capture the trace for the SSL handshake specify the option javax.net.debug=all when you run your application. This causes trace data to be printed to stdout. To capture it, you redirect output to a trace file.

The following illustrates getting an SSL trace:

java -Djavax.net.debug=all MyTest >MyTest_trace.log 2>&1

How can I debug a RACF certificate problem?

When debugging a RACF problem the first step is usually to list the Java keystore representing the RACF keyring in Java. In each case, the sample commands are shown below on multiple lines for readability, but should be entered as a single command.

If you suspect a RACF keyring setup problem, list the keyring and then each entry in the keyring using the RACF command line utility RACDCERT.

The following illustrates listing the keyring:

RACDCERT LISTRING('OwningUserID.KeyringName')

The following illustrates listing the entry with label "MyCert":

RACDCERT LIST(LABEL('MyCert'))

If more information is needed to diagnose the problem, you can turn on tracing in the Java code that handles the RACF keyring. The following illustrates getting this trace and redirecting the output to a file (MyTest_trace.log):

java -Djavax.net.debug=all -Djava.security.auth.debug=ibmjceracf 
    MyTest >MyTest_trace.log 2>&1

How can I debug a hardware problem?

If you suspect a problem related to the hardware platform, then the trace data you provide for the IBM service team should include tracing both for the IBMJCECCA provider and for SSL. The following illustrates getting this trace and redirecting the output to a file (MyTest_trace.log):

java -Djavax.net.debug=all -Djava.security.auth.debug=all  
    MyTest >MyTest_trace.log 2>&1

What does 'javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.g: End user tried to act as a CA' mean?

This error occurs when a handshake is done and the CA certificate used for authentication does not have the basicConstraints extension turned on in the CA certificate.

In general, when you create certificates you must be sure to turn on the CA basicConstraints extension. In RACF be sure to create the CA certificate with the syntax RACDCERT CERTAUTH .... so that basicConstraints extension is included with the CA parameter set to true and the PathLen parameter set to some non-zero value appropriate for the certificate chain.


What does it mean when I get an EOF error after the client hello is sent on the client side?

This problem has been seen in WebSphere when JSSE2 was talking to a System SSL server and the System SSL server did not have a keyring that contained a private key.


What does it mean when I get "certificate verify message error" on one side and "bad_certificate" on the other?

This error usually means that the unrestricted policy files are needed for the operation being attempted.

See What are the unrestricted policy files and how do I install them?


What information should I collect before contacting the IBM service team with a problem related to IBMJSSE2?

You might reduce the time required to resolve your problem if you include the results of the following command in your PMR:

java -version

If the service team is not able to resolve your issue from your description of the failing scenario and the symptoms of the failure, the next step will be to get trace data for the failure. In order to capture the trace for the SSL failure, specify the option javax.net.debug=all when you run your application. This causes trace data to be printed to stdout. To capture it, you redirect output to a trace file.

The following illustrates getting an SSL trace:

java -Djavax.net.debug=all MyTest >MyTest_trace.log 2>&1

If the trace is needed, the service team will give you instructions on how to transmit it.

JAAS and SAF FAQ


General Debugging

There are configurable values to enable trace output for the JAAS and SAF components.

To enable diagnostic tracing for SAF, issue the following command:

     
export OS390_SS_TRACE=ON

To enable diagnostic tracing for JAAS, include the java.security.debug option when you start the JVM, as illustrated below (this example also redirects the output to a file):

java -Djava.security.debug=all MyTest >MyTest_trace.log 2>&1

Can I use the z/OS JAAS LoginModule with protected userids?

The z/OS JAAS OS390LoginModule can create a LoginContext for protected userids under the following circumstances (both 1 and 2 must prevail):

  1. When using the OS390LoginModule shipped with the Java SDK, the LoginContext object must be created with ONLY the name (userid) parameter; no callback handler may be passed when creating the LoginContext object.
  2. One of the following is true about the userid that invokes the application:
    • the userid is a superuser
    • the userid is defined to RACF as a SURROGAT of the protected userid under which authentication is to be performed AND the userid is granted READ permission to the BPX.SERVER FACILITY class

Is it possible to purchase JAAS LoginModule for RACF separately and run it on another platform?

No, the JAAS LoginModule (OS390LoginModule) for RACF cannot be purchased separately. JAAS modules are only available in the JAAS component of the Java for z/OS SDK. The OS390LoginModule for RACF cannot be run on any other platform, as the support is compiled specifically for the z/OS platform. Also, JAAS, as shipped in the Java SDK, contains no support for remote authentication using the OS390LoginModule on z/OS.


Is it possible to control access to datasets using z/OS JAAS and the SAFPermission interfaces?

The SAF services which provide access controls support general resources only; datasets are not supported.


What differences exist between z/OS JAAS and the version of JAAS supplied by Sun?

The major differences are in how native security influences the default behavior on z/OS. For more information, see Differences between IBM and Sun versions of JAAS.


Is a JAAS application on z/OS required to run as an authorized program?

Nothing implemented in z/OS JAAS requires running the calling applications as authorized programs. However, because JAAS uses controlled services to perform authentication and authorization, all program modules which are part of an application using JAAS on z/OS must be marked as program-controlled.

To learn more about protecting programs on z/OS, refer to "Protecting Programs" in z/OS Security Server RACF Security Administrator's Guide (PDF, 5.4MB), SA22-7683.

To learn more about the effects of uncontrolled programs and how to define modules to program control, refer to "Handling dirty address spaces" in z/OS Unix System Services Planning (PDF, 3.2MB), GA22-7800.

For information on defining programs as program controlled, refer to "Defining programs in UNIX files to program control" and "Steps for defining programs from load libraries to program control" in z/OS Unix System Services Planning (PDF, 3.2MB), GA22-7800.


The SAF interfaces shipped in the Java SDK only support querying userid membership in a group; is there any way to administer changes to group membership with Java?

The z/OS Java SDK does not ship any services for performing administration of users and groups. However, z/OS ships with a set of Java interfaces permitting administration of users and groups in security repositories. For more information, refer to Java Security Administration.


Browse z/OS