IBM(R) JavaTM PKCS 11 Implementation Provider 1.0
API Specification & Reference
- Introduction
-
- 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
- DES and DESede
- Algorithm Parameters Classes
- PKCS11DSAKeyPairParameterSpec
- PKCS11RSAKeyPairParameterSpec
- DESPKCS11KeyParameterSpec
- DESedePKCS11KeyParameterSpec
- Key Interface Classes
- Key Specifications Interfaces and Classes
- SecureRandom
- Signature
- Data Encryption Standard
- Triple DES
- RSA
- Keystores for IBMPKCS11Impl
- Configuring and using Hardware Cryptographic devices
- Software to Hardware Key Migration Aids
- Initialization of the IBMPKCS11Impl Provider
- Java Preferences
- JAAS Login Module
- Directly
- Using Multiple Cards
-
Card Observations
- Rainbow ikey 2000
- IBM 4960
- IBM 4758
- Eracom Orange
- Chrysalis Luna SA
- nCipher nForce
-
Copyright
-
- Notices
-
- Trademarks
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 are the supported devices:
- 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 for: Message Digest using the MD2, MD5, and SHA-1 algorithms. It also 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 using the RSA and DSA algorithms. 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.
This provider operates with many different hardware devices. The list in the preceding paragraph 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).
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.
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 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.
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).
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 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.
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 (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.
- Provides an RSA key pair generator for generating a pair of keys (public and private) suitable for the RSA algorithm.
- 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 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 ".
Note: None of the preceding algorithms, expect the DSA parameter generator, have been implemented in software by the provider. The provider only gives access to these functions or algorithms through the device.
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).
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.
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 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).
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.
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.
These keys are handled similar to the others.
In the case of DESede keys, KeyFactory handles DESedeKeySpec and PKCS11KeySpec. For DES, it will handle DESKeySpec and PKCS11KeySpec.
Note: An PKCS11KeySpec is valid only on the system where the key was originally generated and 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. Also note that some hardware devices do not support the RSAPrivateKeySpec, they usually will, however, support the RSAPrivateCrtKeySpec.
The following sections describe the Algorithm Parameter classes that are associated with the IBMPKCS11Impl provider for key generation.
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.
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.
This class 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.
This class 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.
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.
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 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.
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.
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.
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 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
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. This keystore will not save keys to the card using the setKeyEntry call. This keystore will, however, translate a key from another key store 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 exist for only the length of provider initialization. After the provider is re-initialized or the JVM, ends the keys will no longer exist. The same is true for the setCertificateEntry.
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.
Often times it might be necessary to migrate a software key on to a hardware device. However, this migration is security risk, compared to keys generated, stored, and secured on a hardware device. Currently there is no way to permanently move the keys from outside a hardware device to the device using this provider. However, this option maybe available through ikeyman, if your hardware device supports its use.
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 function. The three methods are a Java Preferences method, a JAAS Login Module method, and a direct method. If the provider is in the list but not initialized and you explicitly call the IBMPKCS11Impl provider, you will get a NoSuchAlgorithmException exception. If you don't specify a provider, you will get the first provider in the list that supports that algorithm, which may not be the IBMPKCS11Impl provider.
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);
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;
}
}
This method is documented here for completeness. However, this method has not been applicable to any hardware device that has been tested. This method supplies the hardware device PKCS #11 library and slot number using a string to the constructor of the IBMPKS11Impl provider. The format of the string is:
<hardware device PKCS #11 library name>:<slot #>
The following example shows how to use this method:
// Create provider.
// Note that cryptoki.dll would be replaced by your PKCS#11 library
// name and 0 is be replaced with the slot # you want.
p1 = new com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl("cryptoki.dll:0");
//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);
Note:A common problem is when an IBMPKCS11Impl provider is in the provider list and an application tries initialize a new IBMPKCS11Impl provider object. All IBMPKCS11Impl providers share the hardware device information, (such as the session handle). What happens is the user initializes the provider object they created, but the system tries to initialize the one in the provider list. The provider object that the system has may not have any PKCS 11 device information, which sets all the hardware information to null. This causes ALL of the IBMPKCS11Impl providers to be unusable.
Currently there is no method to use multiple cards concurrently. Because only one IBMPKCS11Impl provider can be on the Java Provider list. It is possible to use different cards, as long as, the old provider is removed from Java Provider list. 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");
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
The following sections descibe the observations for each card.
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 data is not valid.
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
-
Linux for System z it is the OpenCryptoki 2.1.5 update .
The RSA signature encoding issue on this card was fixed by Version 2.42 of the microcode, on Linux for System z OpenCryptoki 2.1.5 fixes this issue. 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.
No issues observed.
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.
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.
Note: Before using this information and the product it supports, be sure to read the general information under Notices.
This edition of the User Guide applies to the IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 1.4.2, and to all subsequent releases and modifications until otherwise indicated in new editions.
(c) Copyright Sun Microsystems, Inc. 1998, 2004, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.
(c) Copyright International Business Machines Corporation, 1998, 2004. All rights reserved.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
-
IBM Director of Licensing
IBM Corporation
North Castle Drive, Armonk
NY 10504-1758 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
-
IBM World Trade Asia Corporation Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
-
JIMMAIL@uk.ibm.com
[Hursley Java Technology Center (JTC) contact]
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
AIX, and IBM are trademarks or registered trademarks of International Business Machines Corporation in the United States, or other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Linux is a registered trademark of Linus Torvalds.
Other company, product, or service names may be trademarks or service marks of others.
|
