Cloudera Docs

Integrating Ranger KMS DB with SafeNet Keysecure HSM

How to integrate Ranger KMS DB with SafeNet Keysecure HSM.

This task describes how to integrate Ranger KMS DB with Safenet Keysecure Hardware Security Module (HSM). This process includes setting up the SafeNet KeySecure Management Console , and configuring Ranger KMS to communicate with the Keysecure instance.

Creating the user on SafeNet keysecure

  1. Login to keysecure with the user having admin privileges.

  2. Click on the Security tab.
  3. Go to the Users & Groups section.
  4. Click on Local Authentication, and click on Add to add a new user.
  5. Check both ‘User Administration Permission’ and ‘Change Password Permission’ when adding the new user.
  6. Save changes.

Creating device on SafeNet KeySecure

  1. Login to Keysecure with user having admin privilges.
  2. Go to Device > NAE-XMLprotocol.
  3. Click on Properties > Edit.
  4. Select the Allow Key and Policy Configuration Operations and Allow Key Export boxes.
  5. Save changes.

Configure SSL on Safenet Keysecure (NAE-XML)

Creating a local CA

  1. Log in to the Management Console as an administrator with certificate uuthorities access control.
  2. Navigate to the Security, CAs & SSL Certificates section and click on Local CA's.
  3. Enter the required details and select Self-signed Root CA as the Certificate Authority Type.
  4. Click on Create.

The Local CA is visble.

Creating a Server Certificate Request on the Management Console

  1. Log on to the Management Console as an administrator with Certificates access control.
  2. Click on the Security tab and on the left side panel .
  3. Navigate to the Device CAs & SSL Certificates section.
  4. Click on SSL certificates link and modify the fields as needed.
  5. Click Create Certificate Request.

    This creates the certificate request and places it in the Certificate List section of the Certificate and CA Configuration page. The new entry shows that the Certificate Purpose is Certificate Request and that the Certificate Status is Request Pending.

Signing a Server Certificate Request with a Local CA

  1. Log on to the Management Console as an Administrator with Certificates and Certificate Authorities access controls.
  2. Navigate to the Security Tab -> Device, CAs and SSL Certificates section.
  3. Click on the SSL Certificates link.
  4. Select the certificate request (cert50) and click Properties.
  5. Copy the text of the certificate request. The copied text must include the header (-----BEGIN CERTIFICATE REQUEST-----) and footer (-----END CERTIFICATE REQUEST-----).
  6. Navigate to the Security Tab -> Device, CAs & SSL Certificates section.
  7. Click on the Local CAs link and select the CA name from the given list.
  8. Click Sign Request to access the Sign Certificate Request section.
  9. On the Sign Certificate Request screen, select Server as certificate Purpose.
  10. Enter the life-span of the certificate for Certificate Duration (days).
  11. Paste all text copied from the server certificate request, including the header and footer in Certificate Request.
  12. Click Sign Request. This will take you to the CA Certificate Information section.
  13. Copy the actual (e.g KSCAN) certificate text. The copied text must include the header (-----BEGIN CERTIFICATE-----) and footer (-----END CERTIFICATE-----).
  14. Navigate back to the Certificate List section (Device, CAs & SSL Certificates )and click on SSL Certificates.
  15. Select your certificate request and click on properties.
  16. Click Install Certificate.
  17. Paste the actual certificate in the Certificate Response.
  18. Click Save.

    The Management Console returns you to the Certificate List section. The section will now show that the Certificate Purpose is Server and that the Certificate Status is Active.

Enable SSL on Keysecure (NAE-XML)

Once SSL has been configured in Safenet KeySecure, perform the following steps.

  1. Log in to keysecure with admin privileges.
  2. Go to Device tab -> Select NAE-XML protocol -> click on properties -> click on edit.
  3. Check Use SSL.
  4. Select the Server Certificate from the given dropdown (e.g. cert50).
  5. Save changes.

