---

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. On z/OS the CCA interface is provided by ICSF. On Linux for System z the CCA interface is provided by the IBM PCIe Cryptographic Coprocessor software.

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?

What operating systems does the IBMJCECCA provider support?

The IBMJCECCA provider is supported on both z/OS and Linux for System z.

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.

On z/OS the java.security file is located in the $JAVA_HOME/lib/security directory. On Linux for System z the java.security file is located in the $JAVA_HOME/jre/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 IBM System z Platform Unique Considerations document and the hwkeytool - Key and Certificate Management Tool document?

The IBM System z Platform 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 IBM System z Platform 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 8, see the "Documentation" section of

    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?

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 the "Online Documentation" section of

Hardware Cryptography IBMJCECCA Overview 

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

What access permissions are required to use IBMJCECCA hardware provider with ICSF on z/OS?

See the "Configuring and using IBMJCECCA" subheading of the section Hardware Cryptographic Devices for the IBM z® Platform in

    IBM z® Platform Unique Considerations

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

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 on z/OS?

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 on z/OS?

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 IBM System z Platform 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 on z/OS?

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 on z/OS?

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?

keytool is a command line utility to manage and to manipulate a keystore. On z/OS and Linux for System z, 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 8 keytool documentation

For more information about hwkeytool, see hwkeytool - Key and Certificate Management Tool, available as described in How can I get the IBM System z Platform 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. 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 a CCA return code or reason code, is that code in hexadecimal or decimal format?

When calls are made by the IBMJCECCA provider to CCA services to perform cryptographic operations, return/reason codes are displayed in error messages using the decimal values of the error codes. Return code and reason codes are documented in the "z/OS Cryptographic Services ICSF Application Programmer's Guide" (SA22-7522) for z/OS and in the "Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide" for Linux for System z.

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 IBM System z Platform 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).

For information about the internal structure of a digital certificate, see Internet RFC 3280 standard - Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile.

How can I renew a digital certificate stored in RACF on z/OS?

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 on z/OS?

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 RC = 8 RSN = 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.)

If you are using AES transport keys (also known as key encrypting keys), this might mean that you have attempted to encrypt data with a SECURE_INTERNAL_TOKEN AES transport key such as an AES EXPORTER key or an AES IMPORTER key. To encrypt data with an AES key, you must use an AES DATA key.

What does "Hardware error from call CSNBSYD RC = 8 RSN = 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.)

If you are using AES transport keys (also known as key encrypting keys), this might mean that you have attempted to decrypt encrypted data with a SECURE_INTERNAL_TOKEN AES transport key such as an AES EXPORTER key or an AES IMPORTER key. To decrypt encrypted data with an AES key, you must use an AES DATA key.

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.

What are the differences between CCAAlgorithmParameterSpec.PROTECTED and CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN and SymmetricKeyConstants.KeyType.PROTECTED and SymmetricKeyConstants.KeyType.SECURE_INTERNAL_TOKEN?

CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN replaces CCAAlgorithmParameterSpec.PROTECTED. PROTECTED is deprecated and SECURE_INTERNAL_TOKEN should be used instead. There are no functional differences between PROTECTED and SECURE_INTERNAL_TOKEN. However, the byte representation of the constants, PROTECTED and SECURE_INTERNAL_TOKEN, are not the same.

SymmetricKeyConstants.KeyType.SECURE_INTERNAL_TOKEN replaces SymmetricKeyConstants.KeyType.PROTECTED. PROTECTED is deprecated and SECURE_INTERNAL_TOKEN should be used instead. There are no functional differences between PROTECTED and SECURE_INTERNAL_TOKEN. However, the representation of the enumerations, PROTECTED and SECURE_INTERNAL_TOKEN, are not the same.

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

What does "Hardware error from call CSNBENC RC = 8 RSN = 39" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "A control vector violation occurred." In general, this means that the key that you are using is not suitable for the requested operation.

If you are using triple DES transport keys (also known as key encrypting keys), this might mean that you have attempted to encrypt data with a triple DES transport key such as a triple DES EXPORTER key or a triple DES IMPORTER key. To encrypt data with a triple DES key, you must use a triple DES DATA key or a triple DES CIPHER key.

What does "Hardware error from call CSNBENC RC = 8 RSN = 47" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "A source key token is unusable because it contains data that is not valid or undefined."

