Cloudera Docs

Integrating Ranger KMS DB with CipherTrust Manager HSM

How to integrate Ranger KMS DB with CipherTrust Manager HSM.

This task describes how to integrate Ranger KMS DB with CipherTrust Manager Hardware Security Module (HSM). This process includes configuring the NAE port in Thales Cipher Trust Manager, configuring Ranger DB KMS to interact with Thales CipherTrust HSM, or, migrating Ranger KMS DB Master Key To CipherTrust Manager HSM, and migrating the master key from CipherTrust Manager HSM to Ranger KMS DB.

  • Ensure you have Thales CipherTrust Manger installed in your enivronment.
  • Ensure you have Java (jdk1.8.0.232) installed.
Configure NAE port in Thales CipherTrust Manager
  1. Log in to Thales CipherTrust Manager.
  2. In CipherTrust Manager > Admin Settings, select Add Interface.
  3. In Type, Select NAE (default).
  4. In Network Interface, selectAll.
  5. In Port, type a value for the port number.
    9000
  6. In Mode, select one of the following options to match your environment:
    • No TLS, user must supply password.
    • TLS, Ignore client cert. user must supply password.
  7. Click Add.
  8. If selected mode is TLS, ignore client cert, user must supply password while adding interface, then click on Edit and Download Current Certificate as shown in the images below. Else, skip this step.
  9. Once certificate downloaded (e.g -Certificate_nae.txt) copy it to Ranger KMS server
    Create a directory on Ranger KMS serverhost under /etc/security. 
    mkdir etc/security/serverKeys
    and scp the downloaded certificate to this directory. Ensure that the user has required access to the file 
    chown kms:kms etc/security/serverKeys/Certificate_nae.txt
    chmod 755 etc/security/serverKeysCertificate_nae.txt
  10. Create a user.
    1. Go toAccess Management > Users, click Create New User .
    2. In Create a New User, provide a username, password, and any required information.
    3. Click Create.

Fresh installation - Configuring Ranger KMS DB to interact with Thales CipherTrust HSM.

These are the steps required to configure Ranger KMS DB to interact with Thales CipherTrust HSM. These steps need to be performed only when the cluster is ready with all the required services and no encryption zone keys are present.

  1. SSH into the Ranger KMS host.
  2. Create a directory and copy the files IngrianNAE.properties, libIngPKCS11.so and sunpkcs11.cfg from Thales CipherTrust Manager to the directory. 
    mkdir -p /opt/safenetConf/64/8.3.1
    and then copy the above mentioned files under this location.
  3. Update the IngrianNAE.propertiesfile and initialize the below mentioned properties. 
    NAE_IP = Hostname / CipherTrust Manager IP address
    NAE_Port=9000 (should be the same port provided on CipherTrust instance under Device tab) 
    Protocol=tcp (valid values ssl or tcp, should be the same protocol provided on CipherTrust instance)
  4. Initialize the following property only when the protocol of the CipherTrust Manager instance is SSL. This is the location of the certificate downloaded from CipherTrust Manager and copied on Ranger KMS host. 
    CA_File=/etc/security/serverKeys/Certificate_nae.txt
  5. Go to CM > Ranger KMS > Configuration > Search for Ranger KMS Server Advanced Configuration Snippet and click on + icon to add the properties.
  6. Add the following properties: 
    IngrianNAE_Properties_Conf_Slot_ID_Max=100
    IngrianNAE_Properties_Conf_SessionID_Max=100
    NAE_Properties_Conf_Filename=/opt/safenetConf/64/8.3.1/IngrianNAE.properties
  7. Save changes.
  8. Search for the following properties and set the values as follows: 
    
ranger.kms.keysecure.enabled = true
                    
ranger.kms.keysecure.UserPassword.Authentication = true
                    
ranger.kms.keysecure.masterkey.name = MasterKey1
                    
ranger.kms.keysecure.login.username = keysecure-username
                    
ranger.kms.keysecure.login.password = keysecure-password
                    
ranger.kms.keysecure.masterkey.size = 256
                    
ranger.kms.keysecure.sunpkcs11.cfg.filepath = /opt/safenetConf/64/8.3.1/sunpkcs11.cfg
  9. Save changes.
  10. Restart Ranger KMS.
The master key with alias MasterKey1 is created in CipherTrust Manager.
Once Ranger KMS has started successfully, verify zone key creation, and zone encryption/decryption.

Migrating Ranger KMS DB Master Key To CipherTrust Manager HSM

How to migrate the Ranger KMS DB Master Key to CipherTrust Manager HSM. These steps need to be performed when the cluster is ready with all the required services and encryption zone keys are present in the Ranger KMS DB.

