How to use the IBM(R) JavaTM Hardware Cryptographic Providers
Hardware cryptographic devices are becoming more and more popular. The need to securely store keys and to do cryptographic operations securely are the major reasons that cryptographic hardware devices are becoming more popular. A Java Cryptography Extension (JCE) (see the Java Cryptography Extension API Specification & Reference for more information) hardware-based provider that provides secure key storage and off loads cryptographic operations to the hardware device would have significant benefits over software-based cryptography approaches. This would allow Java Applications to have access to these benefits. The Public Key Cryptographic Standards(PKCS) #11 is a well know standard for accessing cryptographic hardware devices and most cryptographic hardware devices support this standard. Now if a PKCS#11 implementation could be fit into the JCE framework, then an application could have the benefits without major changes.
The IBMPKCS11Impl provider is one such provider. It uses the Java Cryptography Extension (JCE) and Java Cryptography Architecture (JCA) frameworks to seamlessly add the capability to use hardware cryptography via the Public Key Cryptographic Standards # 11(PKCS#11) standard. This 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. As the complexities of hardware cryptography are taken care of within the normal JCE, advanced security and performance using hardware cryptographic devices is made easily available.
PKCS#11 is a standard that provides a common application interface to cryptographic services on various platforms via various hardware cryptographic devices. The current list of support hardware devices can be found in the IBM Java PKCS 11 Supported Devices document.
The IBMPKCS11Impl provider provides all of the following: Message Digest via the MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512 algorithms. It provides the symmetric algorithms DES, tripleDES (also known as DESede), AES, Arc-Four(RC4), Blowfish and the asymmetric algorithm RSA for encryption and decryption. It further provides digital signature and verification via the RSA and DSA algorithms. There is support for Key Agreement using Diffie-Hellman and HMACs using HmacMD5, HmacSHA1, HmacSHA256, HmacSHA384, and HmacSHA512. This implementation also includes random number generation, key translation using key factories, key/certificate generation and key/certificate management using the iKeyman application. iKeyman is independent from the IBMPKCS11Impl provider.
This provider operates with many different hardware devices. The functionalities in the preceding paragraph are the maximum possible functions that this provider allows an application to use. The actual list of functions may be less depending on the hardware device that is being used. The hardware device may also require that certain attributes be associated with each key. This depends on the hardware device. Read the documentation about your hardware device to know its restrictions, requirements and the algorithms it provides (see IBM Java PKCS11 Supported Devices for more information about some hardware devices and their usage with this provider).
In the hardware cryptography environment, there are multiple ways to take advantage of the hardware. PKCS#11 allows you to create keys such that they have an attribute of SENSITIVE, plus many other attributes (see the PKCS#11 standard on the  RSA Public-Key Cryptography Standards web site). SENSITIVE keys are keys that have the SENSITIVE attribute turned on. This causes parts of the keys to not be able to be seen. For example, an RSA private key that is sensitive does not have an attribute of PRIVATE_EXPONENT, plus others. However, one that is not sensitive will have this attribute. This basically keeps the sensitive parts of keys secret. However, this also means that the key can never be taken off this device. Keys that reside outside of the hardware device are called clear keys. These keys have to be translated so that they can be used by a PKCS#11 device. This is done using KeyFactory.
Key generation can be accomplished using an application called iKeyman , via the JCE API's or by an application that was shipped with the hardware device. The iKeyman application allows you to generate key pairs and store them in different keystore type files or on the hardware device if the device allows this. The JCE API's allow you to generate key pairs and then at the discretion of the application also store them in a keystore(flat file or hardware device). This provider contains a keystore of type PKCS11IMPLKS. Note: that iKeyman requires the IBMPKCS11 provider and does not use the PKCS11IMPLKS keystore type, but PKCS11IMPLKS can make use of the keys/certs that ikeyman puts in to the hardware device. See the iKeyman for more information.
The IBMPKCS11Impl provider makes available digital signature and verification using the RSA and DSA algorithms. This implementation also moves all of the algorithm processing off of the CPU and moves it to the hardware device. For example, as RSA is a rather computationally intensive algorithm, this moves a great deal of instructions off of the main processor and onto the hardware device. The cryptographic hardware processes work on the device so that it is much harder to capture and compromise the sensitive material and frees up cycles from the main processor. Further, hardware gives you the choice to increase the base security of the operation by utilizing the hardware to process the algorithm and data, reduce the load on your main CPU, and you have the option of using more secure key pairs (using key attributes to create sensitive keys).
Hashing algorithms are not as computationally intensive, as the RSA and DSA algorithms. It is not always advantageous to use hardware devices to perform these operations (The overhead of using the hardware device can actually outweigh the potential performance gains, even though the cryptographic operations are processed off of the main CPU). The overall security of performing these hashing algorithms on hardware is not substantially better then doing the same hash in software (as the hash is then typically used within a more secure RSA or DSA sign/verify). The IBMPKCS11Impl provider will call the hardware device to perform MD2, MD5, SHA-1, SHA-256, SHA-384 and SHA-512 hashing. Of course these operations are limited to what the hardware device actually supports.
The random number generation is done through the hardware device. The algorithm name is PKCS11DeviceRNG, but for coding simplicity an alias IBMSecureRandom has been added.
Most applications originally written for JCE will be able to run as is with a few setup changes. The biggest change that an application has to make is to ensure that the IBMPKCS11Impl provider is initialized. Secondly, make sure that the IBMPKCS11Impl provider is in the provider list either explicitly or added using API calls to the provider list. Once the PKCS#11 provider (IBMPKCS11Impl) is selected, and initialized, none of the JCE API calls need to be changed to take advantage of the hardware capabilities. This provider automatically converts keys generated by a software provider, if the hardware device supports this conversion. Therefore, an existing application can be easily migrated from the software JCE environment (like IBMJCE) into the hardware-capable PKCS#11 environment (IBMPKCS11Impl).
The IBMPKCS11Impl provider provides default attribute values for key pair generation to initialize the provider. The default attribute values can be modified by putting the attribute value in the configuration file. This allows most applications to generate keys on hardware devices without having to modify their code. In this way, multiple hardware devices are easily supported.
Note: A PKCS11KeySpec is only valid on the system where the key was originally generated. The PKCS11KeySpec is only made up of the PKCS11Object. If the keys are SENSITIVE, the keys are represented in such a way that they cannot be moved to another system. Also, some hardware devices do not support the simple form of RSAPrivateKey RSAPrivateKeySpec. However, they usually will support the CRT form, using RSAPrivateCrtKeySpec.
This provider supports one KeyStore type: PKCS11IMPLKS. This KeyStore is not a standard flat file keystore. This keystore accesses certificates and keys from the hardware device. In 1.4.2, this keystore did not save keys or certificates to the card using the setKeyEntry or setCertificateEntry call. However, the setKeyEntry method did translate a key for use with this provider. (Note that these translated keys were only session keys and were not permanently saved on the hardware device. These keys only existed for the length of provider initialization.) In 5.0, the keystore was updated to actually save the keys and certificates to the card. This is only important if you are trying to be compatible between 1.4.2 and 5.0 or your application was written in 1.4.2, but needs to run on 5.0.
The IBMPKCS11Impl provider must be initialized using one of three different methods. Otherwise, the provider will not have any algorithms associated with it and will not be able to do anything. The three methods are Java Preferences, a JAAS Login Module, and the Direct method. If the provider is in the list but not initialized and you explicitly call the IBMPKCS11Impl provider than you will get a NoSuchAlgorithmException exception. If you don't specify a provider than you will get the first provider in the list that supports that algorithm, which will not be the IBMPKCS11Impl provider. The direct method of initialization has two types one using a DLL and slot and the other using configuration file. The configuration file method is the preferred method for IBM JDK 5.0. The other methods using a JAAS Login module and Preferences are not covered here since 5.0 applications should not use them.
The last way which is the preferred way for IBM JDK 5.0 is using a configuration file. There are sample configuration files provided with the documentation that should be used for the hardware device that you are using. Here is a basic configuration file:
name = foo
library=C:/WINNT/system32/foo.dll
description=the Foo hardware device config.
slotListIndex = 0
Below is code that makes use of the above configuration file.
com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl p1 = null;
// create new provider from the fooconfig configuration file
p1 = new com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl("d:/fooconfig");
//The name of the provider based on the value from the config file.
String provName = "IBMPKCS11Impl-foo";
try {
//Add provider to provider list
Security.addProvider(p1);
//The next set of code uses the NullPrompter class to pass the password
//into the provider to pass to the hardware device.
String pswd = "PASSWORD";
char [] passwd = new char[pswd.length()];
pswd.getChars(0,pswd.length(),passwd,0);
NullPrompter np = new NullPrompter(passwd);
p1.login(null, np);
} catch (Exception ex) {
ex.printStackTrace();
System.out.println("Unexpected exception0: " + ex.getMessage());
return;
}
Since 1.4.2, the IBMJSSE2 provider is able to be configured to use hardware cryptographic accelerators for potential performance improvement and to use hardware cryptographic cards as keystores for greater flexibility in key and trust management.
In 5.0, in order to be compatible with Sun's PKCS#11 support, a configuration file will now be required, even for code which ran successfully without one in 1.4.2. This configuration file is specific to each hardware device and JSSE. See the sample configuration file specific to the hardware device you are using.
Here is same basic configuration file shown before, but for JSSE. Note that the MD5 and SHA1 operations must be turned off for JSSE. Make sure to see the configuration file specific for the hardware device for other mechanism and attribute specific settings.
name = foo
library=C:/WINNT/system32/foo.dll
description=the Foo hardware device config for JSSE.
slotListIndex = 0
disabledMechanisms = {
CKM_MD5
CKM_SHA_1
}
The JSSE protocol requires a symmetric key to be created jointly between the client and the server. When symmetric keys are made sensitive or the card is made sensitive, the hardware will not allow the software key to be put on the cryptographic card. If a card is modified to make it sensitive or through the configuration file, symmetric keys are made sensitive, then the symmetric keys would have to be disabled in the hardware configuration file to be used with JSSE. JSSE would therefore be using software for its bulk encryption instead of hardware.
Use of the hardware cryptographic accelerator is automatic if the IBMPKCS11Impl provider has been configured, supports that function and is in the provider list. In 1.4.2, the cryptographic accelerator would be used if it was anywhere in the provider list, even if the JCE software provider was before it. In 5.0, the configured IBMPKCS11Impl provider must be before any other JCA/JCE providers in the provider list.
IBMJSSE2 supports the accessing of hardware keystore through the IBMPKCS11Impl keystore, PKCS11IMPLKS. An application must configure the IBMPKCS11Impl provider, add the hardware provider to the provider list before the JCA/JCE provider, and set the KeyStore provider to, IBMPKCS11IMPLKS. The IBMPKCS11Impl will now be used for most JSSE cryptographic functions including the handling of cryptographic hardware keys in the keystore.
After the IBMPKCS11Impl provider is initialized, the IBMJSSE2 provider can use the hardware cryptographic card.
This example shows the server side of a secure socket where the key required by the server is in a hardware cryptography IBMPKCS11Impl type keystore. Using hardware cryptography requires a configuration file that is specific for the hardware crypto card being used. See the IBM PKCS11 Implementation Provider Documentation for the JSSE configuration files for the different cards. The IBM PKCS11 Implementation Provider also provides details for the setup and creation of the hardware key. Set up to use the IBMPKCS11Impl provider using the configuration file and then add to the Java Provider List. The creation of the key on the hardware cryptography card is not shown.
//***************************************************************************
// Substitute actual hardware and configuration information
String password = "12345678";
String dlllocation = "/usr/lib/pkcs11/PKCS11_API.so";
String slotnumber = 0;
String configname = "/home/test/cfg/4960.cfg";
//*****************************************************************************
// Set up Crypto Card hardware provider.
com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl p1 = new com.ibm.crypto.
pkcs11impl.provider.IBMPKCS11Impl(configname);
// Must add the hardware crypto provider before IBMJCE in the Java Provider List
// but after the Sun provider on Solaris and HP systems.
Security.insertProviderAt(p1,2);
// Add the IBMJSSE2 Provider to the Java Provider list
Security.addProvider(new com.ibm.jsse2.IBMJSSEProvider2());
// Login to the card
char [] passwd = new char[password.length()];
password.getChars(0,password.length(),passwd,0);
NullPrompter np = new NullPrompter(dlllocation + ":" + slotnumber,passwd);
p1.login(null,np);
// Get a keystore of type PKCS11IMPLKS. The name of keystore
// is not relevant for a PKCS11IMPLKS keystore.
KeyStore ks = KeyStore.getInstance("PKCS11IMPLKS");
ks.load(null, null);
// Create a KeyManagerFactory that implements the X.509 key management
// algorithm using the IBMJSSE2 provider.
KeyManagerFactory kmf = KeyManagerFactory.getInstance("IbmX509","IBMJSSE2");
// already logged into card. Password not required.
kmf.init(ks, null);
// Initialize the SSLContext with the KeyManagerFactory and the default
// TrustManager. Because there is no client authentication, no trusted
// certificates are required. SSL_TLS will allow the server to
handshake
// using SSLv3 or TLSv1 protocol and will accept a v2
hello.
sslContext = SSLContext.getInstance("SSL_TLS","IBMJSSE2");
sslContext.init(kmf.getKeyManagers(), null, null);
// Create an SSL socket over port 8050
SSLServerSocketFactory factory = sslContext.getServerSocketFactory();
SSLServerSocket ssl_server_sock = (SSLServerSocket)factory.createServerSocket(
8050);
// rest not shown
Some of the restrictions for the 1.4.2 version of the code do not hold in 5.0, if a configuration file is being used for initialization. If a 1.4.2 initialization mode is being used, this causes the last initialization of a IBMPKCS11Impl provider to determines what all IBMPKCS11Impl provider objects named IBMPKCS11Impl support. A good example of this is when IBMPKCS11Impl is already in the provider list and an application initializes and than adds programatically a new IBMPKCS11Impl provider to the provider list. When the provider list is accessed java will initialize the provider object that was originally in the provider list from java.security file. This will cause an application to see a "No such alg : java.security.NoSuchAlgorithmException: no such algorithm: xxxxx for provider IBMPKCS11Impl" exception.
In 5.0, the provider does contain multiple thread serialization code. Therefore, the applications no longer have to worry about this. However, logical units of work will need to be spread across providers.
The IBMPKCS11Impl provider can now be before the IBMJCE provider in the provider list, as long as a configuration file is used to initialize the provider. Note that on the Solaris and HP platforms the SUN provider must still be first in the list.
The IBMPKCS11Impl provider give you access to the following algorithms on a hardware device:
- Digital Signature Algorithm (DSA), described in NIST FIPS 186.
- An implementation of RSA, described in PKCS #1.
- MD2 (RFC1319), MD5 (RFC 1321) and SHA-1, SHA-256, SHA-384, SHA-512 (NIST FIPS 180-1) message digest algorithms.
- AES cipher algorithm.
- RC4 cipher algorithm.
- Blowfish cipher algorithm.
- DES cipher algorithm.
- TripleDES cipher algorithm.
- DSA key pairs can be generated that are suitable for the DSA algorithm.
- DH key pairs can be generated that are suitable for the Diffie-Hellman algorithm.
- An RSA key pair generator for generating a pair of keys (public and private) suitable for the RSA algorithm.
- Diffie-Hellman algorithm for key exchange
- 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.
- DSA algorithm parameter generator this is implemented in software.
- A DSA algorithm parameter manager.
- A DES algorithm parameter manager.
- A TripleDES algorithm parameter manager.
- A DH algorithm parameter manager.
- A "PKCS11DeviceRNG" random number generation algorithm name for random number generation.
- A "certificate factory" for X.509 certificates and Certificate Revocation Lists (CRLs).
- A keystore implementation for the proprietary keystore type named "PKCS11IMPLKS ".
Note that none of the above algorithms, expect the DSA parameter generator, have been implemented in software by the provider. The provider only gives access to these functions/algorithms through the device.
iKeyman
iKeyman is a GUI application that provides key, certification request and self-signed certification generation operations. Please read the iKeyman guide for details.
iKeyman can also be used to generate keys and certificates on PKCS#11 enabled hardware crypto device. The procedure is simple:
- Add the IBMPKCS11 (note: this is different than the IBMKCS11Impl) provider. In the iKeyman tool, there is a "blue-man" icon on the panel. Click on that icon and a message box pops up. Type "com.ibm.crypto.pkcs11.provider.IBMPKCS11" in the "New Provider" box, then click "OK". Now, a provider that enables connection to the hardware crypto device becomes available. To create the actual connection to the hardware crypto device, locate the PKCS#11 native library provided by the hardware crypto device vendor. This can be done by clicking on the "Key Database File" tab, choose "Open" and a message box pops up. In the message box is an option box indicating the type of KeyStore to open. For a hardware crypto device, the "Java Cryptographic Token" type should be chosen. The next step is to specify the native PKCS#11 library provided by the device vendor. For instance, on the AIX platform, the 4758 device PKCS#11 native library is located at "/usr/lib/pkcs11 ". The file name (in this case PKCS11_API.so) in the "File Name" box and the location of the file in the "Location" box and click "OK". You will than be asked for the slot number. Now, iKeyman is ready to generate self-signed certificates and certification requests with the hardware crypto device.
For details about the self-signed certificate and certification requests, please refer to the iKeyman user guide.
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 5.0, and to all subsequent releases and modifications until otherwise indicated in new editions.
(c) Copyright Sun Microsystems, Inc. 1998, 2005, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.
(c) Copyright International Business Machines Corporation, 1998, 2005. 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.
Other company, product, or service names may be trademarks or service marks of others.
|