If you are using a DESede/168 key (also known as a triple DES key with 168 bit strength) for encryption, this might mean that it was imported from an ANSI TR-31 Key Block. Although IBMJCECCA correctly exports a DESede/168 key into an ANSI TR-31 Key Block, it is unable to import a DESede/168 key from an ANSI TR-31 Key Block correctly. This is a limitation of the underlying z/OS support.

What does "Hardware error from call CSNBDEC RC = 8 RSN = 39" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "A control vector violation occurred." In general, this means that the key that you are using is not suitable for the requested operation.

If you are using triple DES transport keys (also known as key encrypting keys), this might mean that you have attempted to decrypt encrypted data with a triple DES transport key such as a triple DES EXPORTER key or a triple DES IMPORTER key. To decrypt encrypted data with a triple DES key, you must use a triple DES DATA key or a triple DES CIPHER key.

What does "Hardware error from call CSNBDEC RC = 8 RSN = 47" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "A source key token is unusable because it contains data that is not valid or undefined."

If you are using a DESede/168 key (also known as a triple DES key with 168 bit strength) for decryption, this might mean that it was imported from an ANSI TR-31 Key Block. Although IBMJCECCA correctly exports a DESede/168 key into an ANSI TR-31 Key Block, it is unable to import a DESede/168 key from an ANSI TR-31 Key Block correctly. This is a limitation of the underlying z/OS support.

What does "Hardware error from call CSNBSAE RC = 8 RSN = 2154" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "At least one key token passed to this callable service does not have the required key type for the specified function." In general, this means that the key that you are using is not suitable for the requested operation.

If you are using AES transport keys (also known as key encrypting keys), this might mean that you have attempted to encrypt data with a CKDS AES transport key such as an AES EXPORTER key or an AES IMPORTER key. To encrypt data with an AES key, you must use an AES DATA key.

What does "Hardware error from call CSNBSAD RC = 8 RSN = 2154" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "At least one key token passed to this callable service does not have the required key type for the specified function." In general, this means that the key that you are using is not suitable for the requested operation.

If you are using AES transport keys (also known as key encrypting keys), this might mean that you have attempted to decrypt encrypted data with a CKDS AES transport key such as an AES EXPORTER key or an AES IMPORTER key. To decrypt encrypted data with an AES key, you must use an AES DATA key.

What does "Hardware error from call CSNDSYX returnCode 8 reasonCode 39, this DES or DESede key cannot be wrapped using a RSA cipher" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines return code 8 and reason code 39 as "A control vector violation occurred." In general, this means that the key that you are using is not suitable for the requested operation.

If you are using DES or triple DES CIPHER keys, or if you are using triple DES transport keys (also known as key encrypting keys), this might mean that you have attempted to wrap a DES or triple DES CIPHER key or a triple DES transport key with a "RSA" cipher. These types of DES and triple DES keys can only be wrapped using a "DESedeKeyWrap" cipher.

What does "Hardware error from call CSNDSYX returnCode 8 reasonCode 2016" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "The rule_array parameter contents are incorrect. One or more of the rules specified are not valid for this service OR some of the rules specified together may not be combined."

If you are using AES transport keys (also known as key encrypting keys), this might mean that you have attempted to wrap an AES transport key such as an AES EXPORTER key or an AES IMPORTER key with a "RSA" cipher without using OAEP (Optimal Asymmetric Encryption Padding). An AES transport key must be wrapped using OAEP if a "RSA" cipher is used for key wrapping.

What does "Hardware error from call CSNBKEX returnCode = 8, reasonCode = 39" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "A control vector violation occurred." In general, this means that the key that you are using is not suitable for the requested operation.

If you are using triple DES transport keys (also known as key encrypting keys), this might mean that you have attempted to wrap a CKDS or SECURE_INTERNAL_TOKEN key with a "DESedeKeyWrap" cipher using a SECURE_INTERNAL_TOKEN key that is not a triple DES EXPORTER key. For key wrapping, the "DESedeKeyWrap" cipher must be initialized with a triple DES EXPORTER key.

What does "Hardware error from call CSNBKEX returnCode = 8, reasonCode = 10012" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "A key label was supplied for a key identifier parameter. This label is the label of a key in the in-storage CKDS or the PKDS. Either the key could not be found, or a key record with that label and the specific type required by the ICSF callable service could not be found." In general, this means that a CKDS or PKDS key that you are using cannot be found in the CKDS or PKDS.

