z/OS Java Security Frequently Asked Questions

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:

n
specifies the preference order. 1 is the most preferred provider.

className
specifies the name of the subclass that is implementing the Provider class.

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 the "Online documentation" section of
    Hardware Cryptography IBMJCECCA Overview
    http://www-03.ibm.com/servers/eserver/zseries/software/java/products/j6jcecca.html  
For Java SDK 5, see the "Online documentation" section of
    Hardware Cryptography IBMJCECCA Overview
    http://www-03.ibm.com/servers/eserver/zseries/software/java/products/j5jcecca.html  
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?

For full function cryptography the unrestricted policy files must be installed. By default, the IBM� SDK provides unlimited jurisdiction policy files.

If import or export laws for your jurisdiction require the use of limited cryptography, you should use the limited jurisdiction policy files by setting the property crypto.policy=limited in the java.security file. See IBM SDK Policy Files for further information.

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   
    http://www.ibm.com/servers/eserver/zseries/software/java/j6jcecca.html   
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
    http://www.ibm.com/servers/eserver/zseries/software/java/j6jcecca.html
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. This RedBook is available at
    Java Security on z/OS - The Complete View, SG24-7610
    http://www.redbooks.ibm.com/abstracts/sg247610.html
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:

JCERACFKS keystores are supported by the IBMJCE provider while JCECCARACFKS keystores are supported by the IBMJCECCA provider.

These keystores can only contain keys supported by the provider. This means that

a keyring containing one or more ICSF (hardware) and RACF (software) keys can only be represented as a JCECCARACFKS keystore
a keyring containing only RACF (software) keys can be represented either as a JCERACFKS keystore or as a JCECCARACFKS keystore.

Additional information about JCERACFKS and JCECCARACFKS keystores is provided int the RedBook Java Security on z/OS - The Complete View, SG24-7610. This RedBook is available at
    Java Security on z/OS - The Complete View, SG24-7610
    http://www.redbooks.ibm.com/abstracts/sg247610.html
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 a program, see How do I copy entries from one keystore to another in a program?

In Java 6 and later, the IBMJCECCA utility hwkeytool command -importkeystore can be used instead. For details, see How do I copy entries from one keystore to another using hwkeytool?

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.

How do I migrate a JCA4758KS keystore to a JCECCAKS keystore?

To migrate a JCA4758KS keystore to a JCECCAKS keystore, you need to copy the keys and certificates stored in the JCA4758KS keystore into a JCECCAKS keystore. To do this in a program, see How do I copy entries from one keystore to another in a program?

In Java 6 and later, the IBMJCECCA utility hwkeytool command -importkeystore can be used instead. For details, see How do I copy entries from one keystore to another using hwkeytool?

How do I copy entries from one keystore to another in a program?

You can copy the keys and certificates in one keystore to another keystore that can be a different type. To do this in a program:

open the source keystore

load the source keystore

open the destination keystore

if the destination keystore already exists, load the destination keystore

for each entry in the source keystore,

extract the key and/or certificate

create an entry in the destination keystore to hold it/them

store the destination keystore

How do I copy entries from one keystore to another using hwkeytool?
hwkeytool can be used to import keys and certificates stored in one keystore into another keystore that can be a different type. In each case, the sample commands are shown below on multiple lines for readability, but should be entered as a single command.
The following illustrates the hwkeytool command to import a keystore when all of the key entries have the same password as the keystore:
    hwkeytool -importkeystore 
        -srckeystore src_ks_name 
        -destkeystore dest_ks_name
        -srcstoretype src_ks_type 
        -deststoretype dest_ks_type
        -srcstorepass src_ks_storepass
        -deststorepass dest_ks_storepass
  
If any key entry has a different password from the keystore, you need to import each key entry separately. The following illustrates the hwkeytool command to import a single key entry:
    hwkeytool -importkeystore 
        -srcalias src_keyalias
        -srckeypass src_keypass
        -srckeystore src_ks_name 
        -destkeystore dest_jks_name
        -srcstoretype src_ks_type
        -deststoretype dest_ks_type
        -srcstorepass src_ks_storepass
        -deststorepass dest_ks_storepass
  
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?
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. This RedBook is available at
    Java Security on z/OS - The Complete View, SG24-7610
    http://www.redbooks.ibm.com/abstracts/sg247610.html
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:

