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.

Introduction

Whats New for 5.0

Cryptographic Hardware Utilization

IBMPKCS11Impl Provider Restrictions

Cryptographic Hardware Keys

Key Generation and Storage

Signature and Verification

Hashing Algorithms

Random Number Generation

IBMPKCS11Impl Provider Package

• Changes from software JCE to the PKCS#11 Implemention
• Specific Changes and Requirements
  • The KeyFactory Class
    • DSA
    • RSA
  • Algorithm Parameters Classes
    • PKCS11DSAKeyPairParameterSpec
    • PKCS11RSAKeyPairParameterSpec
    • GeneralPKCS11KeyParameterSpec
    • DESPKCS11KeyParameterSpec
    • DESedePKCS11KeyParameterSpec
  • Key Interface Classes
  • Key Specifications Interfaces and Classes
  • SecureRandom
  • Signature
  • Data Encryption Standard
  • Triple DES
  • RSA
  • Other Symmetric Ciphers
  • Diffie-Hellman
  • Keystore for IBMPKCS11Impl
• Configuring and using Hardware Cryptographic devices
  • Configuration file
• Software to Hardware Key Migration Aids
• Initialization of the IBMPKCS11Impl Provider
  • Using Configuration File
  • Java Preferences
  • JAAS Login Module
  • Directly
  • Using Multiple Cards

Introduction

The IBMPKCS11Impl provider uses the Java Cryptography Extension (JCE) and Java Cryptography Architecture (JCA) frameworks to seamlessly add the capability to use hardware cryptography using the Public Key Cryptogaphic Standards # 11(PKCS#11) standard. This new provider takes advantage of hardware cryptography within the existing JCE architecture and gives Java 2 programmers 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 using various hardware cryptographic devices. The following link shows the current list of supported devices, Supported Devices

The IBMPKCS11Impl provider provides for: Message Digest using the MD2, MD5, SHA-1, SHA-256, SHA-384, and SHA-512 algorithms. It also provides the symmetric algorithms AES,DES, triple DES (also known as DESede), RC4, Blowfish and the asymmetric algorithm RSA for encryption and decryption. It further provides digital signature and verification using the RSA and DSA algorithms. Hash based Message Authentication Codes are supported for MD5, SHA1, SHA-256, SHA-384, and SHA-512. This implementation also includes random number generation, key generation using key factories, key and certificate generation, and key and certificate management using the ikeyman application.

Whats New for 5.0

IBMPKCS11Impl has been updated to allow more algorithms and to allow the SUN 5.0 methods of initialization of the provider.

The new algorithms are:

• AES
• Diffie-Hellman
• RC4 also known as ArcFour
• Blowfish
• SHA-256
• SHA-384
• SHA-512
• SHA256withRSA
• SHA384withRSA
• SHA512withRSA
• HmacMD5
• HmacSHA1
• HmacSHA256
• HmacSHA384
• HmacSHA512

In SDK 5.0, the ability to pass in a configuration file to the provider, was added. This configuration file can contain a lot of information about the device, like what it should or should not do. Once the provider is created, than the application is able to login to the card in a few different ways. Some devices will allow you to do some cryptographic functions without logging into device. The old 1.4.2 ways to initialize the device still work. However, you will not have the ability to have more than one of these providers at a time, as before. However with this release, it is now possible to initialize more than one IBMPKCS11Impl provider using the 5.0 configuration file and login methods. The PKCS11ImplKS has been updated also, to allow the importation of certificates using the setCertifcateEntry or setEntry. Also, the setKeyEntry will now save the key to the device with the certificates in the chain, as necessary.

The classes DESPKCS11KeyParameterSpec and DESedePKCS11KeyParameterSpec have been deprecated. The GeneralPKCS11KeyParameterSpec class should now be used for all symmetric key types (i.e., DES, DESede, AES, RC4, Blowfish, etc.).

Cryptographic Hardware Utilization

This provider operates with many different hardware devices. The list in the introduction section shows the maximum possible functions that this provider allows an application to use. Fewer functions might be available depending on the hardware device that is bring used. The hardware device might also require that certain attributes be associated with each key. For example, a hardware device might require that only keys with an attribute of SENSITIVE will be allowed to do encryption, or decryption, or both. The requirements depend on the hardware device. Read the documentation about your hardware device to know its limitations, requirements, and the algorithms it provides (see Card Observations for more information).

IBMPKCS11Impl Provider Restrictions

In 1.4.2 this provider used a static variable for the Provider Name, this allowed only one IBMPKCS11Impl provider to be initialized at one time. This meant that the last initialization of a IBMPKCS11Impl provider determines what all IBMPKCS11Impl provider objects support. In 5.0 this was changed, such that you could have multiple providers if a configuration file was used for each provider. This way you are able to give a unique name to each provider. If the provider is initialized using the old 1.4.2 way, and IBMPKCS11Impl is already in the provider list than when an application initializes and adds a new IBMPKCS11Impl provider programatically to the provider list. When an application asks java for a cryptographic function via the provider list, java will initialize the provider object that is in the provider list from java.security file. This may cause an application to see a "No such alg : java.security.NoSuchAlgorithmException: no such algorithm: xxxxx for provider IBMPKCS11Impl" exception.

