IBMJCECCA frequently asked questions
The IBMJCECCA provider extends the JCE capability with the use of hardware cryptography by using the IBM Common Cryptographic Architecture (CCA) APIs.
On z/OS®, the CCA interface is provided by ICSF. The IBMJCECCA provider gives Java™ programmers the significant security advantages that are afforded by secure hardware cryptographic devices with minimal changes to existing Java applications. Usually, the only changes that are needed to a Java application are that method invocations that specify the software JCE provider are changed to specify the IBMJCECCA provider. If method invocations accept the default JCE provider, you need to configure only the Java VM so that the IBMJCECCA provider has precedence over the software JCE provider. For more information about configuring provider precedence, see Installing security providers.
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 fails. Unless the application that makes the request does its own failover, there is no retry that calls a software implementation of the same service.
What access permissions are required to use IBMJCECCA hardware provider with ICSF on z/OS?
How do I set up my RACF key ring 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 that are needed to access your key ring as a Java keystore. The authority of your RACF administrator is required to issue the necessary RACDCERT commands. More information about the JCECCARACFKS and JCERACFKS keystores is provided in Java Security on z/OS - The Complete View, SG24-7610.
What are the differences between JCERACFKS and JCECCARACFKS keystores on z/OS?
- JCERACFKS keystores are supported by the IBMZSecurity provider and JCECCARACFKS keystores are supported by the IBMJCECCA provider.
- These keystores can contain only keys that are supported by the provider, so the following
restrictions apply:
- A keyring that contains one or more ICSF (hardware) and RACF (software) keys can be represented only as a JCECCARACFKS keystore.
- A keyring that contains only RACF (software) keys can be represented either as a JCERACFKS keystore or as a JCECCARACFKS keystore.
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 that are 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?. To do this by using the hwkeytool utility, How do I copy entries from one keystore to another using hwkeytool?. The JCECCAKS keystore supports both symmetric keys and asymmetric keys and certificates but 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, copy the keys and certificates that are 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?. To do this by using the hwkeytool utility, 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?
- Open the source keystore.
- Load the source keystore.
- Open the destination keystore.
- If the destination keystore exists, load the destination keystore.
- For each entry in the source keystore, do the following actions:
- Extract the key and certificate.
- Create an entry in the destination keystore to hold the extracted key and certificate.
- Store the destination keystore.
How do I copy entries from one keystore to another using hwkeytool?
- The following example illustrates the hwkeytool command to import a keystore
when all 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 a key entry has a different password from the keystore, you must import each key entry
separately. The following example 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
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 Java Security on z/OS - The Complete View, SG24-7610.
What are the differences between JCECCAKS and JCECCARACFKS keystores on z/OS?
- The JCECCAKS keystore can be used to store all key types that are supported by the IBMJCECCA provider but the JCECCARACFKS keystore can be used to store only key types that are 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 but 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 closely, making it easier for use by Java programmers.
When (and how) can I control whether cryptographic 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 the ibm.DES.usehdwr.size
system property and how do I use
it?
ibm.DES.usehdwr.size
is a Java system
property that is 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 that is passed for encryption and decryption is less than the value
of this property, IBMJCECCA performs the operation in software. The
ibm.DES.usehdwr.size
system property has the following notable values:- The default value is 60.
- If you set the value to 0, hardware cryptography is used, regardless of data size.
- If you set the value to -1, software cryptography is used, regardless of data size.
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 that is 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 cryptographic 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 by using one or more calls to update() followed by a call to doFinal(), the decision is based on the size of the first data that is processed. For example, if you are encrypting or decrypting the contents of a tape image, the tape header is smaller than the subsequent data blocks. If the data blocks are large, you might prefer that the encryption or decryption is processed by using hardware. However, if your application passes first the tape header data 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?
The tool keytool is a command line utility for managing and manipulating a keystore. On z/OS, keytool is provided for keystore types that are supported by the SUN provider, hwkeytool is provided for keystore types that are supported by the IBMJCECCA provider, and zseckeytool is provided for keystore types that are supported by the IBMZSecurity provider. All three tools include the functions that are defined by the Java specification, and include extensions to that specification. For more information about keytool, see keytool documentation in the Oracle documentation. For more information about hwkeytool, see The hwkeytool key and certificate management utility.
What information should I collect before contacting the IBM service team with a problem related to the hardware provider (IBMJCECCA)?
java -version
If the service team cannot
resolve the issue from your description of the failing scenario and the symptoms of the failure, the
next step is to get trace data for the failure. To generate the trace, specify the
-Djava.security.auth.debug=all
option when you run your application. This option
causes trace data to be printed to stderr. To capture the data, 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 can give you instructions on how to transmit it.What does NoSuchProviderException mean?
Service.getInstance(algorithm,provider)
The
installation instructions that are provided in Installing security providers can be used to
install any provider if you know the package and class name.What does NoSuchAlgorithmException mean?
Service.getInstance(algorithm,provider)
This
error also occurs when an application calls the following method and none of the installed providers
support the specified algorithm for the specified Service.
Service.getInstance(algorithm)
Verify that you specified the algorithm, or the algorithm and the provider name,
correctly.How can I query what algorithms are supported by a particular 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. For more information, see SDK Security policy files
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. For more information, see SDK Security policy files.What does it mean when hwkeytool returns InvalidAlgorithmParameterException: Params must be instance of RSAKeyGenParameterSpec?
-storetype
option on
your hwkeytool command. Unless you 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, specify one of the following options, depending on which
type of keystore you prefer:- For a file-based keystore, specify:
-storetype JCECCAKS
- For a RACF-based keystore,
specify:
-storetype JCECCARACFKS
- For a PKCS11 keystore,
specify:
-storetype PKCS11 -keystore NONE
What does it mean when hwkeytool returns java.io.IOException: Invalid keystore format?
This message might mean that the keystore that you specified with the -keystore
option is not the type that you specified with the -storetype
option. For example,
you get this message if you specify a JCEKS keystore with the -keystore
option but
specify JCECCAKS with the -storetype
option. The message might also mean that you
created a keystore by using one Java version and are
attempting to use it in an earlier Java version. 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 that is 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 that was created with the new
level of protection, you get this message. If you created a keystore that has the new protection and
need to share its contents with an older Java level, you must
migrate the entries from the new keystore to a keystore that was 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 user ID.
What does it mean when hwkeytool returns java.lang.Exception: Key pair not generated, alias <mykey> already exists?
mykey
is used. This message means that the keystore already
contains an entry with the alias mykey
. This entry might have been created by using
hwkeytool either without the -alias option or with the
-alias mykey option specified. This entry also might have been created
programatically by 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 you create 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 by using
the -keystore option.
hwkeytool -delete -alias mykey
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 and reason codes are displayed in error messages that use 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.
How does performance compare when generating random numbers by using the software JCE providers compared to the IBMJCECCA provider?
Performance implications might be observed when you use the hardware-based random number generator instead of the random number generator in the software JCE providers. For more information, see the technote titled Random Number Generation operations performance using Hardware Crypto (IBMJCECCA) Technote.
Where can I find information about digital certificates?
For information about the internal structure of a digital certificate, see Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile.
More information is available in this white paper: Symantec VeriSign Authentication Services.
How can I renew a digital certificate that is 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 that is stored in RACF be shared among users on z/OS?
For information about sharing a private key that is stored in RACF, see Sharing a private key in a key ring in the documentation for your version of z/OS.
When I use an AES Cipher in GCM mode, how is 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 that is 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 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 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 contains 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 that was specified for encryption.
For information about Galois/Counter Mode (GCM), see When I use an AES Cipher in GCM mode, how is 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?
If no Additional Authentication Data (AAD) is specified to the AES Cipher in GCM mode then the authentication tag is computed on the clear text alone. Even with no additional authentication data, this behavior provides some authentication of the clear text that is 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 that is returned contains 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 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 were not altered. This message authentication is available by using a GCM mode cipher with no text for encryption.
If the message is specified as Additional Authentication Data (AAD) and no text is specified for encryption, the byte[] cipherText buffer contains 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 (AAD) and the byte[] cipherText buffer that is 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.