The JCECCAKS keystore can be used to store all key types supported by the IBMJCECCA provider while the JCECCARACFKS keystore can only be used to store key types supported by RACF. For example, symmetric keys can be stored in a JCECCAKS keystore but cannot be stored in a JCECCARACFKS keystore.
The JCECCAKS keystore is secured by a password that you define while the JCECCARACFKS is secured by RACF authorization settings.
The JCECCARACFKS behavior is defined by RACF and differs from the Java keystore model. The JCECCAKS keystore follows the model of the Java keystore very closely, making it easier for use by Java programmers.

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":

The default value is 60.

If you set the value to 0, hardware cryptography will be used, regardless of data size.

If you set the value to -1, software cryptography will be used, regardless of data size.

You can set the value of "ibm.DES.usehdwr.size" on the command line or in a program.
To set the value to 80 on the command line when you run a program named myProgram:
        java -Dibm.DES.usehdwr.size=80 myProgram
To set the value to 0 in a Java program:
        System.setProperty( "ibm.DES.usehdwr.size", "0" );
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 documentation   
    http://www.ibm.com/developerworks/java/jdk/security/50/secguides/keytoolDocs/KeyToolUserGuide-150.html   
or
    Java SDK 6 keytool documentation
    http://www.ibm.com/developerworks/java/jdk/security/60/secguides/keytoolDocs/keytool.html
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,

you attempted to use DSA encryption on a platform other than zSeries 800 or zSeries 900

you attempted to use AES encryption on a z architecture prior to System z10

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:
For a file-based keystore, specify:
    -storetype JCECCAKS
For a RACF-based keystore, specify:
    -storetype JCECCARACFKS
What does it mean when hwkeytool returns "java.io.IOException: Invalid keystore format "?
This might means that the keystore specified with -keystore is not the type specified with the -storetype option. For example, you will get this message if you specify a JCEKS keystore with -keystore but specify JCECCAKS with -storetype.

It might mean that you created a keystore using one version of java and are attempting to use it in an earlier version of java. Beginning with SDK 7 SR 8 and SDK 7.1 SR2, the IBMJCECCA provider includes support for creating JCECCAKS keystores and key entries within them with strengthened protection. For more information, see
    Greater Key and Keystore strength for IBMJCECCA available in z/OS Java 7 and 7.1
A keystore created with the new, stronger protection is not compatible with earlier releases. If you attempt to use hwkeytool in an earlier release with a keystore created with the new level of protection, you will get this message. If you have created a keystore with the new protection and need to share its contents with an older level of Java, you must migrate the entries from the new keystore to a keystore created with an earlier service level. The result is a keystore with the older, weaker protection that can be used by all releases. For information about migrating entries from one keystore to another, see How do I copy entries from one keystore to another in a program? and How do I copy entries from one keystore to another using hwkeytool?
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:
repeat the command and specify -alias with some other value
remove the existing entry before creating the new one. Issue the following command with the -storetype option and, if you are not using the default keystore (homeDir/.HWkeystore), specify the keystore name with the -keystore option.
    hwkeytool -delete -alias mykey
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".

When an exception message includes an ICSF return code or reason code, is that code in hexadecimal or decimal format?

When calls are made by the IBMJCECCA provider to ICSF services to perform cryptographic operations, return/reason codes are displayed in error messages using the decimal values of the error codes, which are documented in the z/OS Cryptographic Services ICSF Application Programmer's Guide (SA22-7522) lists of Return Codes and Reason Codes from the ICSF Callable Services.

How does performance compare when generating random numbers using the IBMJCE provider vs the IBMJCECCA provider?

Performance implications have been observed when using the hardware-based random number generator instead of the random number generator in the IBMJCE provider. Please refer to the technote titled Random Number Generation operations performance using Hardware Crypto (IBMJCECCA) Technote for further information.

Where can I find information about digital certificates?
For general information about digital certificates, information about creating digital certificates in Java and information about storing digital certificates in a Java keystore, see the hwkeytool - Key and Certificate Management Tool document for your version of Java, available as described in How can I get the z/OS Unique Considerations document and the hwkeytool - Key and Certificate Management Tool document?

For general information about digital certificates, information about creating digital certificates in RACF, and information about storing digital certificates in RACF, see the chapter titled "RACF and digital certificates" in the Security Server RACF Security Administrator's Guide (SA22-7683).

General information about digital certificates is available in the following reference documents:
    Software Information Center - Security Concepts
    Digital Certificates
and in the following tutorials:
    Getting Started with Digital Certificates
    Understanding Digital Certificate on z/OS
    Java Security, Part 1 - Crypto basics
For information about the internal structure of a digital certificate, see the RFC located at:
    Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