If you are using triple DES transport keys (also known as key encrypting keys), this might mean that you have attempted to wrap a CKDS or SECURE_INTERNAL_TOKEN key with a "DESedeKeyWrap" cipher using a CKDS key that is not a triple DES EXPORTER key. For key wrapping, the "DESedeKeyWrap" cipher must be initialized with a triple DES EXPORTER key.

If you are using triple DES transport keys (also known as key encrypting keys), this might mean that you have attempted to wrap a key with a triple DES EXPORTER key that is not properly formed. This can occur under the following scenario:

• exporter key 2 is exported using the "DESedeKeyWrap" cipher and exporter key 1 that has the NoCvKEK option enabled
• exporter key 2 is imported using "DESedeKeyWrap" cipher and importer key 1 that has the NoCvKEK option disabled
• The imported exporter key 2 is used to export a key using the "DESedeKeyWrap" cipher

If a transport key is exported using the "DESedeKeyWrap" cipher and an EXPORTER transport key with NoCvKEK option enabled then when it is imported the IMPORTER transport key must also have the NoCvKEK option enabled or the imported key will not be correctly formed.

What does "Hardware error from call CSNBKIM returnCode = 8, reasonCode = 39" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "A control vector violation occurred." In general, this means that the key that you are using is not suitable for the requested operation.

If you are using triple DES transport keys (also known as key encrypting keys), this might mean that you have attempted to unwrap a previously wrapped CKDS or SECURE_INTERNAL_TOKEN key with a "DESedeKeyWrap" cipher using a SECURE_INTERNAL_TOKEN key that is not a triple DES IMPORTER key. For key unwrapping, the "DESedeKeyWrap" cipher must be initialized with a triple DES IMPORTER key.

If you are using transport keys (also known as key encrypting keys) and the DESedeKeyWrap cipher to import a key, this might mean that the key was wrapped with an EXPORTER transport key with the NoCvKEK option enabled but the IMPORTER transport key you are now using has the NoCvKEK option disabled. If a key that is not type OP_DATA is exported using an EXPORTER with NoCvKEK enabled then it can only be imported using an IMPORTER with NoCvKEK enabled. If a key is type OP_DATA then it can be exported using an EXPORTER with NoCvKEK disabled and then imported using an IMPORTER transport key with the NoCvKEK enabled.

If you are importing a transport key with the NoCvKEK option, or importing a key when the IMPORTER transport key has the NoCvKEK option, you are required to specify usage of the key being imported. If you specify the incorrect usage you might get this message. For example, you might get this error if you specify that a transport key being imported is an IMPORTER when it is actually an EXPORTER.

What does "Hardware error from call CSNBKIM returnCode = 8, reasonCode = 10012" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "A key label was supplied for a key identifier parameter. This label is the label of a key in the in-storage CKDS or the PKDS. Either the key could not be found, or a key record with that label and the specific type required by the ICSF callable service could not be found." In general, this means that a CKDS or PKDS key that you are using cannot be found in the CKDS or PKDS.

If you are using triple DES transport keys (also known as key encrypting keys), this might mean that you have attempted to unwrap a previously wrapped CKDS or SECURE_INTERNAL_TOKEN key with a "DESedeKeyWrap" cipher using a CKDS key that is not a triple DES IMPORTER key. For key unwrapping, the "DESedeKeyWrap" cipher must be initialized with a triple DES IMPORTER key.

If you are using triple DES transport keys (also known as key encrypting keys), this might mean that you have attempted to unwrap a key with a triple DES IMPORTER key that is not properly formed. This can occur under the following scenario:

• importer key 2 is exported using the "DESedeKeyWrap" cipher and exporter key 1 that has the NoCvKEK option enabled
• importer key 2 is imported using "DESedeKeyWrap" cipher and importer key 1 that has the NoCvKEK option disabled
• The imported importer key 2 is used to import a key using the "DESedeKeyWrap" cipher

If a transport key is exported using the "DESedeKeyWrap" cipher and an EXPORTER transport key with NoCvKEK option enabled then when it is imported the IMPORTER transport key must also have the NoCvKEK option enabled or the imported key will not be correctly formed.