This provider also does now contain multiple thread serialization code. This serialization will handle cards that do not do the serialization themselves. Please note that this will not help with the unit of work issues. Basically where an application is trying to use the same provider in multiple threads trying to do multiple operations. This can only be done such that a different provider is used in each thread and that one complete operation is done. (i.e. for Hashing do init, than update and finally disgest, without trying to start another type of operation between these steps).

The IBMPKCS11Impl provider can come before the IBMJCE provider in the provider list and IBMJCE may be 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. If you do see this message try updating the configuration file for your provider such that all DSA mechanisms are turned off. Also, when using iKeyman make sure that IBMPKCS11Impl is not in the provider list.

Cryptographic Hardware Keys

In the hardware cryptography environment there are multiple ways to take advantage of the hardware. PKCS#11 allows you to create keys that are SENSITIVE and that have 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 attribute causes parts of the keys to be hidden. 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 attribute basically keeps the sensitive parts of keys secret. However, this behavior also means that the key can never be taken off this device. EXTRACTABLE is another attribute and it keeps the key from being able to be wrapped by another key, if the attribute is set to true. These two attributes are of some importance. Keys that are located outside of the hardware device are called clear keys. These keys have to be converted so that they can be used by a PKCS#11 device. This conversion is done using KeyFactory.

Key Generation and Storage

Key generation can be accomplished using either an application called ikeyman or using the JCE APIs. 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 APIs allow you to generate key pairs and then at the discretion of the application also store them in a keystore file. Also, some hardware devices ship applications that allow users to generate keys. This provider contains a keystore of type PKCS11IMPLKS (see Keystores for IBMPKCS11Impl for more information about this keystore). Note: ikeyman requires the IBMPKCS11 provider. See the ikeyman documentation for more information.

Signature and Verification

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 to the actual hardware device. For example as RSA is a rather computationally intensive algorithm, this implementation moves a large portion of the instructions off of the main processor and onto the hardware device. The cryptographic hardware processes this 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. Also, applications have the option of using secure key pairs(SENSITIVE private keys).

Hashing Algorithms

As the 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 or verify algorithm).

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.

Random Number Generation

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.

IBMPKCS11Impl Provider Package

The IBMPKCS11Impl provider:

• 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, SHA-256, SHA-384, SHA-512 (NIST FIPS 180-1) message digest algorithms on the hardware device.
• Gives access to the AES cipher algorithm.
• Gives access to the RC4 cipher algorithm.
• Gives access to the Blowfish cipher algorithm.
• 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.
• Allows through the hardware device DH key pairs to be generated that are suitable for the Diffie-Hellman algorithm.
• Provides an RSA key pair generator for generating a pair of keys (public and private) suitable for the RSA algorithm.
• Provides access to the Diffie-Hellman algorithm for key exchange
• Provides a DES key generator for generating a key suitable for the DES algorithm.
• Provides TripleDES key generator for generating a key suitable for the TripleDES algorithm.
• Provides a DSA algorithm parameter generator this is implemented in software.
• Provides a DSA algorithm parameter manager.
• Provides a DES algorithm parameter manager.
• Provides a TripleDES algorithm parameter manager.
• Provides a DH algorithm parameter manager.
• Provides access using the "PKCS11DeviceRNG" random number generation algorithm name to random number generation on the hardware device.
• Provides a "certificate factory" for X.509 certificates and Certificate Revocation Lists (CRLs).
• Provides a keystore implementation for the proprietary keystore type named "PKCS11IMPLKS ".

Changes from software JCE to the PKCS#11 Implemention

Most applications will be able to run with few changes. Because the IBMPKCS11Impl provider is based on the JCE Framework, the interfaces an application uses to interact with the provider have not changed. See the Java Cryptography Extension 1.2.1 API Specification & Reference for more information. However, there are changes related to the creating keys. PKCS#11 defines the key attributes that can restrict functions that a key can do and this is reflected in the provider. Also, the list of supported algorithms is much smaller than the software provider IBMJCE. This is of course is limited to what the actual hardware device supports. The largest change that an application has to make is that the IBMPKCS11Impl provider must be initialized unlike the software IBMJCE provider, (see section Initialization for more information). 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 just like a software provider. After the PKCS#11 provider (IBMPKCS11Impl) is selected and initialized, none of the JCE interfaces needs to be changed to take advantage of the hardware capabilities. Keys generated by a software provider are automatically converted for use by this provider, if the hardware device supports this. Therefore, an existing application can be easily migrated from the software JCE environment (such as IBMJCE) into the hardware-capable PKCS#11 environment (IBMPKCS11Impl).

If the provider was initialized using a configuration file than the attributes specified in the configuration file are used for key pair generation, if none are specifed than the attributes default to what ever the device defaults to. If the provider was not initialized using a configuration file, than key pair generation has default attribute values, if none are specified. This allows applications that where written to a software JCE to be functional with this PKCS#11 provider with no changes. Note: The default attribute values do not work with all devices.

