Security information

The following pages contain documentation, example code, and ancillary files relating to IBM's SDKs. The documentation covers IBM-specific features of IBM's offerings. A platform-specific Security User Guide is included in each download. For information about the SDK for z/OS product and security components specific to that platform, see this Web site.

Before you can download code, you will need an IBM Registration ID. You can read about IBM Registration here.

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 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. 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 following devices are supported by this provider:

• Rainbow ikey 2000
• nCipher nForce
• IBM 4758 (LEEDS II)
• IBM 4960 (LEEDS Lite)
• Chrysalis Luna HSM
• Eracom Orange
• nCipher nFast
• IBM Security Kit SmartCard
• Gem Plus Smart Cards
• Rainbow Cryptoswift

The IBMPKCS11Impl provider provides all of the following: Message Digest via the MD2, MD5 and SHA-1 algorithms. It provides the symmetric algorithms DES, triple DES (also known as DESede) and the asymmetric algorithm RSA for encryption and decryption. It further provides digital signature and verification via the RSA and DSA algorithms. 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 indepentent 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 Card Observations 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. 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).

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, but the cryptographic operations are processed off of the main CPU). Further 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 and SHA-1 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 will be able to run with few changes. The biggest change that an application has to make is to make sure that the IBMPKCS11Impl provider is initialized, unlike the software IBMJCE provider. The other task is to make sure that this 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).

This provider provides default attribute value for key pair generation. This allows most applications to generate keys on hardware devices without changes.

Note: That an PKCS11KeySpec is only valid on the system where the key was originally generated. The PKCS11KeySpec is made up only of the PKCS11Object. If the keys are SENSITIVE, the keys are represented in such a way that they cannot be moved to another system. Some hardware devices do not support the simple form of RSAPrivateKeyRSAPrivateKeySpec. However, they usually will support the CRT form, using RSAPrivateCrtKeySpec though.

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. This keystore will not save keys to the card using the setKeyEntry call. The setKeyEntry method will however translate a key for use with this provider. Note that these translated keys are only session keys and are not permanently saved on the hardware device. These keys will only exist for the length of provider initialization. Once, the provider is re-initialized or the JVM ends the keys will no longer exist. The same is true for the setCertificateEntry

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 a 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 not worked with any tested card and will not be talked about here.

This provider will check user preferences for class:

com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl

Another way to initialize the provider is using the provided JAAS Login module and this is the preferred method. This can be done either before the provider is created or after. The login module class is:

com.ibm.crypto.pkcs11impl.module.PKCS11LoginModule

<hardware device PKCS #11 library name>:<slot #>

The entry in the login configuration file entry for this module should look like:

com.ibm.crypto.pkcs11impl.module.PKCS11LoginModule required;

The following example shows how to use the login module before the provider instance is created:

        String pswd = "PASSWORD";
        char [] passwd = new char[pswd.length()];
        pswd.getChars(0,pswd.length(),passwd,0);
        LoginContext lc = null;

        // This class is used to pass the needed information into the login module.
        // This is done by just transfering the passed in parameters to the login
        // module with out any changes.
        // Please note that cryptoki.dll would be replaced by your PKCS#11 library
        // name and 0 is be replaced with the slot # you want.
        NullPrompter np = new NullPrompter("cryptoki.dll:0",passwd);

        // Create the login context.
        lc = new LoginContext("active", np);

        // This creates the needed principal that the provider needs.
        lc.login();

        // Get the associated subject.
        Subject whoami = lc.getSubject();

        // Creates the privileged action needed to finish
        PrivilegedAction doIt =
            (PrivilegedAction)Class.forName("testAction").newInstance();

        // Execute the action.
        Subject.doAs(whoami, doIt);


class testAction implements PrivilegedAction {
    public Object run() {
        com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl p1 = null;

        // Create the provider and make it use the PKCS11Principal.
        p1 = new com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl();

        //Add the provider to the Java Provider List after the IBMJCE provider. Note
        //that the IBMJCE provider should be in the provider list for JCE framework
        Security.addProvider(p1);

        return (Object) null;
    }
}

The IBMJSSE2 provider is able to be configued 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.

Use of the hardware cryptographic accelerator is automatic if the IBMPKCS11Impl provider has been configured, supports that function and is in the provider list. For performance reasons, the cryptographic accelerator will be used if it is anywhere in the provider list, even if the JCE software provider is before it.

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, 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.