Additional information is available in a white paper published by the following:
    Symantec VeriSign Authentication Services
How can I renew a digital certificate stored in RACF?

For information about renewing a certificate stored in RACF, see the topic "Renewing an expiring certificate" in the chapter titled "RACF and digital certificates" in the Security Server RACF Security Administrator's Guide (SA22-7683).

How can a private key stored in RACF be shared among users?

For information about sharing a private key stored in RACF, see the topic "Sharing a private key using a key ring" in the chapter titled "RACF and digital certificates" in the Security Server RACF Security Administrator's Guide (SA22-7683).

What does "Hardware error from call CSNBSYE 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.

However, if you are doing encryption with an AES cipher in GCM mode, it might mean that you specified an unsupported authentication tag length (TLen) in the GCMParameterSpec you provided to initialize the AES Cipher object. The authentication tag length (TLen) specified in the GCMParameterSpec must be a value accepted by the z/OS component that will perform the encryption/decryption operation. See the z/OS ICSF Application Programmer's Guide (SA22-7522) for more information. In particular, see the section on CSNBSYE where you will find the allowed authentication tag lengths in the description of parameter key_parms_length. Note that, although the tag length specified in the GCMParameterSpec is in bits, the valid tag lengths listed in the ICSF Application Programmer's Guide are in bytes. (For example, a GCMParameterSpec TLen value of 112 corresponds to an ICSF tag length of 14.)

What does "Hardware error from call CSNBSYD 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.

However, if you are doing decryption with an AES cipher in GCM mode, it might mean that you specified an unsupported authentication tag length (TLen) in the GCMParameterSpec you provided to initialize the AES Cipher object. The authentication tag length (TLen) specified in the GCMParameterSpec must be a value accepted by the z/OS component that will perform the encryption/decryption operation. See the z/OS ICSF Application Programmer's Guide (SA22-7522) for more information. In particular, see the sections on CSNBSYD where you will find the allowed authentication tag lengths in the description of parameter key_parms_length. Note that, although the tag length specified in the GCMParameterSpec is in bits, the valid tag lengths listed in the ICSF Application Programmer's Guide are in bytes. (For example, a GCMParameterSpec TLen value of 112 corresponds to an ICSF tag length of 14.)

When I use an AES Cipher in GCM mode, how is the the authentication tag returned by encryption and specified to decryption?

Galois/Counter Mode (GCM) is a block cipher mode of operation that uses universal hashing over a binary Galois field to provide authenticated encryption and decryption. The hashing is done over the clear text with any additional authentication data provided appended to it.
The byte[] cipherText buffer returned by the AES Cipher in GCM mode encryption contains the actual cipherText (if any) and the authentication tag (the hash value). For this reason, the cipherText buffer length is the cipherText length plus TLen, the length of the authentication tag. In all other ways, the return and specification of the authentication tag is transparent to the application. As with all cipher modes, a byte[] cipherText buffer is returned by encryption process and that cipherText buffer must be passed as input to the decryption process.

Is it necessary to specify additional authentication data (AAD) when I use an AES Cipher in GCM mode?

No, it is not necessary to specify additional authentication data (AAD) when you use an AES Cipher in GCM mode. However, if additional authentication data is specified when data is encrypted, then exactly the same additional authentication data must be specified when the data is decrypted. For encryption, you must specify text to encrypt, additional authentication data, or both. The returned byte[] cipherText buffer will contain cipherText only if clear text was provided, but it will always contain the computed authentication tag. For decryption, you must specify the byte[] cipherText buffer from the encryption process and any additional authentication data specified for encryption.
For information about Galois/Counter Mode (GCM), see When I use an AES Cipher in GCM mode, how is the the authentication tag returned by encryption and specified to decryption?

Why would I use an AES Cipher in GCM mode with no additional authentication data (AAD)?

If no additional authentication data (AAD) is specifed to the AES Cipher in GCM mode then the authentication tag will be computed on the clear text alone. Even with no additional authentication data, this provides some authentication of the clear text produced by the decryption process.

Is it necessary to specify text to encrypt or decrypt when I use an AES Cipher in GCM mode?

No, it is not necessary to specify text to encrypt or decrypt when you use an AES Cipher in GCM mode. If no clear text is specified during the encrypt phase, the cipherText buffer returned will contain only the authentication tag for the additional authentication data. Because the buffer contains the tag, it must be passed to the decryption process as if it did contain cipherText.
For information about Galois/Counter Mode (GCM), see When I use an AES Cipher in GCM mode, how is the the authentication tag returned by encryption and specified to decryption?

