On-premises HSMs

CORE partition SOClosedSecurity officer - UKC partition administrator role. may expand the partition's boundaries by attaching to it cloud keystores and on-premises HSMs. The partition users and can generate and use key material in the attached keystores. This type of integration is specified in CORE partition and key management guides. See

This section addresses scenarios where Thales and Entrust HSMs are used to store CORE backup keys.

CORE Database Protection using HSM

Unbound CORE database on EP or Partner servers is encrypted by the CORE DEKClosedData Encryption Key - the key that encrypts the database. See also - KEK. key located in the server's file system. The content of the DEKClosedData Encryption Key - the key that encrypts the database. See also - KEK. file is encrypted by another key (KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK).). The location of the KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK)., its key name, and the algorithm to be used to decrypt the DEKClosedData Encryption Key - the key that encrypts the database. See also - KEK. are specified in the DEKClosedData Encryption Key - the key that encrypts the database. See also - KEK.'s metadata file. For the general CORE KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK). and DEKClosedData Encryption Key - the key that encrypts the database. See also - KEK. description, see Database Protection.

In this topic, we are addressing:

  1. Migration of KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK). protection from JKSClosedA Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption. to HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing.
  2. Details for the following HSMs:
    • nCipher nShield
    • Thales Luna

DB Master key (KEK) update

CORE uses the following Java-standard and HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing-specific elements to access the specified HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing:

nCipher nShield

This section covers the installation and setup of the nShield Connect module, the generation of a key in nShield, and its assignment to become the CORE KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK).. For more detailed instructions regarding nShield installation, see nCipher documentation.

Prerequisites

  1. nShield client software must be installed on the CORE server.
  2. The CORE server must be authorized to generate and use a key used for encryption and decryption.

  3. Open the cknfastrc file located in C:\Program Files\nCipher\nfast\cknfastrc. Make sure its content is as follows:

    4. CKNFAST_OVERRIDE_SECURITY_ASSURANCES=all
    #CKNFAST_LOADSHARING=1
    CKNFAST_JCE_COMPATIBILITY=1
    #CKNFAST_DEBUG=10
    #CKNFAST_DEBUGFILE=/opt/nfast/debug.log
    CKNFAST_FAKE_ACCELERATOR_LOGIN=1

Preparations

The CORE server uses the Java SunPKCS11 Provider to utilize the nShield PKCSClosedPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#11 interface.

Create SunPKCS11 Configuration File

Create nCipher's configuration file to be used by sun.security.pkcs11.SunPKCS11. It specifies the following attributes (see the example below):

For example, in Windows, create C:\pkcs11.cfg file:

name=cknfast0
library="C:/Program Files/nCipher/nfast/toolkits/pkcs11/cknfast.dll"

attributes(*, CKO_SECRET_KEY, *) = {
CKA_TOKEN=true
CKA_ENCRYPT=true
CKA_DECRYPT=true
CKA_SENSITIVE=true
}

attributes(*,CKO_PRIVATE_KEY,*) = {
CKA_TOKEN=true
CKA_PRIVATE=true
CKA_DECRYPT=true
CKA_SIGN=true
}

attributes(*,CKO_PUBLIC_KEY,*) = {
CKA_ENCRYPT = true
}

Note
For the description of the attributes settings above, see Attributes Configurationhere.

Modify the Java.security File

Add or modify the sun.security.pkcs11.SunPKCS11 in the java.security file to access nShield HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing.

If the sun.security.pkcs11.SunPKCS11 is missing in the enumerated List of providers section, add the following line to the list. Use the next available number to assign to the security.provider.<number>. For example: 

security.provider.12=sun.security.pkcs11.SunPKCS11 C:\\pkcs11.cfg

Generate a Key in HSM

Run keytool genkeypair specifying:

  • providerName - SunPKCS11-cknfast
  • storetype - PKCS11, and keystore - NONE

See details in Using keytool and jarsigner with PKCS#11 Tokens. For example, generate <alias> key:

java -Dprotect=module -DignorePassphrase=true sun.security.tools.keytool.Main \
-keystore NONE \
-storetype PKCS11 \
-providerName SunPKCS11-cknfast0 \
-genkeypair -v \
-alias <alias> \
-keyalg RSA -keysize 2048

Apply the Key as CORE KEK

  1. Follow the CORE KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK). replacement procedure defined here to replace the default CORE KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK). with the HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing-based one. For example,

    java -jar "C:\Program Files\Dyadic\ekm\lib\ekmconfig.jar" -database -protect \
    -n <alias> \
    -p SunPKCS11-cknfast0 \
    -t PKCS11 \
    -a RSA/ECB/PKCS1Padding

  2. Next, edit the Catalina batch file (catalina.sh) located here. In the batch file,
    1. Search for JAVA_OPTS="$JAVA_OPTS $JSSE_OPTS" statement.
    2. Include in it the following options -Dprotect=module -DignorePassphrase=true:

    JAVA_OPTS="%JAVA_OPTS% %JSSE_OPTS% -Dprotect=module -DignorePassphrase=true"

  3. Restart the EKMClosedEnterprise Key Management - previous name of the product. service.

KEK Rotation

The CORE KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK). is rotated by creating a new key (NEW alias) in the HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing  and by declaring the new key to become the new CORE KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK).:

Step 1 - create a <NEW alias> key:

