Data Encryption Standard (DES) keys and operations
Keys
The hardware JCE implementation (IBMJCECCA) extends the DES key that is available in the software JCE implementation. In the software JCE implementation, the DES key material is stored in the key object. The IBMJCECCA implementation extends this by adding the following alternative representations:
-
A DES key that was previously stored in the CCA key storage area. The key object contains the CCA key storage area label for the key.
The following example illustrates creating a DES key object for a key that is already stored in the CCA key storage area with the label "MY.ENCRYPT.ED.DESKEY", then (for purposes of illustration) deleting the CCA key storage area entry.
On z800 and z900 machines, a key object that contains the label for an encrypted DES key can be used for CBC mode encryption and decryption with the IBMJCECCA provider.// create a key object for an existing entry // (No checking is done to verify that the entry exists, or // that the key it contains is actually a DES key.) // SecretKeyFactory desKeyFactory = SecretKeyFactory.getInstance("DES", "IBMJCECCA"); KeyLabelKeySpec spec = new KeyLabelKeySpec("MY.ENCRYPT.ED.DESKEY"); SecretKey key = desKeyFactory.generateSecret(spec); // delete the entry from the key storage area // (An exception is thrown if the key entry does not exist.) // key.deleteCKDSEntry(); // // Note that, in this example, the Java key object still // exists, but the key entry it represents has been deleted. // Any attempt to use the object
key
will cause an exception // containing a hardware return code and reason code. //On the z890 and z990 and newer zSeries processors, a key object that contains the label for a clear DES key can be used for CBC mode, CFB mode, or ECB mode encryption and decryption with the IBMJCECCA provider. This environment also supports using a key object that contains the label for an encrypted DES key for CBC mode encryption and decryption with the IBMJCECCA provider.
A key object that contains the label for an encrypted DES key can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host.
A DES key that was wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object contains a clear DES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object contains a DES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object contains the label for an entry in the system secure key storage area that contains a DES hardware token.
For more information about wrapping and unwrapping DES keys, see RSA keys.
-
A DES key that is generated by an IBMJCECCA call to the underlying hardware. The key object contains a hardware token. This token contains the key encrypted with the host primary key. The key material for this type of key is never resident in system memory in clear form.
The following example illustrates generating a DES key object that contains a hardware key token:
A key object that contains a DES hardware token can be used for CBC mode encryption and decryption with the IBMJCECCA provider.// create a new key token and a key object to represent it // CCAAlgorithmParameterSpec ccaAlgParmSpec = new CCAAlgorithmParameterSpec(); KeyGenerator keyGen = KeyGenerator.getInstance( "DES", "IBMJCECCA" ); keyGen.init( ccaAlgParmSpec, null ); Key desKey = keyGen.generateKey();
A key object that contains a DES hardware token can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host.
A DES key that was wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object contains a clear DES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object contains a DES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object contains the label for a CCA key storage entry that contains a DES hardware token.
For more information about wrapping and unwrapping DES keys, see RSA keys.
-
A DES key that is generated by an IBMJCECCA call to the underlying hardware then stored in the CCA key storage area. The key object contains the label for the new CCA key entry. The CCA key entry holds a token that contains the key encrypted with the host primary key. The key material for this type of key is never resident in system memory in clear form.
The following example illustrates generating a protected DES key token, storing it in a new CCA key entry with an automatically generated label, and creating a key object that contains the label for the CCA key entry.
The following example illustrates generating a protected DES key token, storing it in a new CCA key entry with the label "ADES.TOKEN.INCKDS", and creating a key object that contains the label for the CCA key entry.// create a new CCA key entry and a key object to represent it // CCAAlgorithmParameterSpec ccaAlgParmSpec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS); KeyGenerator keyGen = KeyGenerator.getInstance("DES", "IBMJCECCA"); keyGen.init( ccaAlgParmSpec, null ); Key thisKey = keyGen.generateKey();
A key object that represents a DES hardware token can be used for CBC mode encryption and decryption with the IBMJCECCA provider.// create a new CCA key entry and a key object to represent it // CCAAlgorithmParameterSpec ccaAlgParmSpec = new CCAAlgorithmParameterSpec(CCAAlgorithmParameterSpec.CKDS, "ADES.TOKEN.INCKDS"); KeyGenerator keyGen = KeyGenerator.getInstance("DES", "IBMJCECCA"); keyGen.init(ccaAlgParmSpec,null); Key thisKey = keyGen.generateKey();
A key object that represents a DES hardware token can be passed to an IBMJCECCA RSA Cipher object to be wrapped for export to another host.
A DES key that was wrapped by an RSA Cipher can be passed to the IBMJCECCA RSA Cipher to be unwrapped for import from another host. By default, the resulting (unwrapped) key object contains a clear DES key. If a CCAAlgorithmParameterSpec is created with no type specified, or with type CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object contains a DES hardware token. If a CCAAlgorithmParameterSpec is created with type CAAlgorithmParameterSpec.CKDS, and the RSA Cipher is initialized with this CCAAlgorithmParameterSpec, the resulting (unwrapped) key object contains the label for a CCA key entry that contains a DES hardware token.
For more information about wrapping and unwrapping DES keys, see RSA keys.
Operations
The hardware JCE implementation (IBMJCECCA) of DES does not change any of the APIs that are available in software JCE implementation. Therefore, an application that used the DES capabilities of the software JCE implementation does not require modification to use the IBMJCECCA provider, except for specific references to the provider. For example, if a call to the getInstance() API specified the IBMJCE provider, you must change the call to specify the IBMJCECCA provider instead.
Although all DES ciphers are available in the IBMJCECCA provider, they are not all available in the hardware devices. The hardware cryptographic devices support the Cipher Block Chaining (CBC), Cipher feedback (CFB), Output Feedback (OFB), and Electronic Code Book (ECB) versions of DES. That is, all the DES ciphers are supported by the IBMJCECCA provider, but only CBC, CFB, OFB, and ECB modes can use hardware cryptography.
It is not always more efficient to use hardware cryptography instead of software cryptography.
The DES algorithm is not as compute intensive as some asymmetric algorithms such as RSA. For smaller
data sizes, software DES cryptography can be faster than hardware cryptography. So, software
versions of DES with CBC, CFB, OFB, and ECB were also implemented in the IBMJCECCA provider. For
small amounts of data, software DES (CBC, CFB, OFB, or ECB) is sometimes faster than hardware DES
(CBC, CFB, OFB, or ECB) cryptography. The exact size of the data at which the performance tradeoff
is found varies from system to system. Therefore, a clip level
is used to specify the data
size at which hardware cryptography is used. Any data length that is smaller than the configured
clip level uses software cryptography. The clip level is a system property called
ibm.DES.usehdwr.size
, which has a default value of 60. Thus, by default, any DES
CBC, CFB, OFB, or ECB processing where the data size less than 60 bytes is performed by using
software cryptography and any data size that is 60 bytes or greater is performed by using hardware
cryptography. For ciphers other than DES CBC, CFB, OFB, and ECB, this system property has no
function.
You can adjust the clip level by changing the system property. If you set the system property to 0, all DES CBC, CFB, OFB, and ECB processing is performed by using hardware cryptography. If you set the system property to -1, all DES CBC, CFB, OFB, and ECB processing is performed by using software cryptography. This system property applies to both DES and triple DES CBC, CFB, OFB, and ECB processing.
The data size comparison to the clip level is done when the first data is passed to the cipher for encryption or decryption. For example, consider an application that decrypts the contents of a tape by reading each record then passing it to the cipher before the application reads the next record. In this case, the first record that is passed to the cipher object is the tape header. If the tape header is smaller than the current clip level, the decryption is done by using software, even though the subsequent records might be very large. This is a case where you might choose to set the clip level to 0 so that hardware cryptography is used regardless of the size of the first record that is processed.
The following example shows how to set the ibm.DES.usehdwr.size
system property
when a Java™ program named programName is
run.
java -Dibm.DES.usehdwr.size=80 programName
This value can also be set programmatically by using the Java
System.setProperty()
method.