IBMJCECCA use of hardware
In the cryptography environment, there are multiple ways to take advantage of cryptographic hardware. The IBMJCECCA provider supports multiple types of hardware use.
After an asymmetric key pair or symmetric key is generated, it is tied to the hardware type that
was used to generate it. The type that is supported for asymmetric key pairs is PKDS
. The two
types that are supported only for symmetric keys are CKDS
and SECURE_INTERNAL_TOKEN
.
Type CLEAR
is supported both for asymmetric key pairs and for symmetric keys. Each type is
described in the following sections. The types of hardware use make tradeoffs between increased
security and increased performance but in general, any type of hardware cryptographic use is more
secure than similar cryptographic functions that are provided by a provider that is implemented to
use only software cryptography.
PKDS hardware key pairs
These keys are known in the CCA architecture as Public Key Algorithm (PKA) key tokens. In this case the PKA key token is subsequently stored in a secure data area. On z/OS®, the secure data area is the ICSF PKDS data set.
The hardware can be used with key pairs to provide increased security and also to take advantage of multiple hardware devices on the system. Key pairs that are generated by using this high level of security are called PKDS key pairs. When a PKDS key pair is generated, the private key is encrypted by using the system's primary key, and the key pair is stored in a system key storage area. On z/OS, this key storage area is a RACF®-protected data set that is managed by ICSF. On z/OS, clear key values can be used that are stored within the PKDS. The clear text version of this key can never be viewed or retrieved. What is stored in the JCE keystore file or returned to the application at key pair generation time is only a reference to the private key, called a label. Because the key is stored in a key storage area instead of on a particular hardware device, cryptographic operations that use PKDS key pairs can take advantage of multiple cryptographic hardware devices. When a cryptographic operation request is received, the private key is decrypted by the CCA software layer and the request is submitted to the next available cryptographic device.
The PKDS key type provides the highest level of security that is supported by the IBMJCECCA provider. Operations that use PKDS key types are more secure and generally slower than similar operations that use the CLEAR type key pairs.
CKDS hardware symmetric keys
These keys are known in the CCA architecture as internal symmetric key tokens. In this case, the internal symmetric key token is subsequently stored in a secure data area. On z/OS, the secure data area is the ICSF CKDS data set.
The hardware can be used with symmetric keys to provide increased security and to take advantage of multiple hardware devices on the system. Symmetric keys that are generated by using this high level of security are called CKDS keys. When a CKDS key is generated, it is encrypted by using the system's primary key and the resulting key token is stored in a system key storage area. On z/OS, this key storage area is a RACF-protected data set that is managed by ICSF. The clear text version of this key can never be viewed or retrieved. What is stored in the JCE keystore or returned to the application at key generation is only a reference to the key, called a label. Because the key is stored in a key storage area instead of on a particular hardware device, cryptographic operations that use CKDS keys can take advantage of multiple cryptographic hardware devices. When a cryptographic operation request is received, the key is decrypted by the CCA software layer and the request is submitted to the next available cryptographic device.
When running on z/OS, the system primary key, which is used to protect the key material, can only be changed by using the ICSF component of z/OS. When the system primary key is changed, all the key entries are re-encrypted such that the keys that it contains are encrypted by using the new system primary key. This behavior ensures that CKDS type keys remain usable even if the system primary key is changed.
The CKDS key type provides the highest level of security that is supported by the IBMJCECCA provider for symmetric keys. Operations that use CKDS key types are the most secure symmetric key operations that are supported by the IBMJCECCA provider.
Note that when running on z/OS, ICSF version HCR7780 or higher is required for creating CKDS hardware symmetric keys.
SECURE_INTERNAL_TOKEN hardware symmetric keys
These keys are known to CCA architecture as internal symmetric key tokens.
The hardware can be used with symmetric keys to provide increased security and to take advantage of multiple hardware devices on the system. Symmetric keys that are generated by using this level of security are called SECURE_INTERNAL_TOKEN keys. When a SECURE_INTERNAL_TOKEN key is generated, it is encrypted by using the system's primary key. What is stored in the JCE keystore or returned to the application at key generation is only the encrypted key, called a key token. Because the system primary key is never available outside the CCA software layer, a SECURE_INTERNAL_TOKEN key is more secure than a CLEAR key. When a cryptographic operation request is received, the key is decrypted by the CCA software layer and the request is submitted to the next available cryptographic device.
When running on z/OS, the system primary key, which is used to protect the key material, can only be changed using the ICSF component of z/OS. SECURE_INTERNAL_TOKEN keys are encrypted by using the host primary key then stored outside the key storage area, that is, outside the control of CCA spaces. This behavior means that if the system primary key is changed, any SECURE_INTERNAL_TOKEN key that was created by using the old system primary key becomes unusable and data that was encrypted by using it cannot be decrypted. For this reason, SECURE_INTERNAL_TOKEN keys are recommended only for short-term use. Do not use these keys for data that will be encrypted, then decrypted at a much later date.
The SECURE_INTERNAL_TOKEN key type has the highest level of security that is supported by the IBMJCECCA provider for symmetric keys. Operations that use SECURE_INTERNAL_TOKEN key types are more secure and generally slower than similar operations that use CLEAR keys.
CLEAR hardware key pairs and symmetric keys
These keys are known to the CCA architecture as clear keys.
The hardware can also be used to accelerate the performance of the cryptographic operation. The
lowest level of hardware security is a CLEAR
key pair or symmetric key. When the key pair or
symmetric key is generated as type CLEAR
, the keypair or symmetric key is stored in a clear
and unprotected representation. This clear key pair or symmetric key can be used by the application
to perform cryptographic operations on any CCA-capable hardware cryptographic device that the system
supports. There is no overhead for retrieving the key from the key storage area, no overhead for
decrypting the key using the primary key, and no requirement for the cryptographic operation to be
processed by a specific hardware device.
The CLEAR key type is the fastest type that is supported by the IBMJCECCA provider, but it is also the least secure.
Key storage overview
All three types of hardware key pair and all three types of symmetric key that are supported by the IBMJCECCA provider can be used by any application. For CKDS and PKDS keys, the application has only a label. For SECURE_INTERNAL_TOKEN keys, the application has only an encrypted token. For CLEAR keys, the application has a clear representation of the key material. The IBMJCECCA provider accepts key labels, key tokens, and clear representations of keys interchangeably and treats all the same as actual keys. Key labels, key tokens, and clear representations of keys can be stored by the application by using whatever mechanism it chooses.
The IBMJCECCA provider includes a Java™ keystore (type JCECCAKS) that can be used to store any of these representations of keys. A JCECCAKS keystore provides an added level of security, allowing the keys stored in it to be encrypted by using passwords before they are stored in the keystore file. This behavior means that if you choose CLEAR keys or SECURE_INTERNAL_TOKEN keys for performance reasons, they can be stored in keystore entries that are password protected. While password protection is provided for all keystore entries, regardless of the type of key that is stored in the entry, it is not as important for PKDS and CKDS keys. This difference is because, for PKDS and CKDS keys, the keystore entry contains only a key label and no sensitive key information.
Key generation and storage
Key generation can be accomplished by using either the keytool utility that is included with the IBMJCECCA provider (hwkeytool) or JCE APIs. The hwkeytool utility enables you to generate symmetric keys and key pairs then store them in a keystore file of type JCECCAKS. The JCE APIs allow you to generate symmetric keys and key pairs in an application then, at the discretion of the application, also store them in a keystore of type JCECCAKS.
RSA signature and verification
The IBMJCECCA provider supports digital signature and verification with the available RSA, DSA (note that DSA is only supported on z800 and z900 hardware) and ECDSA (note that ECDSA is only supported on Crypto Express 3 Coprocessor (CEX3C) and newer cryptographic coprocessor cards) algorithms. This implementation moves all algorithm processing to the installed cryptographic hardware device. RSA is a relatively compute intensive algorithm, so this moves a significant portion of the CPU instructions off the main processor and onto the cryptographic hardware device. The cryptographic hardware processes this work on a secure card, making it much harder to capture and compromise the sensitive material involved. The cryptographic hardware is also much faster than software cryptographic processing.
An additional benefit provided by cryptographic hardware is the choice of two levels of security, CLEAR key pairs and PKDS based key pairs. Cryptographic hardware capabilities increase the base security of the operation (by having the hardware process the algorithm and data), reduce the load on general purpose CPs, potentially increase the throughput rate of the request, and (optionally) permit use of more secure key pairs.
DSA signature and verification
Note that the DSA algorithm is only supported on hardware cryptographic devices for z800 and z900 machines.
DSA signature and verification by using hardware cryptographic devices is available only in Cryptographic Coprocessor Facility (CCF) hardware.
An additional restriction is that, due to the hardware capabilities for DSA in the CCF hardware, the only type of key pair that is available for DSA is PKDS. The CCF hardware does not support CLEAR DSA key pairs.
ECDSA signature and verification
Elliptic Curve Cryptography (ECC) is an encryption system that uses the properties of elliptic curves to provide the same functionality as other public cryptographic systems. The primary benefit provided by ECC is reduced key sizes, so it is therefore faster and less compute intensive than equivalent RSA operations.
Note that the ECDSA algorithm is supported only on Crypto Express 3 Coprocessor (CEX3C) and newer cryptographic coprocessor cards.
MD2, MD5, and SHA hashing algorithms
Hashing algorithms are not as compute intensive as the RSA, DSA and ECDSA algorithms, so it is not always better to use hardware devices to perform them. This is because the overhead of using the hardware device can outweigh the potential performance gains. Further, the security of performing hashing algorithms on hardware is not substantially better than performing the same operations in software, because the hash is subsequently used in a more secure RSA, DSA or ECDSA sign or verify operation. For these reasons, many hardware cryptography devices don't support hashing algorithms and sometimes, the CCA layer performs the hashing algorithm in software rather than hardware.
The IBMJCECCA provider calls the CCA interfaces to perform MD5, SHA-1, SHA-256, SHA-384, and SHA-512 hashing, and performs MD2 hashing by using software. In some cases, the IBM CCA layer performs the MD5 hash by using software instead of hardware.
- SHA-256 is supported only on z9® and newer zSeries processor families.
- SHA-384 and SHA-512 are supported only on z10 and newer zSeries processor families.
- The alias names "SHA-3" and "SHA3", which refer to the SHA384 implementation in IBMJCECCA, were deprecated in Java 8. Use "SHA384" or "SHA-384" as replacement alias names.
- The alias names "SHA-5" and "SHA5", which refer to the SHA512 implementation in IBMJCECCA, were deprecated in Java 8. Use "SHA512" or "SHA-512" as replacement alias names.
Random number generation
The IBM CCA hardware devices provide a
true random number generator. This is an improvement over the java.util.Random
class, which provides a pseudo random number generation capability that is based on salting a random
number operation with some value. The IBMJCECCA provider takes advantage of the true random number
generation capabilities in the cryptographic hardware and makes them available to applications with
the SecureRandom
class. Note that there are performance implications when using
this hardware-based random number generator instead of the random number generator in a software
provider. For more information, see the technote titled Random Number Generation operations performance using Hardware Crypto (IBMJCECCA)
Technote.
ibm.hwrandom.useicsfcache
and ibm.hwrandom.cachesize
, which can be
used to configure a caching implementation of the CCA hardware random number generator. When the
IBMJCECCA provider is loaded, these properties are used to configure the default
SecureRandom implementation for the remainder of the JVM lifespan, unless the
property states are changed programatically and the IBMJCECCA provider is reloaded. By using the
caching implementation, you can experience improved performance. The potential for performance
improvement depends on the type of workload that is run. Experimentation with the cachesize property
might be necessary to see what benefits (if any) are visible for any given workload.ibm.hwrandom.useicsfcache=[true|false]
-
Used to specify caching of secure random numbers that are fetched from CCA APIs. To set the SecureRandom implementation to use caching, set the
ibm.hwrandom.useicsfcache
java property to true. For example:java -Dibm.hwrandom.useicsfcache=true MyApplication
ibm.hwrandom.cachesize=[size]
-
Used to specify the size ( in bytes ) of the cache for caching secure random numbers fetched from CCA APIs. If a user enables CCA caching they can optionally specify the desired size of the cache (in number of bytes). For example:
java -Dibm.hwrandom.cachesize=14400 -Dibm.hwrandom.useicsfcache=true MyApplication
If not specified, the default cache size is 14400 bytes. This property must be set to a value that is an integer value greater than 0. If the
ibm.hwrandom.useicsfcache
Java property is not set totrue
, theibm.hwrandom.cachesize
Java property is ignored.