java -Dprotect=module -DignorePassphrase=true sun.security.tools.keytool.Main \
-keystore NONE \
-storetype PKCS11 \
-providerName SunPKCS11-cknfast0 \
-genkeypair -v \
-alias <NEW alias> \
-keyalg RSA -keysize 2048 \
-dname "CN=KEK" -sigalg SHA256withRSA

Step 2 - declare the new KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK).

java -jar "C:\Program Files\Dyadic\ekm\lib\ekmconfig.jar" -database -protect \
-n <NEW alias> \
-p SunPKCS11-cknfast0 -t PKCS11 \
-a RSA/ECB/PKCS1Padding

Note
This step takes care to decrypt the DEKClosedData Encryption Key - the key that encrypts the database. See also - KEK. using the previous KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK). and encrypt it using the new KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK).. See Updating the Database KEK.

Thales Luna

This section covers the installation and setup of the Thales Luna client, the generation of a key in Luna HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing, and its assignment to become the CORE KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK).. For more detailed instructions regarding Luna client configuration, see Thales Luna HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing documentation.

Prerequisites

This integration has the following prerequisites:

  • Luna client software must be installed on the CORE server.
  • The CORE server must be authorized to generate and use a key used for encryption and decryption.

Preparations

The CORE server uses the Java SunPKCS11 Provider to utilize the Luna client PKCSClosedPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#11 interface.

Create SunPKCS11 Configuration File

Create Luna's configuration file to be used by sun.security.pkcs11.SunPKCS11. It specifies the following attributes (see the example below):

  • name - "luna". It will be later used to produce the full name: SunPKCS11-luna.
  • library - path to PKCSClosedPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#11 library:
    • Windows - C:\Program Files\SafeNet\LunaClient\cryptoki.dll
    • Linux - /usr/safenet/lunaclient/bin/cryptoki.so
  • slot - Luna slot that will hold the key
  • attributes - permitted operations per key category (secret key, private key, public key).

For example, in Windows, create C:\pkcs11.cfg file:

name = luna
library = C:\Program Files\SafeNet\LunaClient\cryptoki.dll
slot = 0

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

attributes(*,CKO_SECRET_KEY,*) = {
CKA_CLASS=4
CKA_PRIVATE= true
CKA_KEY_TYPE = 21
CKA_SENSITIVE= true
CKA_ENCRYPT= true
CKA_DECRYPT= true
CKA_WRAP= true
CKA_UNWRAP= true
}

attributes(*,CKO_PRIVATE_KEY,*) = {
CKA_CLASS=3
CKA_LABEL=true
CKA_PRIVATE = true
CKA_DECRYPT=true
CKA_SIGN=true
CKA_UNWRAP=true
}

attributes(*,CKO_PUBLIC_KEY,*) = {
CKA_CLASS=2
CKA_LABEL=true
CKA_ENCRYPT = true
CKA_VERIFY=true
CKA_WRAP=true
}

Note
For the description of the attributes settings above, see Attributes Configurationhere.

Modify the Java.security File

Add or modify the sun.security.pkcs11.SunPKCS11 in the java.security file to access nShield HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing.

If the sun.security.pkcs11.SunPKCS11 is missing in the enumerated List of providers section, add the following line to the list. Use the next available number to assign to the security.provider.<number>. For example: 

security.provider.12=sun.security.pkcs11.SunPKCS11 C:\\pkcs11.cfg

Generate a Key in HSM

Run keytool genkeypair specifying:

  • providerName - SunPKCS11-luna
  • storetype - PKCS11, and keystore - NONE

See details in Using keytool and jarsigner with PKCS#11 Tokens. For example, generate <alias> key:

keytool \
-keystore NONE -storetype PKCS11 \
-providerName SunPKCS11-luna \
-genkeypair -v \
-alias <alias> \
-keyalg RSA -keysize 2048 \

Note
When prompted for the passphrase, enter Luna's crypto officer (CO) password.

Apply the Key as CORE KEK

  1. Follow the CORE KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK). replacement procedure defined here to replace the default CORE KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK). with the HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing-based one. For example

    2. java -jar "C:\Program Files\Dyadic\ekm\lib\ekmconfig.jar" -database -protect \
    -n <alias> \
    -p SunPKCS11-Luna \
    -t pkcs11 \
    -w <Luna Crypto Officer (CO) password> \
    -a RSA/ECB/PKCS1Padding

  2. Restart the EKMClosedEnterprise Key Management - previous name of the product. service.

KEK Rotation

The CORE KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK). is rotated by creating a new key (NEW alias) in the HSMClosedHardware Security Module - a physical computing device that safeguards and manages digital keys for strong authentication and provides cryptoprocessing  and by declaring the new key to become the new CORE KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK).:

Step 1 - create a <NEW alias> key:

keytool \
-keystore NONE -storetype PKCS11 \
-providerName SunPKCS11-luna \
-genkeypair -v \
-alias <NEW alias> \
-keyalg RSA -keysize 2048 \
-dname "CN=KEK" -sigalg SHA256withRSA

Note
Provide Luna's crypto officer (CO) password as the keystore password to create the keys.

Step 2 - declare the new KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK).:

java -jar "C:\Program Files\Dyadic\ekm\lib\ekmconfig.jar" -database -protect \
-n <NEW alias> \
-p SunPKCS11-luna -t PKCS11 -w <CO Password> \
-a RSA/ECB/PKCS1Padding

Note
This step takes care to decrypt the DEKClosedData Encryption Key - the key that encrypts the database. See also - KEK. using the previous KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK). and encrypt it using the new KEKClosedKey Encryption Key - Used to encrypt the data encryption key (DEK).. See Updating the Database KEK.