Using the IBM(R) JavaTM FIPS approved Providers IBMJSSEFIPSProvider and IBMJCEFIPS
Introduction
The IBM Java JCE (Java Cryptographic Extension) FIPS providers v1.1 and v1.2 (IBMJCEFIPS) and the IBM Java JSSE (Java Secure Sockets Extension) FIPS 140-2 Cryptographic Module (IBMJSSEFIPS) for Multi-platforms are scalable, multi-purpose cryptographic modules that support only FIPS-approved cryptographic operations through the Java2 Application Programming Interfaces (APIs). These providers and are compliant to Federal Information Processing Standards (FIPS) 140-2 [Level 1]:
- IBMJCEFIP v1.1 and 1.2 for Solaris, Windows, AIX, z/OS, AS/400, Linux (Red Hat and SuSE)
- IBMJSSEFIPS for Solaris, Windows, AIX, z/OS, AS/400, Linux (Red Hat and SuSE)
In order to meet the requirements set forth in the FIPS publication 140-2, the algorithms utilized by the IBMJCEFIPS and IBMJSSEFIPS providers are isolated into the provider cryptographic module (referred to as cryptographic module) itself. These cryptographic modules are accessed by the product code through the Java JCE framework and Java JSSE framework APIs. As the IBMJCEFIPS and IBMJSSEFIPS providers utilize the cryptographic module in an approved manner, the product complies with the FIPS 140-2 requirements when properly configured.
With the addition of IBMJSSE2 and IBM JCE FIPS v1.2 at the IBM JVM 1.4.2 SR1a level, products that want to take advantage of the the newer IBM JSSE2 provider can while still using only FIPS certified cryptography. You can get more information on how to use IBM JSSE2 in FIPS mode by reading "Java Secure Socket Extension (JSSE) IBMJSSE2 Provider Reference Guide" in section "Running the IBMJSSE2 in Mode". IBMJSSE2 gets it's cryptographic functions from IBM JCE FIPS when in FIPS mode. This allows service to be done on IBM JSSE2 with out effecting any FIPS certification. Therefore, this is the strategic provider for Secure Sockets in Java at the 1.4.2 SR1a and above JVMs.
This document describes how to move from the non-FIPS JCE and JSSE providers and how to use the FIPS approved cryptographic modules to retain FIPS compliance.
Provider Information
Because these cryptographic modules are just providers, the APIs used to access them have not changed. These APIs are defined by the JCE framework APIs (see IBM Java JCE FIPS (IBMJCEFIPS) Cryptographic Module API and Java Cryptography Extension 1.2.1 API Specification & Reference for more information) and the JSSE framework APIs (see Java Secure Socket Extension (JSSE) API User's Guide and associated IBMJSSEProvider Class Documentation for more information). This framework makes the transition from the non-FIPS versions relatively easy. A main difference between the non-FIPS approved and the FIPS-approved versions are the provider names'IBMJSEFIPS and IBMJSSEFIPS (See Programming Practices for more differences.) Therefore, in order to use the FIPS providers, the providers must be added to the JVM java.security file's provider list. The example shows the entries needed in this file:
security.provider.?=com.ibm.fips.jsse.IBMJSSEFIPSProvider
security.provider.?=com.ibm.crypto.fips.provider.IBMJCEFIPS
Note: Replace the ? in the preceding with a number for the sequence you want each provider in the list. This list defines which providers the applications have access to and the order in which the algorithms that an application requests are searched.
Programming Practices
Just because the FIPS provider is in the Java provider list is no guarantee that an application will not use a non-FIPS provider. The FIPS JCE v1.1 and FIPS JSSE providers were based on the non-FIPS providers and provide only the FIPS-compliant algorithms. FIPS JCE v1.2 was also based on the non-FIPS IBM JCE but does contain non-FIPS approved alogrithms.
Basically the FIPS providers provider a subset of the algorithms of the non-FIPS providers (see the IBM JAVA JCE FIPS 140-2 Cryptographic Module Security Policy v1.1 and v1.2 and the IBM JAVA JSSE FIPS 140-2 Cryptographic Module Security Policy for more information. AppendixA contains the algorithm lists for each). Therefore, if the non-FIPS providers are in the provider list an application could request and use a algorithm from one of the non-FIPS providers. So, the easiest way to guarantee that a FIPS-approved provider is being used is to explicitly specify the provider name on all getInstance calls. Java uses getInstance calls to create an instance of a Java object. If a provider name is not specified, then Java searches the provider list for a provider that supports the requested algorithm for the specified Java object. Below is an example of this:
//Create a DSA with SHA1 signature using the java.security provider list
Signature sig = Signature.getInstance("SHA1withDSA");
//Create a DSA with SHA1 signature specifying the non-FIPS IBMJCE explicitly
Signature sig = Signature.getInstance("SHA1withDSA", "IBMJCE");
//Create a DSA with SHA1 signature specifying the FIPS IBMJCE explicitly
Signature sig = Signature.getInstance("SHA1withDSA", "IBMJCEFIPS");
This process is the same for any other class that is obtained using a getInstance call for both the IBMJCEFIPS and IBMJSSEFIPS providers. Another way to make sure that only the FIPS provider is being used, is to have only the FIPS providers in the provider list. However because having only the FIPS providers in the list is not always feasable (i.e. Keystore), having the FIPS providers in the list before the non-FIPS providers also helps, but one must still be careful about the algorithms that are going to be used. With the new IBM JCE FIPS v1.2 care must be taken in the use of the algorithms so that non-approved algorithms are not used.
IBMJSSEFIPS allows an application to create an SSL session using defaults. In this case, an application cannot specify the provider explicitly on the getInstance call. The application must instead set the following in the JVM java.security file:
ssl.SocketFactory.provider=com.ibm.fips.jsse.JSSESocketFactory
ssl.ServerSocketFactory.provider= com.ibm.fips.jsse.JSSEServerSocketFactory
This method has the drawback of setting these values for the whole JVM and not just for a single instance. Note: The HTTPS handler uses getDefaults to create an SSL session and therefore ssl.SocketFactory.provider and ssl.ServerSocketfactory.provider must be set to the above values.
Each cryptographic object must be unique and accessible only by an individual user. Therefore do not use static objects, because all users of the JVM share these objects. Static objects are shared in the Java architecture and the creation of a static object would be counter to the unique object method of controlling access and data.
In order to stay FIPS-compliant, an application must use only the FIPS providers and the FIPS approved algorithms. Mixing non-FIPS and FIPS providers will cause a non-compliance.
The same is true for keys. Keys should be created by a FIPS-approved provider to be used by a FIPS-approved provider. However, the FIPS-generated keys can be used by the non-FIPS providers. Because the physical boundary of the cryptographic module is the whole computer, the keys generated by the FIPS provider are in the clear. It is up to the application to wrap these keys if the keys are to be exported off, of the generating computer. Also, the IBM JCE FIPS provider does not contain a keystore. Key storage is left up to the user. The keys created by this provider are still within the physical boundary of the computer and, therefore, the keys do not have to be encrypted unless they are to be moved off of the computer. This physical boundry allows the non-FIPS IBM JCE provider keystores to be used to store these keys.
Some other notable programming practices that an application using the IBMJCEFIPS provider should be aware of are:
- Zeroize keys - The zeroize method should be used when a cryptographic key object is no longer needed to remove the key from memory. While normal Java garbage collection will zeroize the key from memory as part of the object finalizer method it is a safer coding practice to explicitly call the zeroize method when an application is finished with a key object.
- An application that will use FIPS validated cryptography must use the IBM Secure random algorithm associated with the IBMJCEFIPS provider for the source of random data needed by some algorithms.
- The RSA Cryptographic Cipher can be used only to Encrypt and Decrypt keys for transport to stay within the boundaries of the Approved Mode of FIPS 140-2 Level 1.
- One way to help alleviate performance problems is by creating a single source of randomness (IBMSecureRandom in v1.1, IBMSecureRandom or FIPSPRNG in v1.2) and using that object when ever possible.
- In IBM JCE FIPS v1.2, MD5, RSAforSSL and DSAforSSL can only be used if the user is implementing the TLS protocol for Secure Sockets. Any other use will cause the application to be in non-compliance.
For the IBMJSSEFIPSProvider, some other notable programming practices that an application should be aware of are:
- The program must ensure that the only IBM JSSE interfaces used are documented in the Java Secure Socket Extension (JSSE) API User's Guide and associated IBMJSSEProvider Class Documentation based on the level of the JVM that the IBMJSSEFIPS provider is running under.
- The classes of this provider, such as the com.ibm.fips.* classes should not be called directly. Only use the standard extension API interfaces documented in the Java Secure Socket Extension (JSSE) API User's Guide at the JVM level that the IBMJSSEFIPS provider is running on.
- Any tokens used for storing private cryptographic keys should be password protected. The password should follow generally accepted guidelines for password security. All soft tokens should be configured as local to the computer.
- Only the TLS protocol is supported.
The algorithm lists for the FIPS providers are shown below.
IBM JCE FIPS v1.1 algorithms
Ciphers
- AES with modes ECB, CBC, OFB, and CFB
- DES with modes ECB, CBC, OFB, and CFB
- DESede(TripleDES) with modes ECB, CBC, OFB, and CFB
- RSA with PKCS#1 padding this is a non-approved algorithm see Security Policy for more information.
Signature
Key agreement
- DiffieHellman this a non-approved algorithm but is allowed for use in exchanging keys.
Key (pair) generation
- DSA
- AES
- DES
- TripleDES
- HmacSHA1
- RSA
- DiffieHellman
Message authentication code (MAC)
Message digest
Algorithm parameter generator
Algorithm parameter
- AES
- DiffieHellman
- DES
- TripleDES
- DSA
Key Factory
Secret Key Factory
Certificate
Random Number Generation
IBM JCE FIPS v1.2 algorithms
Ciphers
- AES with modes ECB, CBC, OFB, and CFB
- DESede(TripleDES) with modes ECB, CBC, OFB, and CFB
- RSA with PKCS#1 padding this is a non-approved algorithm see Security Policy for more information.
Signature
Key agreement
- Diffie-Hellman this a non-approved algorithm but is allowed for use in exchanging keys.
Key (pair) generation
- DSA
- AES
- TripleDES
- HmacSHA1
- RSA
- DiffieHellman
Message authentication code (MAC)
Message digest
- SHA-1
- SHA-256
- SHA-384
- SHA-512
- MD5 this is a non-approved algorithm see Security Policy for more information.
Algorithm parameter generator
Algorithm parameter
- AES
- DiffieHellman
- TripleDES
- DSA
Key Factory
Secret Key Factory
Certificate
Random Number Generation
- IBMSecureRandom, also known as FIPSPRNG
IBM JSSE FIPS Cipher Suites
This provider supports only the TLS protocol. The associated cipher suites that this provider supports are:
- SSL_RSA_WITH_DES_CBC_SHA (hex number 0009)
- SSL_RSA_FIPS_WITH_DES_CBC_SHA (hex number FEFE)
- SSL_RSA_WITH_3DES_EDE_CBC_SHA (hex number 000A)
- SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA (hex number FEFF)
- SSL_RSA_WITH_AES_128_CBC_SHA (hex number 002F)
- SSL_RSA_WITH_AES_256_CBC_SHA (hex number 0035)
- SSL_DHE_RSA_WITH_AES_128_CBC_SHA (hex number 0033)
- SSL_DHE_RSA_WITH_AES_256_CBC_SHA (hex number 0039)
- SSL_DHE_RSA_WITH_DES_CBC_SHA (hex number 0015)
- SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA (hex number 0016)
- SSL_DHE_DSS_WITH_AES_128_CBC_SHA (hex number 0032)
- SSL_DHE_DSS_WITH_AES_256_CBC_SHA (hex number 0038)
- SSL_DHE_DSS_WITH_DES_CBC_SHA (hex number 0012)
- SSL_RSA_EXPORT1024_WITH_DES_CBC_SHA (hex number 0062)
- SSL_RSA_EXPORT_WITH_DES40_CBC_SHA (hex number 0008)
- SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA (hex number 0014)
- SSL_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA (hex number 0063)
- SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA (hex number 0011)
- SSL_DH_anon_WITH_AES_128_CBC_SHA (hex number 0034)
- SSL_DH_anon_WITH_AES_256_CBC_SHA (hex number 003A)
- SSL_DH_anon_WITH_DES_CBC_SHA (hex number 001A)
- SSL_DH_anon_WITH_3DES_EDE_CBC_SHA (hex number 001B)
- SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA (hex number 0019)
Note: Before using this information and the product it supports, be sure to read the general information under Notices.
This edition of the User Guide applies to the IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 1.4.2, and to all subsequent releases and modifications until otherwise indicated in new editions.
(c) Copyright Sun Microsystems, Inc. 1998, 2004, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.
(c) Copyright International Business Machines Corporation, 1998, 2004. All rights reserved.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
- IBM Director of Licensing
IBM Corporation
North Castle Drive, Armonk
NY 10504-1758 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
- IBM World Trade Asia Corporation Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
- JIMMAIL@uk.ibm.com
[Hursley Java Technology Center (JTC) contact]
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
AIX, and IBM are trademarks or registered trademarks of International Business Machines Corporation in the United States, or other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Linux is a registered trademark of Linus Torvalds.
Other company, product, or service names may be trademarks or service marks of others.
This product is also based in part on the work of the FreeType Project. For more information about Freetype, see  http://www.freetype.org.
This product includes software developed by the Apache Software Foundation http://www.apache.org/.
|