The following example shows the Server side of a secure socket where the key required by the server is in the IBMPKCS11ImplKS keystore. The IBMJSSE2 provider after successfully using the PKCS11IMPLKS keystore for the server key, it will use the hardware cryptography card for bulk encryption and other hardware cryptography functions, if the card supports it. The example starts after the IBMPKCS11Impl provider from above has been initialized.

        // Add the IBMJSSE2 Provider to the Java Provider list
        Security.addProvider(new com.ibm.jsse2.IBMJSSEProvider2());

        // Get a keystore of type PKCS11IMPLKS.
        KeyStore ks = KeyStore.getInstance("PKCS11IMPLKS");

        //The name of the keystore is not relevant for the PKCS11IMPLKS keystore.
        //Use the appropriate password.
        ks.load(null,"passphrase".toCharArray());

        // Create a KeyManagerFactory implementing the X.509 key management
        // algorithm using the IBMJSSE2 provider.
        KeyManagerFactory kmf - KeyManagerFactory.getInstance("IBMX509","IBMJSSE2");

 	    // load the keystore with appropriate password
        kmf.init(ks, "passphrase".toCharArray());

        // Create a TrustManagerFactory implementing the X.509 key
        // management algorithm using the IBMJSSE2 provider.

        TrustManagerFactory tmf = TrustManagerFactory.getInstance("IbmX509","IBMJSSE2");

        // Since client authentication will be requested,
        // the server must be able to trust the client.
        tmf.init(ks);

        // Initialize the SSLContext with the KeymangerFactory and the
        // TrustManagerFactory.  "SSL" will allow the server to handshake
        // using "SSLv3" and accept v2 hello.
        SSLContext = SSLContext.getInstance("SSL","IBMJSSE2");
        sslContext.init(kmf.getKeyManagers(), tmf.getTrustManagers(), null);

        // Create an SSL socket over port 8050
        SSLServerSocketFactory factory = sslContext.getServerSocketFactory();
        SSLServerSocket ssl_server_sock = (SSLServerSocket)factory.createServerSocket(
        8050);

        // Require client authentication
        ssl_server_sock.setNeedClientAuth(true);
        // rest not shown

IBMPKCS11Impl Provider Restrictions

This provider uses static variables to hold the hardware device information. This means that the last initialization of a IBMPKCS11Impl provider determines what all IBMPKCS11Impl provider objects 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.

This provider also does not contain multiple thread serialization code. The serialization would have to be done by an application that wishes to use this provider in mulitple threads. This is partly because this provider only supports one PKCS #11 session to a hardware device.

The IBMPKCS11Impl provider must not be before the IBMJCE provider in the provider list and IBMJCE is always required to be in the provider list for JCE framework jar verification. If IBMPKCS11Impl is in the provider list before IBMJCE than you may see a "java.lang.SecurityException: Cannot set up certs for trusted CAs" somewhere in the exception stack trace. Also, when using iKeyman make sure that IBMPKCS11Impl is not in the provider list.

Card Observations

The following cards have observations that a user may be interested in:

• Rainbow ikey 2000
• IBM 4960 (LEEDS Lite)
• IBM 4758 (LEEDS II)
• Eracom Orange
• Chrysalis Luna
• nCipher nForce

Rainbow ikey 2000

This card can translate only CRT RSA keys and cannot translate plain RSA keys. Also, when a Signature is passed, for verification and the signature is not valid, you get an expection that the data is not valid.

IBM 4960 (LEEDS Lite)

This card can translate only CRT RSA keys and cannot translate plain RSA keys. RSA keys can wrap DES and DESede keys, but DES and DESede keys cannot wrap an RSA key. Signature encoding issues on this card are fixed by an update:

• AIX 5.2 it is IY53096 which puts bos.pkcs11 at 5.2.0.30,
• AIX 5.1 it is IY54784 which puts bos.pkcs11 at 5.1.0.28 and
• z/Linux it is the OpenCryptoki 2.1.5 update.

IBM 4758 (LEEDS II)

The RSA signature encoding issue on this card was fixed by Version 2.42 of the microcode, on z/Linux the fix is OpenCryptoki 2.1.5. RSA keys can wrap DES and DESede keys, but DES and DESede keys cannot wrap an RSA key. Also plain RSA keys cannot be translated, but RSA CRT keys can be. The card does not create a ShortBufferException for buffers that are too small.

Eracom Orange

No issues observed.

Chrysalis Luna SA

Software keys cannot be translated using this card. Key wrapping does not work work with the default configuration of the device. Setting a seed for the random number generator is not allowed. This device also doesn't create a ShortBufferException for buffers that are too small.

nCipher nForce

RSA key can wrap a DES or DESede key, but DES and DESede key cannot wrap an RSA key. Also, public keys cannot be wrapped. Translation of plain RSA keys is not supported, but is supported for RSA CRT keys. This device does not allow seeding of the random number generator. Also, it doesn't create a ShortBufferException for buffers that are too small.

IBMPKCS11Impl Provider Package Overview

• Gives access to the Digital Signature Algorithm (DSA), described in NIST FIPS 186 on the hardware device.
• Gives access to an implementation of RSA, described in PKCS #1, on the hardware device.
• Gives access to MD2 (RFC1319), MD5 (RFC 1321) and SHA-1 (NIST FIPS 180-1) message digest algorithms on the hardware device.
• Gives access to the DES cipher algorithm.
• The provider allows access to the TripleDES cipher algorithm on a hardware device.
• Allows through the hardware device DSA key pairs to be generated that are suitable for the DSA algorithm.
• Also, a RSA key pair generator for generating a pair of keys (public and private) 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 DSA algorithm parameter generator that is implemented in software.
• A DSA algorithm parameter manager.
• A DES algorithm parameter manager.
• A TripleDES algorithm parameter manager.
• Access via "PKCS11DeviceRNG" random number generation algorithm name to provide random number generation on the hardware device.
• A "certificate factory" for X.509 certificates and Certificate Revocation Lists (CRLs).
• 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.

Copyright information

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.

Notices

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.

Trademarks

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/.