Setting Up the External KMIP Keystore

Describes how to set up the KMIP keystore and how to enable integration with Data Fabric.

Prerequisite to Setting Up the KMIP Keystore

Data Fabric will have a minimum of 3 hosts to 10 hosts that need to communicate with your External KMIP Keystore vendor. Contact your External Key Management vendor for license considerations.

The steps to first set up the external KMIP key store and then enable KMIP integration with Data Fabric are the same irrespective of whether the cluster is an existing one with DARE enabled, or whether it is a new cluster.

Set up the Keystore

Setting up the external KMIP key store involves the following steps:

  1. Set up the external KMIP-enabled key management appliance for the HSM of your choice as described in the Utimaco ESKM Integration Guide, or the Gemalto SafeNet KeySecure Key Manager Integration Guide, or the Vormetric Data Security Manager (DSM) Integration Guide, or the HashiCorp Vault Integration Guide.

    At the end of this step, you should have the following on one of your Data Fabric cluster hosts that is running the CLDB:

    • Private client key
    • Signed client certificate in PEM format
    • Signed CA certificate in PEM format
  2. On your host running CLDB, initialize the PKCS#11/KMIP configuration using the mrhsm init command. Alternatively, you can do this in multiple steps, using the mrhsm set and mrhsm info commands, until you have achieved a successful connection to the external KMIP-enabled key manager.

    A sample mrhsm init session is as follows:

    # mrhsm init -label "Utimaco ESKM"
Enter SO PIN (4-255 characters): ********
Please reenter SO PIN: ********
    After running the mrhsm init command, the Token info section is initialized, with a serial number assigned. You will need this serial number for various mrhsm configuration tasks. For example:
    # mrhsm info -slots
Available slots:
Slot 1298274617
    Slot info:
        Description:          MapRHSM slot ID 0x4d621939                                      
        Manufacturer ID:      HPE MapR-HSM                    
        Token present:        yes
    Token info:
        Manufacturer ID:      HPE MapR-HSM                    
        Model:                MapRHSM         
        Serial number:        07137a824d621939
        Initialized:          yes
        User PIN initialized: yes
        Label:                Utimaco ESKM
    Alternatively, a sample session with mrhsm set and mrhsm info commands is as follows:
    The following example shows how the mrhsm set command is used. Since the port number 
and KMIP version is not specified, they default to 5696 and 1.1 respectively:

# mrhsm set -ip 12.1.78.164,12.1.78.165 -cacert /root/eskm/LocalCA.crt -clientcert \ 
 /root/eskm/client.pem -clientkey /root/eskm/client.key
Enter SO PIN: ****
    After the preceding mrhsm set command, the configuration settings are updated in ${MAPR_HOME}/conf/tokens/mrhsm.conf and can be displayed using the mrhsm info command:
    # mrhsm info -config 
Displaying information for KMIP token with serial b819261a33fbe5a1
IPs
  IP 1                 : 12.1.78.164 Active
  IP 2                 : 12.1.78.165 Active
Port                   : 5696
KMIP Version           : 1.1
KMIP Client Key        : Configured

KMIP Client Certificate:
    Subject: /C=US/ST=California/L=Santa Clara/O=HPE/OU=MapR/CN=kmipclient/emailAddress=johndoe@hpe.com
    Issuer: /C=US/ST=OR/L=Campbell/O=Utimaco/OU=Atalla/CN=LocalCA/emailAddress=support@utimaco.com
    Version: 3
    Signature Algorithm: rsaEncryption
    Validity:
        Not before: Jan 13 05:23:00 2020 GMT
        Not after: Aug  5 05:23:00 2029 GMT

KMIP CA Certificate:
    Subject: /C=US/ST=OR/L=Campbell/O=Utimaco/OU=Atalla/CN=LocalCA/emailAddress=support@utimaco.com
    Issuer: /C=US/ST=OR/L=Campbell/O=Utimaco/OU=Atalla/CN=LocalCA/emailAddress=support@utimaco.com
    Version: 3
    Signature Algorithm: id-ecPublicKey
    Validity:
        Not before: Aug  6 23:49:09 2019 GMT
  3. When you have successfully verified your KMIP setup and ensured that all the HSMs are Active , enable the KMIP functionality using the mrhsm enable command. A sample session for an existing DARE enabled cluster is as follows:
    # ls /opt/mapr/conf | grep cldb.key