The following section on "Specific Changes and Requirements " is intended to provide detail for advanced application programmers. It might also provide some information on the changes to key pair generation and key representation, but an in-depth understanding is probably not required for the typical application developer.

Specific Changes and Requirements

This section provides a discussion of the restrictions and features that have been changed or added from the base JCE to the PKCS#11 IBMPKCS11Impl provider.

The KeyFactory Class:

The KeyFactory class is an engine class that is designed to provide opaque cryptographic keys (of type Key) and key specifications (transparent representations of the underlying key material).

DSA

The keys generated by this provider are similar to the keys that are available in a software provider. However, the keys have more methods that relate to the PKCS#11 standard attributes.

The KeyFactory class can be used to generate a DSA Private PKCS#11 key from a DSAPrivateKeySpec or a PKCS11KeySpec. The KeyFactory can also be used to generate a DSA public key from a DSAPublicKeySpec, an X509EncodedKeySpec, or a PKCS11KeySpec.

The KeyFactory class can also derive a DSAPrivateKeySpec from a DSA Private PKCS#11 key or a DSAPublicKeySpec or X509PublicKeySpec from a DSA public key.

The KeyPairGenerator class requires the use of the class PKCS11DSAKeyPairParameterSpec if the defaults are not to be used. An application is not allowed to only specify the key size, or the key size and source of randomness. The above class is required for all non-default key pair generations. Note: That specifying a source of randomness is not required, because the device uses its own source to generate keys.

RSA

This provider handles RSA keys similar to the DSA keys above.

RSA is similar to DSA in that the KeyFactory class can be used to generate a RSA Private PKCS#11 key from an RSAPrivateCrtKeySpec, RSAPrivateKeySpec or a PKCS11KeySpec. The KeyFactory can also be used to generate an RSA public key from an RSAPublicKeySpec, an X509EncodedKeySpec, or an PKCS11KeySpec. The opposite can also be done to generate an RSAPrivateCrtKeySpec or an RSAPrivateKeySpec from an RSA private PKCS#11 key and an RSAPublicKeySpec or X509EncodeKeySpec can be generated from an RSA public key.

The KeyPairGenerator class is also similar and if an application needs to create an RSA key pair that does not use the defaults, the PKCS11RSAKeyPairParameterSpec class must be used. An application is not allowed to only specify the key size, or the key size and source of randomness. The above class is required for all non-default key pair generations. Note: That specifying a source of randomness is not required, because the device uses its own source to generate keys.

The SecretKeyFactory Class

The SecretKeyFactory is used to convert secret keys (opaque cryptographic keys of type SecretKey) into key specifications (transparent representations of the underlying key material), and vice versa.

The SecretKeyFactory can be used to generate a PKCS#11 secret key from a PKCS11KeySpec or a SecretKeySpec. Notice there is a difference from SDK 1.4.2, where the KeySpec used to generate the PKCS#11 secret key was PKCS11KeySpec, DESKeySpec or DESedeKeySpec. The reason to use a more general class to represent secret key spec is because IBMPKCS11Impl now supports more symmetric key algorithms including DES, DESede, Blowfish, AES, and RC4, while on SDK 1.4.2, it only supports DES and DESede.

Algorithm Parameters Classes:

The following sections describe the Algorithm Parameter classes that are associated with the IBMPKCS11Impl provider for key generation.

The KeyParameterSpec class for DSA PKCS#11 (PKCS11DSAKeyPairParameterSpec):

This class (which implements the AlgorithmParameterSpec interface) specifies the set of parameters to use with the DSA algorithm. These include:

• KeySize, which is the size of the keys based on prime p
• ID which is the identifier of the keys and will become a byte array.
• Subject which is the DER encoding of certificate subject name.
• Label which is to be associated with these keys.
• isToken which says that these keys are to be stored on the device.
• isSensitive which says that the sensitive parts of the keys are not available to be seen.
• extractable which says that these keys can be extracted off the device. Many devices do not support this attribute. Set this attribute to null if your hardware device does not support it.
• DSAParameterSpec which includes the prime p, the sub-prime q and base g.

See the Java API documentation for the specific methods and restrictions associated with this class. Also, read the documentation associated with your hardware device to know which attributes are applicable.

The KeyParameterSpec class for RSA PKCS#11 (PKCS11RSAKeyPairParameterSpec):

This class implements the AlgorithmParameterSpec interface and specifies the set of parameters to use with the RSA algorithm. These include:

• strength which is the size of the key.
• keyIdentifier which is the identifier of the keys. It will become a byte array.
• Subject which is the DER encoding of the certificate subject name.
• Label which is to be associated with these keys.
• isToken which says that these keys are to be stored on the device.
• isSensitive which says that the sensitive parts of the keys are not available to be seen.
• signing which says that these keys can be used for signing data.
• encryption which says that these keys can be used for encrypting or decrypting data.
• wrapping which says that these keys can be used to wrap or unwrap other keys.
• extractable which says that these keys can be extracted off the device. Many devices do not support this attribute. Set this attribute to null if your hardware device does not support it.

See the Java API documentation for the specific methods and restrictions associated with this class. Also, read the documentation associated with your hardware device to know which attributes are applicable.

