Appendix C: PKCS11 Usage Tips

PKCS11 Usage Tip #1:

Session objects and token objects are stored on a crypto adapter. Session objects disappear when the associated PKCS11 session goes away. Token objects do not disappear when the associated PKCS11 session goes away. The crypto hardware uses the CKA_TOKEN attribute setting to determine whether an object is created as a session object or as a token object.

You can override the default CKA_TOKEN setting by changing the PKCS11 configuration file. Use the value CKA_TOKEN=false to create a session object. Use the value CKA_TOKEN=true to create a token object.

In the following example, the CKA_TOKEN attribute for an object is set to true, regardless of how the RSA Private Key object is created on the crypto hardware. The effect of adding this stanza to the PKCS11 configuration file is that all RSA Private Key objects are created as token objects.

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

You can add a separate stanza for each key type you require.

For example, changing the PKCS11 configuration file can be useful when using iKeyman with an underlying PKCS11 key store, and a crypto adapter for which CKA_TOKEN=false is the default. When iKeyman imports a p12 file containing a user's certificate and private key, the imported information is displayed as a Personal Certificate entry. The entry consists of a user certificate and private key pair. If iKeyman is stopped and restarted, terminating the original PKCS11 session, the Personal Certificate reappears as a Signer Certificate. The certificate no longer has an associated private key, because the default is for the key to be created as a session key. The result is that the key is removed when iKeyman is stopped and restarted. By explicitly adding the stanza shown for the desired key type, the private key is created as a token key and is not lost when iKeyman is stopped and restarted.

Do not use a generic PKCS11 configuration file stanza. In the following example, the CKA_TOKEN attribute is set to true for any object created on the crypto hardware.

attributes(*, *, *) = {
  CKA_TOKEN=true
}

This stanza would cause multiple unwanted token objects to be created and stored on the crypto hardware, because iKeyman can perform many crypto operations while extracting the contents of a p12 file. Use the stanza selectively to identify only the specific object types imported from the p12 file.

PKCS11 Usage Tip #2:

When working with any of the following PKCS11 key types, the application cannot rely on garbage collection to clean up the underlying hardware object when the Java™ key object goes out of scope. This is very important when the underlying hardware object is created as a token object, because the hardware object would not disappear when the associated PKCS11 session goes away.

• RSAPrivateKey
• RSAPublicKey
• DSAPrivateKey
• DSAPublicKey
• DHPKCS11PrivateKey
• DHPKCS11PublicKey
• PKCS11ECPrivateKey
• PKCS11ECPublicKey

You can code your PKCS11 application to clean up a hardware object without relying on garbage collection. For example, a PKCS11 application can create an RSAPublicKey object pk as follows:

RSAPublicKey pk = (RSAPublicKey)myKeyFactory.generatePublic(pks);

((com.ibm.crypto.pkcs11impl.provider.RSAPublicKey)pk).rm( );

PKCS11 Usage Tip #3:

In previous releases, when you used the KeyGenerator class to generate DESede keys by using the IBM®PKCS11Impl provider, the IBMPKCS11Impl provider supported only a DESede key size of 192. The IBMPKCS11Impl provider now also accepts a DESede key size of 168, to be consistent with the IBM JCE security provider, which accepts a DESede key size of 168. 168 and 192 actually represent the same DESede key size; 192 includes the DESede parity bits, but 168 does not.

PKCS11 Usage Tip #4:

PKCS11 Usage Tip #5:

        KDFParameterSpec ps = new KDFParameterSpec(16,   // 16  => the size of the secret key to be derived, in bytes   
                KDFParameterSpec.CKD_SHA256_KDF, sharedInfoBytes);  
        KeyAgreement ka = KeyAgreement.getInstance("ECDH","IBMPKCS11Impl-MYHSM");                                       
        ka.init( privateKey, ps);
        ka.doPhase( publicKey, true);
        SecretKey derivedSecretKey = ka.generateSecret("AES");   // The key size specified on line 1 must be compatible
                                                                 // with the secret key type specified here

        KDFParameterSpec ps = new KDFParameterSpec(16,   // 16  => the size of the secret key to be derived, in bytes   
                KDFParameterSpec.CKD_SHA256_KDF, sharedInfoBytes);  
        KeyAgreement ka = KeyAgreement.getInstance("ECDHCofactor","IBMPKCS11Impl-MYHSM"); 
        ka.init( privateKey, ps);
        ka.doPhase( publicKey, true);
        SecretKey derivedSecretKey = ka.generateSecret("AES");   // The key size specified on line 1 must be compatible
                                                                 // with the secret key type specified here

public static final int CKD_SHA256_NIST_KDF = 0x80000014;