Fresh Installation Of Ranger KMS with SafeNet KeySecure (NAE-XML)

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

  1. SSH into the Ranger KMS host.
  2. Create a directory and copy the files IngrianNAE.properties, libIngPKCS11.so and sunpkcs11.cfg from Gemalto SafeNet KeySecure to the directory. 
    mkdir -p /opt/safenetConf/64/8.3.1
    and then copy the above mentioned files under this location.
  3. If SSL is enabled on KeySecure ,then download the CA certificate file (e.g. KSCAN.crt) created on key secure cluster while configuring SSL on keysecure instance.
    1. Log in to KeySecure.
    2. Click on Security tab and then go to Device CAs and SSL Certificates section
    3. Click on Local CA’s link
    4. Select the appropriate certificate and click on download as shown in the below image.
    5. Once the certificate is downloaded, copy/scp it to the Ranger KMS host at location “/etc/security/serverKeys/”.
      Make sure the Ranger KMS user has read-write access to the file. 
      chown  kms:kms /etc/security/serverKeys/KSCAN.crt
      chmod  755 /etc/security/serverKeys/KSCAN.crt
  4. Update the IngrianNAE.propertiesfile and initialize the below mentioned properties. 
    NAE_IP = Your SafeNet KeySecure IP address (Provide public IP if its on a different network.)
    NAE_Port=9000 (should be the same port provided on KeySecure instance under Device tab) 
    Protocol=tcp (valid values ssl or tcp, should be the same protocol provided on KeySecure instance)
  5. Initialize the following property only when the protocol of the KeySecure instance is SSL. This is the location of the certificate downloaded from KeySecure and copied on Ranger KMS host. 
    CA_File=/etc/security/serverKeys/KSCAN.crt
  6. Go to CM > Ranger KMS > Configuration > Search for Ranger KMS Server Advanced Configuration Snippet and click on + icon to add the properties.
  7. 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
  8. Save changes.
  9. 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
  10. Save changes.
  11. Restart Ranger KMS.
The master key with alias MasterKey1 is created in KeySecure.
Once Ranger KMS has started successfully, verify zone key creation, and zone encryption/decryption.

Migrating the master key from Ranger KMS DB to KeySecure

How to migrate the Ranger KMS DB Master Key to SafeNet KeySecure 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.

  1. Once Ranger KMS is installed and running, note down the KMS current running process directory.
  2. Stop the Ranger KMS service.
  3. If SSL is enabled on KeySecure ,then download the CA certificate file (e.g. KSCAN.crt) created on key secure cluster while configuring SSL on keysecure instance.
    1. Log in to KeySecure.
    2. Click on Security tab and then go to Device CAs and SSL Certificates section
    3. Click on Local CA’s link
    4. Select the appropriate certificate and click on download as shown in the below image.
    5. Once the certificate is downloaded, copy/scp it to the Ranger KMS host at location “/etc/security/serverKeys/”.
      Make sure the Ranger KMS user has read-write access to the file. 
      chown  kms:kms /etc/security/serverKeys/KSCAN.crt
      chmod  755 /etc/security/serverKeys/KSCAN.crt
  4. Create a directory and copy the files IngrianNAE.properties, libIngPKCS11.so and sunpkcs11.cfg from Gemalto SafeNet KeySecure to the directory. 
    mkdir -p /opt/safenetConf/64/8.3.1
    and then copy the above mentioned files under this location.
  5. Update the IngrianNAE.propertiesfile and initialize the below mentioned properties. 
    NAE_IP = Your SafeNet KeySecure IP address (Provide public IP if its on a different network.)
    NAE_Port=9000 (should be the same port provided on KeySecure instance under Device tab) 
    Protocol=tcp (valid values ssl or tcp, should be the same protocol provided on KeySecure instance)
  6. Initialize the following property only when the protocol of the KeySecure instance is SSL. This is the location of the certificate downloaded from KeySecure and copied on Ranger KMS host. 
    CA_File=/etc/security/serverKeys/KSCAN.crt
  7. Go to CM > Ranger KMS > Configuration > Search for Ranger KMS Server Advanced Configuration Snippet and click on + icon to add the properties.
  8. 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
  9. Save changes.
  10. 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
  11. Run the DBMKTOKEYSECURE.sh script. 
    ./DBMKTOKEYSECURE.sh masterKey-name keysecure-UserName keysecure-password /path/to/sunpkcs/config/file/sunpkcs11.cfg
    where keySecureMasterKeyName : Name of the key which needs to be created on KeySecure , keySecureUsername : User created on KeySecure cluster , and keySecurePassword : Password of the user
    Master Key from Ranger KMS DB has been successfully imported into CipherTrust Manager.
  12. 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 the same name used above with migration utility ./DBMKTOKEYSECURE.sh )
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
  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 KeySecure HSM to Ranger KMS DB

How to migrate the Master key from KeySecure 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.

  1. Ensure Ranger KMS is running.
  2. Find the KMS current process directory. 
    ps -ef | grep proc_rangerkms
  3. Stop Ranger KMS service from CM.
  4. 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
  5. Run the ./KEYSECUREMKTOKMSDB script by passing the master key password. 
    ./KEYSECUREMKTOKMSDB masterKeyPassword
    Master Key from Key Secure has been successfully imported into Ranger KMS DB.
  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.