What does "Hardware error from call CSNBKIM returnCode = 8, reasonCode = 10028" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "Either the left half of the control vector in a key identifier (internal or external) equates to a key type that is not valid for the service you are using, or the value is not that of any ICSF control vector. For example, an exporter key-encrypting key is not valid in the key import callable service."

If you are using transport keys (also known as key encrypting keys) and the DESedeKeyWrap cipher to import a key and you specified usage for the key being imported, this could mean that you specified the incorrect usage. For example, you might get this error if you specify that the key being imported is a DATA key when it is actually a CIPHER key.

What does "Hardware error from call CSNBKIM returnCode = 8, reasonCode = 10036" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "Either the complete control vector (CV) in a key identifier (internal or external) equates to a key type that is not valid for the service you are using, or the value is not that of any ICSF control vector."

If you are using transport keys (also known as key encrypting keys) and the DESedeKeyWrap cipher to import a key, this might mean that the key was wrapped with an EXPORTER transport key with the NoCvKEK option disabled but the IMPORTER transport key you are now using has the NoCvKEK option enabled. If a key that is not type OP_DATA is exported using an EXPORTER with NoCvKEK disabled then it can only be imported using an IMPORTER with NoCvKEK disabled. If a key is type OP_DATA then it can be exported using an EXPORTER with NoCvKEK disabled and then imported using an IMPORTER transport key with the NoCvKEK enabled.

What does "Hardware error from call CSNBKIM returnCode = 8, reasonCode = 10056" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "You called the key import callable service. The importer key-encrypting key is a NOCV importer and you specified TOKEN for the key_type parameter. This combination is not valid."

When importing a key using an IMPORTER transport key (also known as a key encrypting key) with NoCvKEK option, you are required to specify usage of the key being imported. You might get this message if usage is not specified for the imported key.

If you are using transport keys (also known as key encrypting keys) and the DESedeKeyWrap cipher to import a key, this might mean that the key was wrapped with an EXPORTER transport key with the NoCvKEK option disabled but the IMPORTER transport key you are now using has the NoCvKEK option enabled. If a key that is not type OP_DATA is exported using an EXPORTER with NoCvKEK disabled then it can only be imported using an IMPORTER with NoCvKEK disabled. If a key is type OP_DATA then it can be exported using an EXPORTER with NoCvKEK disabled and then imported using an IMPORTER transport key with the NoCvKEK enabled.

What does "Hardware error from call CSNDSYX returnCode = 8, reasonCode = 2154" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "At least one key token passed to this callable service does not have the required key type for the specified function." In general, this means that the key that you are using is not suitable for the requested operation.

If you are using AES transport keys (also known as key encrypting keys), this might mean that you have attempted to wrap a CKDS or SECURE_INTERNAL_TOKEN key with an "AESKeyWrap" cipher using an AES IMPORTER key. For key wrapping, the "AESKeyWrap" cipher must be initialized with an AES EXPORTER key.

What does "Hardware error from call CSNDSYX returnCode = 8, reasonCode = 10040" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "Key identifiers contain a version number. The version number in a supplied key identifier (internal or external) is inconsistent with one or more fields in the key identifier, making the key identifier unusable."

If you are using AES transport keys (also known as key encrypting keys), this might mean that you have attempted to wrap a CKDS or SECURE_INTERNAL_TOKEN key with an "AESKeyWrap" cipher using a key that is not an AES EXPORTER key. For key wrapping, the "AESKeyWrap" cipher must be initialized with an AES EXPORTER key.

What does "Hardware error from call CSNDSYI2 returnCode = 8, reasonCode = 2154" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "At least one key token passed to this callable service does not have the required key type for the specified function." In general, this means that the key that you are using is not suitable for the requested operation.

If you are using AES transport keys (also known as key encrypting keys), this might mean that you have attempted to unwrap a previously wrapped CKDS or SECURE_INTERNAL_TOKEN key with an "AESKeyWrap" cipher using an AES EXPORTER key. For key unwrapping, the "AESKeyWrap" cipher must be initialized with an AES IMPORTER key.

What does "Hardware error from call CSNDSYI2 returnCode = 8, reasonCode = 10040" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "Key identifiers contain a version number. The version number in a supplied key identifier (internal or external) is inconsistent with one or more fields in the key identifier, making the key identifier unusable."