GeneralPKCS11KeyParameterSpec

This class implements the AlgorithmParameterSpec interface specifies the set of parameters to use with the symmetric key algorithms. These include:

• keyIdentifier which is the identifier of the keys. It will become a byte array.
• Label which is to be associated with these keys
• isToken which says that these keys are to be stored on the device.
• isSensitive which says that the sensitive parts of the keys are not available to be seen.
• encryption which says that these keys can be used for encrypting or decrypting data.
• wrapping which says that these keys can be used to wrap or unwrap other keys.
• extractable which says that these keys can be extracted off the device. Many devices do not support this attribute. Set this attribute to null if your hardware device does not support this attribute.
• Keysize which is the length of key value

See the Java API documentation for the specific methods and restrictions associated with this class. Also, read the documentation associated with your hardware device to know which attributes are applicable.

The KeyParameterSpec class for DES PKCS#11 (DESPKCS11KeyParameterSpec):

This class is deprecated. It implements the AlgorithmParameterSpec interface) specifies the set of parameters to use with the DES algorithm. These include:

• keyIdentifier which is the identifier of the keys. It will become a byte array.
• Label which is to be associated with these keys.
• isToken which says that these keys are to be stored on the device.
• isSensitive which says that the sensitive parts of the keys are not available to be seen.
• encryption which says that these keys can be used for encrypting or decrypting data.
• wrapping which says that these keys can be used to wrap or unwrap other keys.
• extractable which says that these keys can be extracted off the device. Many devices do not support this attribute. Set this attribute to null if your hardware device does not support this attribute.

See the Java API documentation for the specific methods and restrictions associated with this class. Also, read the documentation associated with your hardware device to know which attributes are applicable.

The KeyParameterSpec class for DESede PKCS#11 (DESedePKCS11KeyParameterSpec):

This class is deprecated. It implements the AlgorithmParameterSpec interface and specifies the set of parameters to use with the DESede algorithm. These parameters are the same as for the DES algorithm above. See the Java API documentation for the specific methods and restrictions associated with this class.

The Key Interface Class:

Because this is a hardware implementation, the encoding associated with keys that are SENSITIVE have no meaning. These keys cannot be transported to another system for use. All keys of this provider have an associated PKCS11Object, which is the hardware represention of the key. To get these keys, call:

public PKCS11Object getObject() 

All key classes of this provider implement PKCS11Key, which defines the basic parts of a key.

Key Specifications Interfaces and Classes:

The PKCS11KeySpec Class

This class (which implements the KeySpec Interface) specifies all keys in this provider and their associated parameters. It has the following method:

public PKCS11Object getObject() - returns the PKCS11Object associated with this key.

See the Java API documentation for more information.

The SecureRandom Class:

The SecureRandom class in this provider is a hardware-device-based random number generator and some devices do not support seeding. Therefore, calls to setSeed, getSeed and generateSeed might throw an exception. Note that an alias for the algorithm name "PKCS11DeviceRNG " has been added as "IBMSecureRandom" for compatibility reasons.

Example of SecureRandom usage

java.security.SecureRandom random = null;
// Could replace PKCS11DeviceRNG with IBMSecureRandom
random = java.security.SecureRandom.getInstance( "PKCS11DeviceRNG");
byte[] testData = new byte[1024];
random.nextBytes(testData);

In this example an instance of the SecureRandom class is obtained, a byte array is instantiated, and a random number of size 1024 bytes is generated.

See the Java API documentation for the specific methods, default values, and restrictions associated with this class.

The Signature Class:

SHA1 with DSA or RSA, MD2 with RSA, and MD5 with RSA are the types of signatures that the IBMPKCS11Impl provider supports. However, this list is dependent on the hardware device that is being used and may be less. The signatures are either created by first calling the MessageDigest class that is to be associated with the signature and then calling the hardware to create the actual signature from hash and the corresponding private key or by making a single call to the hardware to everything at once. Signatures are verified the same way by either creating a hash and passing in both the public key and the previously generated signature to the hardware or by just passing in the data, public key and previously generate signature.

Data Encryption Standard (DES):

The hardware implementation for DES does not change any of the APIs that are available in JCE (using software cryptography). Therefore, an application that used the DES capabilities of JCE in software will not have to change to use the hardware provider, other than any specific references to the provider (Such as any getInstance() calls that call for the IBMJCE provider will need to change to call for the IBMPKCS11Impl provider).

Not all of the DES modes are available using the hardware devices. The provider has support only for the Cipher Block Chaining (CBC) and Electronic Code Book (ECB) modes of DES.

Triple DES (also known as DESede or 3DES):

As with DES, not all of the triple DES ciphers are available using the hardware devices. The provider supports only the Cipher Block Chaining (CBC) and Electronic Code Book (ECB) version of triple DES.

RSA

RSA encryption and decryption is available in the provider. As the RSA algorithm is computationally intensive, using the hardware should provide significant performance improvements over software cryptography. Using hardware to perform the RSA encryption and decryption also allows the application to choose to use more secure key pairs such as key pairs that are stored on the card and that keep the sensitive private key from ever being made available in the clear.