cldb.key
# ls /opt/mapr/conf | grep dare.master.key
dare.master.key
# mrhsm enable
Existing DARE master key found at /opt/mapr/conf/dare.master.key, and -dare is not specified
Use the -dare option to import the DARE master key into the HSM.
# mrhsm enable -dare
Enter SO PIN: ****
Obtained cluster name my.cluster.com from mapr-clusters.conf
Enabling MapR HSM on cluster my.cluster.com
Successfully generated Core KEK, UUID a6a07015-4fa0-477f-8bc3-8c5fa272d822
SHA-256 checksum for Core KEK is 3A1F6060408025873AD32EA7D05086C6F6D99530DFD7467B677E8A94978DC863
Successfully generated Common KEK, UUID 22812c6f-44b1-4c6a-ad77-1cc21b255d04
SHA-256 checksum for Common KEK is 1065ACB3C339AE81ABE43E6D8048795397FE3FD58C4511D63C5C96B2337E4932
SHA-256 checksum for CLDB key is 9C1F76DAE7F9C0EC49153AA91B420DFF07276E896DC858A18F3FD20D551340CC
Successfully set encrypted CLDB key in KMIP configuration
SHA-256 checksum for DARE key is D062D60D6D3AFC1906660FA373C12A05BA40EA4CB077195116399B009E3CDDDF
Successfully set encrypted DARE key in KMIP configuration
##############################################################################
The CLDB and DARE master keys are now protected by the HSM.
The CLDB key cldb.key and DARE master key dare.master.key in /opt/mapr/conf
are no longer used. Back up these keys in a safe location, and then remove
them from /opt/mapr/conf. All keys in the HSM, including the CLDB and DARE
master keys, should be safely backed up. Without the DARE master key, the
cluster cannot be started and data cannot be accessed.

Copy the entire contents of the KMIP token directory /opt/mapr/conf/tokens to
all CLDB and Zookeeper nodes. All files in /opt/mapr/conf/tokens must be owned
by the mapr user and mapr group.
##############################################################################
    As an alternative to Steps 2 and 3, run the configure.sh script with the HSM parameters as many times as needed until the setup is successful.
  4. Use the mrhsm info command to verify that KMIP is enabled. For example:
    # mrhsm info -kmip 
Displaying information for KMIP token with serial 8ce465dd102da8f6
KMIP Configuration Version 1
-----------------------------
CLDB:
    Encrypted Key   : FA31033A00220EDE67006049FFD98EEFB9D517E3E8BF1EEE35C29726BA11EE34F7118124C17F7C10654AC1D1E5BA16F83FCFAC398F99B392E226C2CE23D29D30
    UUID            : 260ca605-bb65-4a81-a341-f3fffc8dced8
    SHA-256 checksum: 9C1F76DAE7F9C0EC49153AA91B420DFF07276E896DC858A18F3FD20D551340CC
DARE :
    Encrypted Key   : 75E530E5DC12AEDB50AF414B8B7C7B07DCC9532FBE698543EF0A90E58767D03C4BF5B4518ED9F34F8D3379DA87F1C4E467891E22D6404502328D1CC9A69A65EC
    UUID            : effc0d14-8d8e-4335-8b03-849a0da46eed
    SHA-256 checksum: D062D60D6D3AFC1906660FA373C12A05BA40EA4CB077195116399B009E3CDDDF
Core KEK :
    UUID            : a6a07015-4fa0-477f-8bc3-8c5fa272d822
    SHA-256 checksum: 3A1F6060408025873AD32EA7D05086C6F6D99530DFD7467B677E8A94978DC863
Common KEK :
    UUID            : 22812c6f-44b1-4c6a-ad77-1cc21b255d04
    SHA-256 checksum: 1065ACB3C339AE81ABE43E6D8048795397FE3FD58C4511D63C5C96B2337E4932
Enabled             : Yes
  5. Copy the contents of the /opt/mapr/conf/tokens directory to all the CLDB and ZooKeeper hosts in the cluster.

Enable KMIP Integration with Data Fabric

You can integrate KMIP with Data Fabric in one of the following ways.

  • Perform a manual Data Fabric installation and run the configure.sh script with the new HSM parameters for a fresh installation, or run the configure.sh script with the normal parameters followed by the mrhsm Commands.
  • Run the mrhsm Commands for an upgrade, or to import the CLDB and DARE keys into the KMIP key management appliance after a regular fresh install.
  • Use the graphical installer to perform a regular (non-KMIP) installation, and then use mrhsm Commands to import the CLDB and (if applicable) DARE keys into the KMIP key management appliance. Finally, manually copy the KMIP configuration to other CLDB and ZooKeeper nodes in the cluster.
    NOTE
    There is no direct support in the Data Fabric graphical installer to enable KMIP integration.