Ensure you have confiured CipherTrust Manager.
  1. Stop Ranger KMS service.
  2. SSH into the Ranger KMS host.
  3. Create a directory and copy the files IngrianNAE.properties, libIngPKCS11.so and sunpkcs11.cfg from Thales Cipher Trust Manager to the directory. 
    mkdir -p /opt/safenetConf/64/8.3.1
    and then copy the above mentioned files under this location.
  4. Update the IngrianNAE.propertiesfile and initialize the below mentioned properties. 
    NAE_IP = Hostname / CipherTrust Manager IP address
    NAE_Port=9000 (should be the same port provided on CipherTrust instance under Device tab) 
    Protocol=tcp (valid values ssl or tcp, should be the same protocol provided on CipherTrust instance)
  5. Initialize the following property only when the protocol of the CipherTrust Manager instance is SSL. This is the location of the certificate downloaded from Cipher Trust Manager and copied on Ranger KMS host. 
    CA_File=/etc/security/serverKeys/Certificate_nae.txt
  6. Go to the Ranger KMS home directory. 
    cd /opt/cloudera/parcels/CDH/lib/ranger-kms
  7. Export the following variables and ensure the variables are exported successfully using the command env|grep NAE 
    export IngrianNAE_Properties_Conf_Slot_ID_Max=100
export IngrianNAE_Properties_Conf_SessionID_Max=100
export NAE_Properties_Conf_Filename=/opt/safenetConf/64/8.3.1/IngrianNAE.properties
  8. Go to Ranger KMS home directory and export the environment variables. 
    export JAVA_HOME = /usr/java/jdk1.8.0_232-cloudera
export RANGER_KMS_HOME = /opt/cloudera/parcels/CDH/lib/ranger-kms
export RANGER_KMS_CONF = /var/run/cloudera-scm-agent/process/current_procsess_dir-RANGER_KMS_SERVER/conf
export SQL_CONNECTOR_JAR = /path/to/SQL-Connector.jar
export HADOOP_CREDSTORE_PASSWORD = hadoop_cred_store_password
  9. Run the DBMKTOKEYSECURE.sh script. 
    ./DBMKTOKEYSECURE.sh masterKey-name keysecure-UserName keysecure-password /path/to/sunpkcs/config/file/sunpkcs11.cfg
    Master Key from Ranger KMS DB has been successfully imported into CipherTrust Manager.
  10. Go to CM > Ranger KMS > Configuration.Search for the following properties and set the values. 
    ranger.kms.keysecure.enabled = true
ranger.kms.keysecure.UserPassword.Authentication = true
ranger.kms.keysecure.masterkey.name = masterkeyname (must be same name used above with migration utility ./DBMKTOKEYSECURE.sh )
ranger.kms.keysecure.login.username = keysecure-username
ranger.kms.keysecure.login.password = keysecure-password  (User details are craeted on KeySecure while adding the user)
ranger.kms.keysecure.masterkey.size = 256
ranger.kms.keysecure.sunpkcs11.cfg.filepath = /opt/safenetConf/64/8.3.1/sunpkcs11.cfg
  11. Search for Ranger KMS Service Environment Advanced Configuration Snippet. Click on the + icon and add the following environment variables. 
    IngrianNAE_Properties_Conf_Slot_ID_Max=100

IngrianNAE_Properties_Conf_SessionID_Max=100

NAE_Properties_Conf_Filename=/opt/safenetConf/64/8.3.1/IngrianNAE.properties
  12. Save changes.
  13. Restart Ranger KMS.
Master Key from Ranger KMS DB has been successfully migrated to CipherTrust Manager.
Once Ranger KMS has started successfully, verify zone key creation, and zone encryption/decryption.

Migrating the Master key from CipherTrust Manger HSM to Ranger KMS DB

How to migrate the Master key from CipherTrust HSM to Ranger KMS DB. These steps need to be performed when the cluster is ready with all the required services and encryption zone keys are present in the Ranger KMS DB.

Ensure Ranger KMS service is running.
  1. Find the KMS current process directory. 
    ps -ef | grep proc_rangerkms
  2. Stop Ranger KMS service from CM.
  3. Go to the Ranger KMS home directory and export the following environment variables. 
    export JAVA_HOME = /usr/java/jdk1.8.0_232-cloudera
export RANGER_KMS_HOME = /opt/cloudera/parcels/CDH/lib/ranger-kms
export RANGER_KMS_CONF = /var/run/cloudera-scm-agent/process/current_procsess_dir-RANGER_KMS_SERVER/conf
export SQL_CONNECTOR_JAR = /path/to/SQL-Connector.jar
export HADOOP_CREDSTORE_PASSWORD = hadoop_cred_store_password

export IngrianNAE_Properties_Conf_Slot_ID_Max = 100
export IngrianNAE_Properties_Conf_SessionID_Max = 100
export NAE_Properties_Conf_Filename = /path/to/ingrian_props_file/IngrianNAE.properties
  4. If the Ranger KMS DB table contains any old master key, then delete the entry from ranger_masterkey table manually and proceed to the next step.
  5. Run the ./KEYSECUREMKTOKMSDB script by passing the master key password. 
    ./KEYSECUREMKTOKMSDB masterKeyPassword
  6. Once the script runs successfully, go toCM > Ranger KMS > Configuration. Search for dbks-site.xml and update the value of ranger.kms.keysecure.enabled to false.
  7. Search for ranger.db.encrypt.key.password and set its value to the master-key password which you used above while invoking the migration script.
  8. Restart Ranger KMS.
Once Ranger KMS has started successfully, verify zone key creation, and zone encryption/decryption.