In the software versions of JCE (such as IBMJCE) providers, RSA encryption and decryption is implemented with PKCS 1 type 2 padding. The IBMPKCS11Impl provider allows PKCS padding and no padding, only. There are two restrictions that must be noted because of restrictions by the hardware, the type of the key pair that is needed and the maximum length of the data that can be encrypted or decrypted. This capability requires that the keys that are used to encrypt or decrypt data be generated to have a key attribute of ENCRYPT or DECRYPT. The second restriction is that the amount of data that can be encrypted or decrypted must be smaller than the modulus size of the key, in bytes.

The following example shows how to create an instance on an RSA Cipher with "no padding":

Cipher myCipher = Cipher.getInstance("RSA/ /NoPadding","IBMPKCS11Impl");

The following examples show how to create an instance on an RSA Cipher with "PKCS padding":

Cipher myCipher = Cipher.getInstance("RSA/ /PKCS1Padding", "IBMPKCS11Impl");

or

Cipher myCipher = Cipher.getInstance("RSA/ /PKCS", " IBMPKCS11Impl"); // this is the default

or

Cipher myCipher = Cipher.getInstance("RSA", " IBMPKCS11Impl"); // this is the default

Other Symmetric Ciphers

Other symmetric ciphers that IBMPKCS11Impl supports are AES, RC4 and Blowfish. There are no API or functional changes compared to IBMJCE provider.

Diffie-Hellman

The Diffie-Hellman key agreement protocol allows two users to exchange their public values to have a shared secret key. Using KeyAgreement.init(Key, AlgorithmParameterSpec, SecureRandom), the AlgorithmParameterSpec parameter must be null as the current release of IBMPKCS11Impl provider does not support it. KeyAgreement.doPhase(Key, boolean) only supports two-party DH on PKCS11 token, while IBMJCE provider supports multiparty. The returned value is always null as it must be the last phase. The valid key size range for generating DH parameter is 512-1024 and must be a multiple of 8.

IBMPKCS11Impl

Certain PKCS#11 operations, such as accessing private keys, require a login using a Personal Identification Number, or PIN, before the operations can proceed. The most common type of operations that require login are those that deals with keys on the hardware device. In a Java application, such operations often involve first loading the keystore. This provider supports one keystore: PKCS11IMPLKS. This keystore is not a standard flat file keystore. This keystore reads certificates and keys off of the hardware device. It can store the certificates and keys on the hardware device either permanently as token objects or temporarily that will exist for only the length of provider initialization. See details on IBM PKCS11 Impl Proivder’s KeyStore requirements on the underlying native PKCS#11 library in Appendix B.

When accessing the PKCS#11 token as a keystore via the java.security.KeyStore class, you can supply the PIN in the password input parameter to the load method, similar to how applications initialize a keystore prior to SDK 5.0. The PIN will then be used by the IBM PKCS#11 provider for logging into the token. Here is an example:

char[] pin = ...;
KeyStore ks = KeyStore.getInstance("PKCS11IMPLKS", provider);
ks.load(null, pin); 

For an application that wants to accommodate PKCS#11 tokens more dynamically, such as Smartcards being inserted and removed, you may want to use the KeyStore.load(KeyStore.LoadStoreParameter) method. Alternatively, you can use the new KeyStore.Builder class to decouple the configuration from KeyStore. Here is an example of how to initialize the builder for a PKCS#11 keystore with a callback handler:

KeyStore.CallbackHandlerProtection protection = new
                                            KeyStore.CallbackHandlerProtection(handler);
KeyStore.Builder builder = KeyStore.Builder.newInstance("PKCS11",
                                                        provider,
                                                        protection);

The IBMPKCS11Impl provider supports password call back. For the initial access, it will prompt for a password. It prompts only once if the user continues to use the same card. If the user logouts, then logins again using a different card, the builder will prompt for a password for the new card using the previously configured callback handler. Note that if the user removes the card without explicitly logouts, the behavior is not predicted.

Configuring and Using Hardware Cryptographic devices

To use the hardware cryptographic devices the card must be installed and configured according to the specifications that are included with the card. Access to the hardware cryptographic devices is controlled using the PKCS #11 interface. This product uses the PKCS#11 interfaces to access the actual hardware devices.

Configuration file

The configuration file is a text file that contains entries in the following format.

attribute = value

The valid values for attribute and value are described in the table in this section. The two mandatory attributes are name and library. Here is a sample configuration file.

name = Accel
library = /opt/foo/lib/libpkcs11.so
    

Comments are denoted by lines starting with the # (number) symbol.

The supported Config files are contained in this jar for each of the cards that IBM currently supports. You must use these files for you to be supported. The only thing that you should change is the path to the PKCS #11 device library and the slot number. Any other changes and we will not be able to support you.

Attributes Configuration

The attributes option allows you to specify additional PKCS#11 attributes that should be set when creating PKCS#11 key objects. By default, the IBMPKCS11Impl provider only specifies mandatory PKCS#11 attributes when creating objects. For example, for RSA public keys it specifies the key type and algorithm (CKA_CLASS and CKA_KEY_TYPE) and the key values for RSA public keys (CKA_MODULUS and CKA_PUBLIC_EXPONENT). The PKCS#11 library you are using will assign implementation specific default values to the other attributes of an RSA public key, for example that the key can be used to encrypt and verify messages (CKA_ENCRYPT and CKA_VERIFY = true).

