In general, Java Cryptography Extension (JCE) 1.2.1 provides a framework and implementations for encryption, key generation and key agreement, and Message Authentication Code (MAC) algorithms. Support for encryption includes symmetric, asymmetric, block, and stream ciphers. The software also supports secure streams and sealed objects. JCE 1.2.1 supplements the Java 2 platform, which already includes interfaces and implementations of message digests and digital signatures. That is JCE includes all of the function of JCA plus a great deal of additional function.
This IBMJCE4758 implementation extends JCE to seamlessly add the capability to use hardware cryptography via the IBM Common Cryptographic Architecture (CCA) interfaces. This new provider takes advantage of hardware cryptography within the existing JCE architecture and gives Java 2 programmers the significant security and performance advantages of hardware cryptography with minimal changes to existing Java applications. Just as the complexities of hardware cryptography are taken care of within the normal Java Cryptography Architecture, IBMJCE4758 makes advanced security and performance easily available using hardware cryptographic devices.
IBM CCA is a set of software elements that provide common application interfaces to secure, high-speed cryptographic services on various platforms via hardware cryptographic devices. For IBM 2084 eServer zSeries 990 Machines (T-Rex), these devices include the PCIX Cryptographic Coprocessor (PCIXCC), the PCI Cryptographic Accelerator (PCICA), and the Central Processor Assist for Cryptographic Functions (CPACF). For machines prior to T-Rex the devices are the IBM 4758 PCI Cryptographic Coprocessor (PCICC), the PCI Cryptographic Accelerator (PCICA), and the Cryptographic Coprocessor Facility (CCF).The amount and type of hardware cryptographic services available depends on your platform and hardware device. For more information please refer to your platform's hardware cryptography information and service/support organization and "Configuring and using hardware cryptographic devices" for more information.
IBMJCE4758 uses hardware cryptography to implement those engines that can use the hardware function available through IBM CCA. Thus some of the JCE function will be available throughthis hardware implementation (IBMJCA4758) and others, those that the CCA hardware cannot perform, will only be available through a software cryptography provider like IBMJCE.
IBMJCE4758 provides for all the engine classes available in Java Cryptographic Architecture (JCA) including Message Digest, Signature and KeyFactory classes. This makes Message Digests available through the MD2, MD5 and SHA-1 algorithms. It further provides digital signature and verification via the RSA and DSA algorithms. IBMJCE4758 also includes true Random number generation, key generation via key factories, key/certificate generation and key/certificate management via a keytool application. This hardware capable implementation also provides the symmetric algorithms, DES, triple DES (also known as DESede), HMAC and PBE. It also provides the asymmetric algorithms, RSA encryption and decryption with zero padding, and PKCS 1 type 2 padding.
For information on the IBMJCE4758 package and classes, see the online documentation section.
To download a copy of the documentation for the IBMJCE4758 provider, download the jce4758Docs.jar file.
The jce4758docs.jar files contain the following documents:
To extract the documentation from the downloaded .jar file, place the .jar file at the directory location where you would like the documentation (for instance the ${java-home}/docs/jce4758Docs)directory and issue the following command:
jar -xvf jce4758docs.jar
Note that the jce4758docs.jar file is actually a Java Archive (.jar) file that contains documentation only and no executable code.
For a general overview of JCE, visit Java Cryptography Extension (JCE) Web site. The documents at this Web site contain links to many other Web-based information sources.
The IBMJCE4758 Provider package includes:
- An implementation of the Digital Signature Algorithm (DSA), described in NIST FIPS186 (not supported on T-Rex).
- An implementation of RSA, described in PKCS #1.
- An implementation of the MD2 (RFC1319), MD5 (RFC 1321) and SHA-1 (NIST FIPS 180-1) message digest algorithms.
- An implementation of the HmacMD2, HmacMD5 and HmacSHA1 hashing message authentication code algorithms.
- An implementation of the DES cipher algorithm.
- An implementation of the TripleDES cipher algorithm.
- An implementation of the following PBE algorithms:
- PBEWithMD2AndDES
- PBEWithMD2AndTripleDES
- PBEWithMD5AndDES
- PBEWithMD5AndTripleDES
- PBEWithSHA1AndDES
- PBEWithSHA1AndTripleDES
- PBEWithSHAAnd2KeyTripleDES
- PBEWithSHAAnd3KeyTripleDES
- A DSA key pair generator for generating a pair of public and private keys suitable for the DSA algorithm (not supported on T-Rex)..
- A RSA key pair generator for generating a pair of public and private keys suitable for the RSA algorithm.
- A DES key generator for generating a key suitable for the DES algorithm.
- A TripleDES key generator for generating a key suitable for the TripleDES algorithm.
- A HmacMD2 key generator for generating a key suitable for the HmacMD2 algorithm.
- A HmacMD5 key generator for generating a key suitable for the HmacMD5 algorithm.
- A HmacSHA1 key generator for generating a key suitable for the HmacSHA1 algorithm.
- A DSA algorithm parameter generator (not supported on T-Rex).
- A DSA algorithm parameter manager (not supported on T-Rex).
- A DES algorithm parameter mamager.
- A TripleDES algorithm parameter mamager.
- An implementation of the proprietary "IBMSecureRandom" random number generation algorithm.
- A "certificate factory" for X.509 certificates and Certificate Revocation Lists (CRLs).
- Keystore implementations for the proprietary keystore types named "JCA4758KS", "JCE4758KS" and "JCE4758RACFKS".
For a more detailed description of the differences between IBMJCE4758 and IBMJCE please refer to the following:
The following files are pre-installed in the ${java-home}/lib/ext directory:
- ibmjcefw.jar
- ibmpkcs.jar
- US_export_policy.jar
- local_policy.jar
The following directories and files are pre-installed in the ${java-home}/demo directory:
- jce/policy-files/global
- US_export_policy.jar
- local_policy.jar
- jce/policy-files/unrestricted
- US_export_policy.jar
- local_policy.jar
To use the IBMJCE4758 provider, you must specify the following in your java.security file in the ${java-home}/lib/security directory:
security.provider.1=sun.security.provider.Sun
security.provider.2=com.ibm.crypto.hdwrCCA.provider.IBMJCE4758
security.provider.3=com.ibm.crypto.provider.IBMJCE
Note that the IBM IBMJCE4758 provider must be placed after the default Sun provider.
Also please be sure to have ICSF started before attempting to use IBMJCE4758. If IBMJCE4758 is ahead of IBMJCE in the provider list and ICSF is not started most cryptographic operations will fail.
Specifying Full Function versus Limited Key Size Cryptography
Files US_export_policy.jar and local_policy.jar pre-installed in directory ${java-home}/lib$/ext give you the ability to do full function cryptography and are installed by default. If you don't want this function, or can not use this function because of your country's laws, do the following:
- Remove the US_export_policy.jar and local_policy.jar files from the ${java-home}/lib/ext directory
- Copy different versions of the US_export_policy.jar and local_policy.jar files from directory ${java-home}/docs/jce/policy-files/global into the ${java-home}/lib/ext directory.
These files will give you JCE capabilities, but with limited key size. For more information about these policy files, see the JCE API Specification & Reference.
The sample programs that demonstrate how to use the IBMJCE4758 provider are located in directory ${java-home}/demo/jce4758/src.
To use IBMJCE4758, you must have the following:
- A system at the OS/390 V2R9 level or higher, with at least one CCF and IBM4758 PCI card.
- ICSF must be up and running
You'll need the following two APARs to use ICSF with OS/390 V2R9:
- OW48568 - provides performance enhancements
- OW48511 - is needed to use clear key pairs.
|
