Configure HSM using Sun PKCS11

About this task

The system supports IBM Sun PKCS11 implementation for HSM devices. HSMs implement Java JCE API. This interface accesses the keys in the device.

Important: The ordering of the security providers is very important. If you try to change the current out-of-the-box order, you need to contact IBM support for assistance.

For nCipher and Safenet HSMs, the ordering of the security providers in the JDK properties impacts the sequence in which the HSM is invoked. This can lead to issues where excessive HSM impact can create too many objects in the HSM, consuming resources, until the HSM crashes.

Procedure

The property file hsm.properties.in is used for supporting PKCS11IMPLKS/SunPKCS11.

The following table lists the properties that are specific to configure HSM.

Attribute	Description
HSM_KEYSTORE_TYPE	If HSM_ENABLED is set to true, the attribute value must be PKCS11IMPLKS.
HSM_KEYSTORE_PROVIDER	If HSM_ENABLED is set to true, the attribute value must be SunPKCS11.
HSM_KEYSTORE_FILE	<Should be left blank>
HSM_ADAPTER_TYPE	ncipher or safeNetFor ncipher, run the following command while creating or updating Keys or Certificates - For UNIX: `export CKNFAST_OVERRIDE_SECURITY_ASSURANCES="longterm;tokenkeys"`
HSM_PASSWORD	The default HSM Keystore password.
HSM_ENABLED	This attribute must be set to true for HSM support.
HSM_PRNG_ALGORITHM	If HSM_ENABLED is set to true the attribute value must be PKCS11.
HSM_CONFIG_FILE_LOCATION	If HSM_ENABLED is set to true the attribute value must be set to the location of the nCipher configuration file. Note: A sample nCipher configuration file is bundled with Sterling B2B Integrator. It is located at <InstallDir/properties/nCipher_B2Bi.cfg.
HSM_KEYSTORE_CACHE_TIME	Time taken to cache the HSM Keystore in Sterling B2B Integrator. The default value is 60 seconds.

Create a configuration file required for the HSM setup based on the HSM type and specify the path in HSM_CONFIG_FILE_LOCATION property.

For the HSM type, you can find the configuration file for the device as shown below or you can ask IBM support to get the configuration file. You can update any of the default settings as required. You must edit the library value if your location is different from the default.

For SafeNet Luna Device:

lunasa_5_0_jsse.cfgname = B2Bi
library=/usr/safenet/lunaclient/lib/libCryptoki2_64.so
description=Luna SA 5.0 IBM SSP config - JSSE

publickeyimportonly=false
slotListIndex = 0
disabledMechanisms = {
   CKM_MD5
   CKM_SHA_1
   CKM_MD5_HMAC
   CKM_SHA_1_HMAC
   CKM_DES_CBC
   CKM_DES_CBC_PAD
   CKM_DES_ECB
   CKM_DES3_CBC
   CKM_DES3_ECB
   CKM_DES3_CBC_PAD
   CKM_AES_CBC
   CKM_AES_ECB
   CKM_AES_CBC_PAD
   CKM_RC4
   CKM_SSL3_MASTER_KEY_DERIVE
   CKM_SSL3_KEY_AND_MAC_DERIVE
   CKM_SSL3_PRE_MASTER_KEY_GEN
   CKM_TLS_PRE_MASTER_KEY_GEN
   CKM_TLS_MASTER_KEY_DERIVE
   CKM_TLS_KEY_AND_MAC_DERIVE
   CKM_TLS_MASTER_KEY_DERIVE_DH
   CKM_TLS_PRF
   CKM_SHA256_HMAC
   CKM_SHA384_HMAC
   CKM_SHA512_HMAC
   CKM_EC_KEY_PAIR_GEN
   CKM_ECDSA_KEY_PAIR_GEN
   CKM_ECDH1_DERIVE
   CKM_ECDH1_COFACTOR_DERIVE
   CKM_ECMQV_DERIVE
   CKM_DH_PKCS_KEY_PAIR_GEN
   CKM_DH_PKCS_PARAMETER_GEN
   CKM_DH_PKCS_DERIVE
}
attributes (*, CKO_PRIVATE_KEY, *) = {
CKA_SENSITIVE = true
CKA_SIGN = true
CKA_DECRYPT = true
CKA_DERIVE=true}
attributes (*, CKO_PUBLIC_KEY, *) = {
CKA_VERIFY = true
CKA_ENCRYPT = true
CKA_DERIVE = true}
attributes (*, CKO_SECRET_KEY, *) = {
CKA_SENSITIVE = true
CKA_ENCRYPT = true
CKA_DECRYPT = true
CKA_SIGN = true
CKA_VERIFY = true}

For nCipher Device:

#nCipher nShield, nForce - Generation 2 cards
name = B2Bi
library = /opt/nfast/toolkits/pkcs11/libcknfast.so
description = IBM B2Bi NCIPHER HSM ADAPTER config for JSSE

slotListIndex =  1
disabledMechanisms = {
   CKM_MD5
   CKM_SHA_1
   CKM_MD5_HMAC
   CKM_SHA_1_HMAC
   CKM_SHA256_HMAC
   CKM_SHA384_HMAC
   CKM_SHA512_HMAC
   CKM_EC_KEY_PAIR_GEN
   CKM_ECDSA
   CKM_ECDSA_SHA1
   CKM_ECDH1_DERIVE
   CKM_ECDH1_COFACTOR_DERIVE
   CKM_ECMQV_DERIVE
}

attributes(*, CKO_SECRET_KEY, *) = {
   CKA_ENCRYPT=true
   CKA_DECRYPT=true
}
attributes (*, CKO_PRIVATE_KEY, *) = {
   CKA_TOKEN=true
   CKA_SIGN=true
   CKA_SENSITIVE=true
}
attributes(generate, CKO_PRIVATE_KEY, CKK_RSA) = {
   CKA_DECRYPT=true
   CKA_UNWRAP=true  
}
attributes(generate, CKO_PUBLIC_KEY, *) = {
   CKA_TOKEN=true
   CKA_VERIFY=true
}
attributes(*, CKO_PUBLIC_KEY, CKK_RSA) = {
   CKA_ENCRYPT=true
   CKA_WRAP=true
   CKA_VERIFY=true
}
attributes(import, CKO_PRIVATE_KEY, CKK_RSA) = {  
   CKA_DECRYPT=true
   CKA_UNWRAP=true
   CKA_DERIVE=true
}

Note: SafeNet Luna does not allow you to import an externally-created private key. You must create and store them on the HSM device.