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.