The attributes option can be used if you do not like the default values your PKCS#11 implementation assigns or if your PKCS#11 implementation does not support defaults and requires a value to be specified explicitly. Note that specifying attributes that your PKCS#11 implementation does not support or that are invalid for the type of key in question may cause the operation to fail at runtime.

The option can be specified zero or more times, the options are processed in the order specified in the configuration file as described below. The attributes option has the format:

attributes(operation, keytype, keyalgorithm) = {
  name1 = value1
  [...]
}
    

Valid values for operation are:

• generate, for keys generated via a KeyPairGenerator or KeyGenerator

• import, for keys created via a KeyFactory or SecretKeyFactory. This also applies to Java software keys automatically converted to PKCS#11 key objects when they are passed to the initialization method of a cryptographic operation, for example Signature.initSign().

• *, for keys created using either a generate or a create operation.

Valid values for keytype are CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, and CKO_SECRET_KEY, for public, private, and secret keys, respectively, and * to match any type of key.

Valid values for keyalgorithm are one of the CKK_xxx constants from the PKCS#11 specification, or * to match keys of any algorithm. The algorithms currently supported by the IBMPKCS11Impl provider are CKK_RSA, CKK_DSA, CKK_DH, CKK_AES, CKK_DES, CKK_DES3, CKK_RC4, CKK_BLOWFISH, and CKK_GENERIC_SECRET.

The attribute names and values are specified as a list of one or more name-value pairs. name must be a CKA_xxx constant from the PKCS#11 specification, for example CKA_SENSITIVE. value can be one of the following:

• a boolean value, true or false

• an integer, in decimal form (default) or in hexadecimal form if it begins with 0x.

• null, indicating that this attribute should not be specified when creating objects.

If the attributes option is specified multiple times, the entries are processed in the order specified with the attributes aggregated and later attributes overriding earlier ones. For example, consider the following configuration file excerpt:

attributes(*,CKO_PRIVATE_KEY,*) = {
  CKA_SIGN = true
}

attributes(*,CKO_PRIVATE_KEY,CKK_DH) = {
  CKA_SIGN = null
}

attributes(*,CKO_PRIVATE_KEY,CKK_RSA) = {
  CKA_DECRYPT = true
}
    

The first entry says to specify CKA_SIGN = true for all private keys. The second option overrides that with null for Diffie-Hellman private keys, so the CKA_SIGN attribute will not specified for them at all. Finally, the third option says to also specify CKA_DECRYPT = true for RSA private keys. That means RSA private keys will have both CKA_SIGN = true and CKA_DECRYPT = true set.

There is also a special form of the attributes option. You can write attributes = compatibility in the configuration file. That is a shortcut for a whole set of attribute statements. They are designed to provider maximum compatibility with existing Java applications, which may expect, for example, all key components to be accessible and secret keys to be useable for both encryption and decryption. The compatibility attributes line can be used together with other attributes lines, in which case the same aggregation and overriding rules apply as described earlier.

Software to Hardware Key Migration Aids

Often times it might be necessary to migrate a software key on to a hardware device. However, this migration is a security risk, compared to keys generated, stored, and secured on a hardware device. Importing a software key to a hardware device can be done through KeyStore.setKeyEntry(). The setKeyEntry method can accept a software key as argument and converts the key to a session key object. Session object is short lived, it only exists during that session. When a session is closed, the object will be destroyed. If you want to store the key permanently on the token, you can do so by using the configuration file. The attributes option allows you to add additional PKCS#11 attributes to the configuration file. You can add attributes for "import" operation with CKA_TOKEN=true. That means that the keys with the type and algorithm specified in this set of attributes will be imported as token object. Token objects stay on the token after the session is closed. This operation is subject to the hardware device restriction.

Initialization of the IBMPKCS11Impl Provider

The IBMPKCS11Impl provider is implemented by the main class com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl. To use the provider, you must first install it by using the Java Cryptography Architecture (JCA). As with all JCA providers, installation of the provider can be done either statically or programmatically. There are several ways to initialize the provider including configuration file, Java Preferences method, JAAS Login Module method, and direct method. The preferred mechanism to install and initialize the provider is using the configuration file. The old ways of doing it are Java Preferences, JAAS Login Module and direct method. They were introduced on SDK1.4.2, and are deprecated on SDK5.0. We continue to support these mechanisms, but new applications should use configuration file mechanism.

Using Configuration File

To install the provider statically, add the provider to the Java Security properties file ($JAVA_HOME/lib/security/java.security) with the configuration file's full pathname after the provider name. For example:

security.provider.6=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl /opt/foo/cfg/pkcs11.cfg

The pkcs11.cfg is the full pathname of configuration file that has the PKCS library, name, description, attributes, etc. The pathname is platform dependent. For example, /opt/foo/cfg/pkcs11.cfg might be the pathname on AIX or Linux, while c:\foo\pkcs11.cfg might be the one on Windows. See Configuration file section for detailed information. When the system loads the provider, it will automatically initialize it with the information from the configuration file.

