Setting-up KMIP—for Existing Data Fabric Installation

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

Enable KMIP Integration with Data Fabric

You can integrate KMIP with Data Fabric in either of the ways that follow:
  • Option 1: Perform a manual Data Fabric installation and run the configure.sh script with the new HSM parameters for a fresh installation. See Setting-up KMIP—for Fresh Data Fabric Installation for details.
  • Option 2: Perform a regular (non-KMIP) installation in either of the following ways:
    • Run the configure.sh script with the normal parameters. Or
    • Use the Graphical installer to perform a regular (non-KMIP) installation.

    Then, use the steps in this page to execute the mrhsm Commands, to import the CLDB and DARE keys.

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.

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 (now known as Thales CipherTrust 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 set and mrhsm info commands, until you have achieved a successful connection to the external KMIP-enabled key manager.
    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: ****
    The SO PIN can also be specified with the -sopin option. See About the SO PIN for further info about this.
    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:
    # 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 PKCS#11 store.
    
    The file /opt/mapr/conf/tokens/mrhsm-file.conf still contains a copy of the CLDB
    and DARE master key, which are no longer used. Back up this file in a safe
    location and then remove it. If the cldb.key and dare.master.key files are still
    present in /opt/mapr/conf anywhere on the cluster, after an earlier upgrade,
    they should be securely backed up and deleted too.
    
    All keys in the PKCS#11 store, 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.
    
    Next, copy the entire contents of the 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.
    ##############################################################################
  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 ${MAPR_HOME}/conf/tokens directory and the ${MAPR_HOME}/conf/maprhsm.conf file to all the CLDB and ZooKeeper hosts in the cluster. Ensure that all the files in the tokens directory and the maprhsm.conf file are owned by the mapr user and mapr group.
  6. Restart the cluster (at least All CLDBs nodes, all ZooKeeper nodes, and some of the data nodes), to ensure that the cluster comes up with the installed HSM configuration set.