If you are using AES transport keys (also known as key encrypting keys), this might mean that you have attempted to unwrap a previously wrapped CKDS or SECURE_INTERNAL_TOKEN key with an "AESKeyWrap" cipher using a key that is not an AES IMPORTER key. For key unwrapping, the "AESKeyWrap" cipher must be initialized with an AES IMPORTER key.

What does "Hardware error from call CSNBKRC2 returnCode 12 reasonCode 0" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "CKDS Key Record Create2 was called to add a variable-length key record to a fixed-length CKDS. A variable-length symmetric key token can only be added to a CKDS that supports variable-length records."

If you are using AES transport keys (also known as key encrypting keys), this might mean that you are using a Cryptographic Key Data Set (CKDS) that only supports fixed-length records. A CKDS that supports variable-length records is required for CKDS type AES transport keys. Please refer to the section titled Converting a CKDS from fixed length to variable length record format in the ICSF System Programmer's Guide for more information or contact your system administrator.

What does "Hardware error from call CSNBT31I returnCode 8 reasonCode 90" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "Access is denied for this request. This is due to an access control point in the domain role either being disabled or an access control point being enabled that restricts the use of a parameter such as a rule array keyword."

If you are unwrapping (importing) a transport key (also known as a key encrypting key) from a TR-31 key block then this message might mean that the required access control points have not been enabled. The access control points can be enabled by your ICSF administrator using the TKE workstation. The following access control points are required to unwrap a transport key from a TR-31 key block:

• Permit K0:E to EXPORTER/OKEYXLAT
• Permit K0:D to IMPORTER/IKEYXLAT

What does "Hardware error from call CSNBT31I returnCode 8 reasonCode 2016" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "The rule_array parameter contents are incorrect. One or more of the rules specified are not valid for this service OR some of the rules specified together may not be combined."

If you are unwrapping a key using an instance of DESedeTR31KeyWrap, this might mean that the usage specified (or defaulted) for the key being imported is not correct. The default key usage for a key being imported from a TR-31 Key Block is data encryption/decryption. For example, you might see this error if you did not specify key usage and the key is actually a transport key or if you specified the wrong type of transport key (such as EXPORTER when the key is actually an IMPORTER).

What does "Hardware error from call CSNBT31I returnCode 8 reasonCode 2131" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "The MAC validate step failed for a parameter. This may result from tampering, corruption, or attempting to use a different key to validate the MAC from the one used to generate it."

If you are unwrapping a key using an instance of DESedeTR31KeyWrap, this might mean that the IMPORTER transport key (also known as an IMPORTER key encrypting key) is not correct. The IMPORTER transport key must have the same key material as the EXPORTER transport key that was used to create the TR-31 Key Block.

What does "Hardware error from call CSNBT31I returnCode 8 reasonCode 2227" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "The triple-length key cannot be imported because the TR-31 key block does not include a CCA control vector."

If you attempt to import a TR-31 key block containing a DESede key with 168 bit strength you might see this message if any of the following are true:

• you are using an IMPORTER transport key with NoCvKEK enabled
• the TR-31 key block was created using an EXPORTER transport key with NoCvKEK enabled
• the TR-31 key block was created on a non-CCA platform and it contains a control vector not valid for a CCA platform

What does "Hardware error from call CSNBT31X returnCode 8 reasonCode 39" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines return code 8 and reason code 39 as "A control vector violation occurred." In general, this means that the key that you are using is not suitable for the requested operation.

If you are wrapping a key using an instance of DESedeTR31KeyWrap and you specified key usage for the key being exported, this might mean that the key usage you specified does not match the key usage specified when the key was created.

If you are wrapping a key using an instance of DESedeTR31KeyWrap and you did not specify key usage for the key being exported, the exported key usage defaulted to data encryption/decryption. You might get this error if the key being exported is actually a transport key (an IMPORTER or EXPORTER). In this case you must explicitly specify the correct key usage for the key being exported.

What does "Hardware error from call CSNBT31X returnCode 8 reasonCode 90" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "Access is denied for this request. This is due to an access control point in the domain role either being disabled or an access control point being enabled that restricts the use of a parameter such as a rule array keyword."

If you are wrapping (exporting) a transport key (also known as a key encrypting key) in a TR-31 key block then this message might mean that the required access control points have not been enabled. The access control points can be enabled by your ICSF administrator using the TKE workstation. The following access control points are required to wrap a transport key in a TR-31 key block:

• Permit EXPORTER/OKEYXLAT to K0:E
• Permit IMPORTER/IKEYXLAT to K0:D

What does "Hardware error from call CSNBT31X returnCode 8 reasonCode 72" 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."

The format defined for a TR-31 key block allows exactly two decimal digits for the number of optional blocks. If padding is needed, CSNBT31X will add one optional data block for padding. In other words, in some cases the maximum number of optional data blocks that can be added by an application is 98. If you add 99 optional data blocks when creating a TR-31 key block then you will see this error if padding is needed.

What does "Hardware error from call CSNBT31O returnCode 8 reasonCode 345" mean?

The ICSF Application Programmer's Guide (SA22-7522) defines this error as "Insufficient storage space exists for the data in the data block buffer."

The format defined for a TR-31 key block allows exactly 2 decimal digits for the number of optional blocks. You will see this error if you attempt to add more than 99 optional data blocks when creating a TR-31 key block.

What does "Hardware error from call CSNBT31O returnCode 8 reasonCode 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."

The format defined for a TR-31 key block allows exactly 2 bytes for the length in hexadecimal of an optional block, for a maximum of 255 bytes. Two bytes are used for the optional data block ID, two bytes are used for the block length. Therefore, you will see this error if you attempt to add an optional block with data larger than 251 bytes when creating a TR-31 key block.

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 on z/OS?

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 for z/OS

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

    z/OS 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 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();

What is the difference between PlatformAccessControl.checkPermission() and PlatformAccessControl.checkMyPermission()?

The implementation of PlatformAccessControl.checkPermission() requires the current user to either have READ access to BPX.SERVER or to have superuser status, whereas PlatformAccessControl.checkMyPermission() only requires that the current user has a task-level Access Control Environment Element (ACEE). A user can generate a task-level ACEE via a call to ThreadSubject.doAs(). However, ThreadSubject.doAs() has the same restrictions as PlatformAccessControl.checkPermission(). Therefore, PlatformAccessControl.checkMyPermission() should only be used when a task-level ACEE is already present. Otherwise PlatformAccessControl.checkPermission() should be used.

The following example demonstrates using ThreadSubject.doAs to generate an ACEE for checkMyPermission:

    /**
     * Calls PlatformAccessControl.checkMyPermission() inside a ThreadSubject.doAs() call
     */
    private void checkMyPermission_Example_NoACEE() {
        LoginContext lc = new LoginContext("MY_LOGINCONTEXT");

        lc.login();
        Subject subject = lc.getSubject();

        PrivilegedAction<Object> action = new PrivilegedAction<Object>() {
            @Override
            public Object run() {
                PlatformReturned pr = PlatformAccessControl.checkMyPermission("MY_CLASS", "MY_RESOURCE_NAME", PlatformAccessLevel.READ);

                if(pr == null)
                    return "SUCCESS";
                else
                    return "FALSE";

            }
        };

        String result = (String) ThreadSubject.doAs(subject, action);

        lc.logout();

    }

However, if the current user has already obtained an ACEE, PlatformAccessControl.checkMyPermission() can simply be called as in the following example:

    /**
     * Calls PlatformAccessControl.checkMyPermission() when the user already has an ACEE
     */
    private void checkMyPermission_Example_ACEE() {
    	PlatformReturned pr = PlatformAccessControl.checkMyPermission("MY_CLASS", "MY_RESOURCE_NAME", PlatformAccessLevel.READ);
    	String result;

    	if (pr == null)
    	    result = "SUCCESS";
    	else
    	    result = "FALSE";
    }

The PlatformReturned object has also been modified to provide a descriptive error message in the case of a failure in checkMyPermission(). The error message can be obtained as in the following example:

    /**
     * Calls PlatformAccessControl.checkMyPermission() and prints out an error message
     */
    private void checkMyPermission_ErrorMessage() {
    	PlatformReturned pr = PlatformAccessControl.checkMyPermission("BADCLASS", "BAD_RESOURCE_NAME", PlatformAccessLevel.READ);
    	String errorMessage;

    	if (pr != null){
    	    errorMessage = pr.stringRet;
    	    System.out.println(errorMessage);
    	}

    }

---

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.

---

© Portions Copyright 2003, 2019 IBM Corporation. All rights reserved. © Portions Copyright 2003, 2019 Oracle and/or its affiliates. All rights reserved.