Here is the old syntax of adding the provider to Java Security properties file:

security.provider.6=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl

Without the configuration file information, the system loads an empty provider with no algorithms associated with it. You must programmatically initialize it before you are able to explore its cryptographic capabilities. You can initialize it by calling com.ibm.crypto.pkcs11imppl.provider.IBMPKCS11Impl.Init(String, char[]).

Alternatively, you can dynamically install the provider using configuration file. Here are the code snippets:

//create a new instance of IBMPKCS11Impl using the configuration file.
Provider p = new com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl("D:\\pkcs11impl\\luna.cfg");
//add the provider to the system
Security.addProvider(p1);

User login is a requirement to access the private information on the token such as the private keys and secret keys. Some crypto devices may require user login before utilizing their crypto operations. The purpose of com.ibm.crypto.pkcs11imppl.provider.IBMPKCS11Impl.Init(String, char[]) is two folded: it tells the provider where to locate the configuration file, and it is a way for users to put in their PIN for authentication. Once authentication is successful, this provider is fully initialized and the application will have complete access to the crypto device and utilize its capabilities. Alternatively, you can use com.ibm.crypto.pkcs11imppl.provider.IBMPKCS11Impl .login(Subject, CallbackHandler) to supply the PIN. The CallbackHandler must support a PasswordCallback. You only need to provide the PIN once for authentication. Once you login, you don't have to do it again until you logout of the provider.

Java Preferences

This provider will check user preferences for class:

com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl

If the preferences "IBMPKCSImpl DLL" and "IBMPKCSImpl password" exist, the values from these will be used to initialize the connection between the provider and the hardware device. This initialization is done before the provider is created and added to the Java Provider list.

This example shows how to use preferences and then add the provider to the Java Provider List:

        // Get class associated with the preferences
        Class cls = null;
        cls = Class.forName("com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl");

        // Get user preferences associated with this class.
        Preferences prefs = Preferences.userNodeForPackage(cls);

        // prefs.put("IBMPKCSImpl DLL","{hardware device PKCS #11 library name}:{slot #}
        ");
        // A DLL name of cryptoki.dll and a slot of 0:
        prefs.put("IBMPKCSImpl DLL","cryptoki.dll:0");

        // prefs.put("IBMPKCSImpl password", "{hardware device PIN}");
        // A PIN of PASSWORD:
        prefs.put("IBMPKCSImpl password", "PASSWORD");

        // Create provider using the above preferences.
        Provider p1 = new com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl();

        // Since the PIN is sensitive data you probably want to remove it as soon as
        // possible.
        prefs.remove("IBMPKCSImpl DLL");
        prefs.remove("IBMPKCSImpl password");

        //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
        verification.
        Security.addProvider(p1);
    

JAAS Login Module

This is the preferred method. This method can be done either before the provider is created or after. The login module class is:

com.ibm.crypto.pkcs11impl.module.PKCS11LoginModule

This module uses a TextInputCallback with a label of "PKCS11 DLL name: " to get the hardware device PKCS #11 library, and slot number. The format of the string is:

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

In order to get the PIN, the module uses PasswordCallback with a label of "password: ". This password is received as a character array and is cleared as soon as possible.

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.
        // 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
        verification.
        Security.addProvider(p1);

        return (Object) null;
    }
}
    

The following example shows how to use the login module after the provider is created. The only difference is in testAction code. Note that this example assumes that the provider has already been added to Java Provider List:

        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.
        // 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() {
        Provider p = null;

        p = Security.getProvider("IBMPKCS11Impl");

        if (p != null) {
            ((com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl)p).Init(null,null);
        } else {
            System.out.println("not found.");
        }

        return (Object) null;
    }
}
    

Direct Method

This method is documented here for completeness. The IBMPKCS11Impl provider has two constructors. One takes the configuration file's full pathname as argument. The usage is described in Using Configuration File section. The other one has no arguments. You can call it to construct an IBMPKCS11Impl provider instance. It is initially empty, and you must initialize it to make it functional.

Here are the code snippets:

com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl p1 = new com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl();
p1.Init("c:\\program files\\LunaSA\\cryptoki.dll:0", "password".toCharArray());
Security.addProvider(p1);

The format of the string supplied to the Init methods is:

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

or

<configuration file name>

Note: Problems will occur when two IBMPKCS11Impl providers in the provider list share the same provider name. This can happen if two IBMPKCS11Impl providers are initialized with the same configuration file or if the two providers are initialized using the 1.4.2 initializations. If you could get a PKCS11Exception the exception message is like this-com.ibm.pkcs11.PKCS11Exception: Invalid dll name : c:\program files\LunaSA\cryptoki. If you use Login Module mechanism, you could get a LoginException with such messages- javax.security.auth.login.LoginException: com.ibm.pkcs11.PKCS11Exception: Cryptoki is already initialized. This is not a problem with using configuration file. That is, if the configuration file is specified with the provider name in the provider list, you still can programmatically initialize a new provider using the same configuration file.