Why would I use an AES Cipher in GCM mode with no text to encrypt or decrypt?

It is sometimes useful to store or to transmit a clear text message (or document) and later to verify that the contents have not been altered. This message authentication is available using a GCM mode cipher with no text for encryption.
If the message is specified as additional authentication data and no text is specified for encryption, then the byte[] cipherText buffer will contain an authentication tag for the message. To authenticate the message later, GCM mode cipher decryption is used. The message is again specified as additional authentication data and the byte[] cipherText buffer returned by encryption is as if it were data to decrypt. If the message is successfully authenticated, an empty byte[] clearText buffer is returned. If the message cannot be authenticated, an AEADBadTagException is thrown.

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.
The following illustrates listing the keystore if you are accessing the RACF keyring as a JCERACFKS keystore and redirecting the output to a file (keystore_list.log):
    keytool -debug -list -storetype JCERACFKS 
        -keystore safkeyring://OwningUserID/KeyringName 
        -J-Djava.protocol.handler.pkgs=com.ibm.crypto.provider
        >keystore_list.log 2>&1
The following illustrates listing the keystore if you are accessing the RACF keyring as a JCECCARACFKS keystore and redirecting the output to a file (keystore_list.log):
    hwkeytool -debug -list -storetype JCECCARACFKS 
        -keystore safkeyring://OwningUserID/KeyringName 
        -J-Djava.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider
        >keystore_list.log 2>&1
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):

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.

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
    http://www-03.ibm.com/servers/eserver/zseries/software/java/products/jaas14.html#differ
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 V1Rxx Security Server RACF Security Administrator's Guide (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 V1Rxx Unix System Services Planning Guide (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 V1Rxx Unix System Services Planning guide (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
    http://www-03.ibm.com/servers/eserver/zseries/zos/racf/racfjsec.html
Why does ThreadSubject.doAs(...) not execute successfully under JZOS?
z/OS JAAS requires that doAs(...) be executed on the Initial Program Thread (IPT), as it does under normal Java execution. However, while executing a Java program with JAAS using JZOS, the Java program does not execute on this thread.

To bypass this restriction, execute the doAs(...) code in a Java thread. For example:
    new Thread(new Runnable()
    {
        public void run()
        {
       	    Object obj =  OS390ThreadSubject.doAs(subject, new SAFAction());
       	    System.out.println("\n>>>>>FINISHED calling SAFACTION: OBJ:" + obj + "\r");
        }
            
    }).start();

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.

IBMJCECCA FAQ

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

How do I install the IBMJCECCA provider?

Installing the IBMJCECCA provider statically

Installing the IBMJCECCA provider dynamically

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

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

What are the security policy files?

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

What is the IBMJCE4758 provider?

What services are supported by the IBMJCECCA provider?

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

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

What are the differences between JCERACFKS and JCECCARACFKS keystores?

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

How do I migrate a JCA4758KS keystore to a JCECCAKS keystore?

How do I copy entries from one keystore to another in a program?

How do I copy entries from one keystore to another using hwkeytool?

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

What are the differences between JCECCAKS and JCECCARACFKS keystores?

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

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

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

What keytool support is available on z/OS?

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

What does NoSuchProviderException mean?

What does NoSuchAlgorithmException mean?

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

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

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

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

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

What does it mean when hwkeytool returns "java.io.IOException: Invalid keystore format "?

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

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

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

When an exception message includes an ICSF return code or reason code, is that code in hexadecimal or decimal format?

How does performance compare when generating random numbers using the IBMJCE provider vs the IBMJCECCA provider?

Where can I find information about digital certificates?

How can I renew a digital certificate stored in RACF?

How can a private key stored in RACF be shared among users?

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

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

When I use an AES Cipher in GCM mode, how is the the authentication tag returned by encryption and specified to decryption?

Is it necessary to specify additional authentication data (AAD) when I use an AES Cipher in GCM mode?

Why would I use an AES Cipher in GCM mode with no additional authentication data (AAD)?

Is it necessary to specify text to encrypt or decrypt when I use an AES Cipher in GCM mode?

Why would I use an AES Cipher in GCM mode with no text to encrypt or decrypt?

IBMJSSE2 FAQ

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

How can I debug a RACF certificate problem?

How can I debug a hardware problem?

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

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

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

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

JAAS and SAF FAQ

General Debugging

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

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

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

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

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

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?

Why does ThreadSubject.doAs(...) not execute successfully under JZOS?

Trademarks

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