Using Multiple Cards

With configuration file, you are able to use multiple cards concurrently. To use more than one card or more than one slot per card, simply create configuration file for each, and repeat the installation for each with the appropriate configuration file. This will result in an IBMPKCS11Impl provider instance for each card or each slot.

You would still be able to reuse the same provider instance for different cards like what you can do on SDK 1.4.2. A few calls are available to help you do this. These calls basically clear out the PKCS #11 information from the provider and then allow you to either create a new provider object or reuse the same one if you are using the JAAS login module. The first call is part of the login module:

<LoginContext>.logout();

This call removes the PKCS #11 information from all IBMPKCS11Impl provider objects. You are now ready to initialize the provider again or create a new provider object. Note: That this call is only for an initialization that used the JAAS login module. The other methods should use the static call:

IBMPKCS11Impl.removeSession();

This call will also clear out all IBMPKCS11Impl provider objects. Here is an example of how to do this using JAAS first to initialize the provider and then preferences:

        //Initialize Provider using JAAS
        //

        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.
        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);

        // Remove Provider from Java Provider List
        Security.removeProvider("IBMPKCS11Impl");

        // Log out of the JAAS Login Module to clear the provider out.
        lc.logout();


        //Create Java Preferences for initialization.
        //

        // Add Preferences
        prefs.put("IBMPKCSImpl DLL","cryptoki.dll:0");
        prefs.put("IBMPKCSImpl password", "PASSWORD");

        // Create new provider object
        p1 = new com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl();

        // Remove Preferences for security reasons.
        prefs.remove("IBMPKCSImpl DLL");
        prefs.remove("IBMPKCSImpl password");

        //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
        verification.
        Security.addProvider(p1);

        // Clear all of the IBMPKCS11Impl provider objects and remove the
        // provider from the Java Provider List.
        com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl.removeSession();
        Security.removeProvider("IBMPKCS11Impl");
    

Appendix A: Supported Algorithms

The following table lists the Java algorithms supported by the IBMPKCS11Impl provider and corresponding PKCS#11 mechanisms needed to support them. When multiple mechanisms are listed, they are given in the order of preference and any one of them is sufficent.

Appendix B: IBMPKCS11Impl Provider's KeyStore Requirement

The existing objects stored on a PKCS11 token should match to KeyStore entries.

1. Certificate objects
We consider all certificate objects, no matter the CKA_TRUSTED attribute is set to true or not, are trusted. Each of the certificate objects has a KeyStore.TrustedCertificateEntry type of entry in the keystore.

The alias for the entry is the value of CKA_LABEL attribute of the certificate object. It is possible that different objects may have the same CKA_LABEL value, then the alias may already exist in the keystore. In such case, the new alias will be derived from the label plus "cert" plus a number. The number starts at 0 and increments by 1 every time we derive a new alias. For example, if alias "aliceCA" exists, the new alias for the certificate object with same label will be "aliceCAcert0".

2. Private key objects
All private key objects have a KeyStore.PrivateKeyEntry type of entry in the keystore. On the hardware token, the certificate object for a private key object should share the same unique CKA_ID value as the private key object. For each matching pair of private key and certificate, the certificate chain is built by following the issuer->subject path. If more than one certificate is found, the first one will be used. Once the certificate chain is built and validated, it is added to the keystore as part of the private key entry. If the private key object has no CKA_ID, or for any reason the certificate chain can not be built, then the private key entry will not have a certificate chain with it.

The alias of the private key is the value of CKA_LABEL attribute of the private key object. If the same alias exists in the keystore, the new one will be the label plus "key" plus a number. The number starts at 0 and increments by 1 every time we derive a new alias. For example, if alias "alicePriv" exists, the new one will be "alicePrivkey0". If the key's CKA_LABEL attribute is empty, we create an alias for the private key entry using "privatekey" plus a number.

3. Secret key object
For each secret key object, we create a KeyStore.SecretKeyEntry type entry, with the CKA_LABEL value as the keystore alias. If the alias already exists, then we derive an alias using "secretkey" plus a number. The number increases by 1 every time we create such new alias.

Adding new entry to the keystore would create new object to the PKCS11 token.

1. Trusted certificate entry
The alias string parameter is converted into byte array and use as the value for CKA_ID. The alias is also used as CKA_LABEL value. The certificate object will be created on the token as a token object. Because PKCS11 specification does not allow regular applications to set CKA_TRUSTED attribute to be true, the certificate object will not have this flag set.

2. Key entry
When you try to add a new private key entry, if there is a private key entry with the same alias in the keystore, the old private key token will be deleted as well as its associated certificate. If the rest of the certificates in the chain are not used by other entries, they will be removed also.

The private key or secret key entry may wrap the PKCS11 private key or secret key object that the IBMPKCS11Impl provider recognizes. If not, or if the key is actually a software key, IBMPKCS11Impl provider will convert the key using the KeyFactory or SecretKeyFactory facility. The default is to convert it to an extractable, non-sensitive PKCS11 session key object. Users can change the default by customizing the key attributes with "import" operation in the configuration file.

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

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.