MongoDB and Entrust KeyControl: Integration Guide

1. Start MongoDB.

   % sudo systemctl start mongod

2. Verify that MongoDB has started successfully.

   % sudo systemctl status mongod
   
   mongod.service - MongoDB Database Server
        Loaded: loaded (/lib/systemd/system/mongod.service; disabled; vendor preset: enabled)
        Active: active (running) since Mon 2021-07-19 16:27:45 EDT; 46s ago
          Docs: https://docs.mongodb.org/manual
      Main PID: 2947 (mongod)
        Memory: 62.8M
        CGroup: /system.slice/mongod.service
                └─2947 /usr/bin/mongod --config /etc/mongod.conf
   
   Jul 19 16:27:45 mongodb-ubuntu-20 systemd[1]: Started MongoDB Database Server.

3. Stop MongoDB.

   % sudo systemctl stop mongod

4. Restart MongoDB.

   % sudo systemctl restart mongod

5. View the log file used by MongoDB at /var/log/mongodb/mongod.log .

   You can follow the state of the process for errors or important messages by watching the output in the /var/log/mongodb/mongod.log file.

6. Begin using MongoDB.

   Start a mongosh session on the host machine where mongod is running. You can run mongosh without any command-line options to connect to a mongod that is running on your localhost with default port 27017 :

   % mongosh
   
   Current Mongosh Log ID: 60f5e17a21539927be5d0f9d
   Connecting to:          mongodb://127.0.0.1:27017/?directConnection=true&serverSelectionTimeoutMS=2000
   Using MongoDB:          5.0.0
   Using Mongosh:          1.0.0
   
   See: https://docs.mongodb.com/mongodb-shell/.
   
   
   To help improve our products, anonymous usage data is collected and sent to MongoDB periodically (https://www.mongodb.com/legal/privacy-policy).
   You can opt-out by running the disableTelemetry() command.
   
   ------
      The server generated these startup warnings when booting:
      2021-07-19T16:27:45.890-04:00: Using the XFS file system is strongly recommended with the WiredTiger storage engine. See http://dochub.mongodb.org/core/prodnotes-filesystem
      2021-07-19T16:27:46.427-04:00: Access control is not enabled for the database. Read and write access to data and configuration is unrestricted
   ------
   
   Enterprise test>

7. Create a test database;

   % Enterprise test> use mydb1;
   
   switched to db mydb1
   
   % Enterprise mydb1> db
   
   mydb1

8. Insert an entry into the database.

   % Enterprise mydb1> db.movie.insertOne({"name":"tutorials point"})
   
   {
     acknowledged: true,
     insertedId: ObjectId("60f73d77d932673cb91de215")
   }

9. List the databases.

   > Enterprise mydb1> show dbs
   
   admin     41 kB
   config  73.7 kB
   local     41 kB
   mydb1     41 kB

10. Drop the test database.

    % Enterprise mydb1> db.dropDatabase()
    
    { ok: 1, dropped: 'mydb1' }

If you were able to create the database and perform the commands above, the installation is validated.

When you added the security section to the mongod.conf file, add the KeyControl hostname.domainname to the /etc/hosts file to resolve the IP address of the KMIP server to the hostname. The hostname must match the hostname used in the mongod.conf and cannot be an IP address. The hostname must also contain the subdomain.

Once you have finished configuring the mongod.conf and hosts files, start MongoDB. When started, MongoDB will attempt to retrieve an encryption key stored on KeyControl. If MongoDB does not find a key, it creates one and stores it in KeyControl.

If you try enable encryption on an existing instance of MongoDB and data already exists in the MongoDB data directory /var/lib/mongodb , you will get an error when you start the mongod service. You can only have encryption enabled in a blank data directory. See Enable encryption on an existing MongoDB instance for instructions on how to get around the issue.

To confirm that the master key was successfully created, log in to KeyControl and look at KMIP Configuration Settings > Objects .

You should see the master key that you have just created.

1. Stop the network services on the MongoDB server and try to restart the mongod service.

   The mongod service will not start because it can’t connect to one of the KeyControl servers.

   % sudo systemctl restart mongod
   % sudo systemctl status mongod
   
   mongod.service - MongoDB Database Server
        Loaded: loaded (/lib/systemd/system/mongod.service; disabled; vendor preset: enabled)
        Active: failed (Result: exit-code) since Wed 2021-07-21 11:28:36 EDT; 1min 42s ago
          Docs: https://docs.mongodb.org/manual
       Process: 16120 ExecStart=/usr/bin/mongod --config /etc/mongod.conf (code=exited, status=14)
      Main PID: 16120 (code=exited, status=14)
   
   Jul 21 11:28:35 mongodb-ubuntu-20 systemd[1]: Started MongoDB Database Server.
   Jul 21 11:28:36 mongodb-ubuntu-20 systemd[1]: mongod.service: Main process exited, code=exited, status=14/n/a
   Jul 21 11:28:36 mongodb-ubuntu-20 systemd[1]: mongod.service: Failed with result 'exit-code'.

2. Restart the network services and try again and you will see that mongod starts successfully.

   mongod.service - MongoDB Database Server
        Loaded: loaded (/lib/systemd/system/mongod.service; disabled; vendor preset: enabled)
        Active: active (running) since Wed 2021-07-21 11:32:49 EDT; 8s ago
          Docs: https://docs.mongodb.org/manual
      Main PID: 16297 (mongod)
        Memory: 165.0M
        CGroup: /system.slice/mongod.service
                └─16297 /usr/bin/mongod --config /etc/mongod.conf
   
   Jul 21 11:32:49 mongodb-ubuntu-20 systemd[1]: Started MongoDB Database Server.

When MongoDB is encrypted, it is only accessible when KeyControl is available and master key is found.

1. Bring down one of the KeyControl nodes and check that you can access MongoDB.

1. Attempt to start up mongod when one of the KeyControl nodes in the cluster is down.

   % sudo systemctl restart mongod
   % sudo systemctl status mongod
   
   mongod.service - MongoDB Database Server
        Loaded: loaded (/lib/systemd/system/mongod.service; disabled; vendor preset: enabled)
        Active: active (running) since Wed 2021-07-21 11:57:47 EDT; 10s ago
          Docs: https://docs.mongodb.org/manual
      Main PID: 16922 (mongod)
        Memory: 166.9M
        CGroup: /system.slice/mongod.service
                └─16922 /usr/bin/mongod --config /etc/mongod.conf

When one of its nodes is down, the KeyControl cluster goes out of Healthy status. New keys can only be created when the cluster is in Healthy status. Therefore, rotating keys should not be attempted when one of the nodes in the cluster is down.

You can rotate the master key, the only externally managed key. With the new master key, the internal keystore will be re-encrypted but the database keys will be otherwise left unchanged. This obviates the need to re-encrypt the entire data set.

1. Add the following to /etc/mongod.conf under the kmip settings:

     kmip:
       rotateMasterKey: true

2. Restart the mongod service:

   % sudo systemctl restart mongod

3. When the master key has been rotated and the database keystore has been re-encrypted, mongod exits and restarts with the new key. This is visible when you check the status of mongod .

   % sudo systemctl status mongod
   
   mongod.service - MongoDB Database Server
        Loaded: loaded (/lib/systemd/system/mongod.service; disabled; vendor preset: enabled)
        Active: inactive (dead)
          Docs: https://docs.mongodb.org/manual
   
   Jul 21 11:32:49 mongodb-ubuntu-20 systemd[1]: Started MongoDB Database Server.
   Jul 21 11:57:47 mongodb-ubuntu-20 systemd[1]: Stopping MongoDB Database Server...
   Jul 21 11:57:47 mongodb-ubuntu-20 systemd[1]: mongod.service: Succeeded.
   Jul 21 11:57:47 mongodb-ubuntu-20 systemd[1]: Stopped MongoDB Database Server.
   Jul 21 11:57:47 mongodb-ubuntu-20 systemd[1]: Started MongoDB Database Server.
   Jul 21 12:07:53 mongodb-ubuntu-20 systemd[1]: Stopping MongoDB Database Server...
   Jul 21 12:07:53 mongodb-ubuntu-20 systemd[1]: mongod.service: Succeeded.
   Jul 21 12:07:53 mongodb-ubuntu-20 systemd[1]: Stopped MongoDB Database Server.
   Jul 21 12:07:53 mongodb-ubuntu-20 systemd[1]: Started MongoDB Database Server.
   Jul 21 12:07:56 mongodb-ubuntu-20 systemd[1]: mongod.service: Succeeded.

4. Remove the kmip rotateMasterKey setting from the /etc/mongod.conf file by commenting it out.

     kmip:
   #    rotateMasterKey: true

5. When the key is rotated, check on KeyControl if the master key is rotated.

   To confirm that the new master key was successfully created, log in to KeyControl, look at the Objects tab under KMIP Configuration Settings as shown below.

   You will find a new key created in KeyControl. You should also be able to see the creation of the key in the KeyControl Audit Logs.

If for some reason you have not yet configured a HSM to be used with KeyControl, it has to be configured now.

Initialize the HSM on KeyControl

Add the KeyControl node(s) to the HSM

Set up the nShield HSM Server

Enable KMIP service and KMIP key wrapping

Test the HSM usage

If you try enable encryption on an existing instance of MongoDB and data already exists in the MongoDB data directory /var/lib/mongodb, you should get an error like this when you start the mongod service:

When you look in /var/log/mongodb/mongod.log for what may be causing the failure, you should see errors like this:

The error clearly states that the data files are present in the db path without any key store. This translates to how it works with mongodb - you can only have encryption enabled in a blank data directory. You can achieve this by taking the backup, stopping the mongod instance, clearing the data directory, restarting by enabling encryption and then restore from backup.

1. Comment out the security section in /etc/mongod.conf .

   If you already added the security section to /etc/mongod.conf , comment it out.

   #security:
   #  enableEncryption: true
   #  encryptionCipherMode: AES256-GCM
   #  kmip:
   #    serverName: htkeycontrol54-1.interop.com,htkeycontrol54-2.interop.com
   #    port: 5696
   #    clientCertificateFile: /opt/mongodb/security/MONGODB.pem
   #    serverCAFile: /opt/mongodb/security/cacert.pem

2. Restart the mongod service.

   % sudo systemctl start mongod
   % sudo systemctl status mongod
   
   mongod.service - MongoDB Database Server
        Loaded: loaded (/lib/systemd/system/mongod.service; disabled; vendor preset: enabled)
        Active: active (running) since Wed 2021-07-21 13:58:34 EDT; 2s ago
          Docs: https://docs.mongodb.org/manual
      Main PID: 17392 (mongod)
        Memory: 158.6M
        CGroup: /system.slice/mongod.service
                └─17392 /usr/bin/mongod --config /etc/mongod.conf

3. Make a backup of the data.

   % sudo mkdir -p /data/backup
   % sudo mongodump --out=/data/backup
   
   2021-07-21T14:22:13.433-0400    writing admin.system.version to /data/backup/admin/system.version.bson
   2021-07-21T14:22:13.434-0400    done dumping admin.system.version (1 document)
   2021-07-21T14:22:13.435-0400    writing mydb1.movie to /data/backup/mydb1/movie.bson
   2021-07-21T14:22:13.435-0400    done dumping mydb1.movie (1 document)

4. Put the security section back in /etc/mongod.conf .

   security:
     enableEncryption: true
     encryptionCipherMode: AES256-GCM
     kmip:
       serverName: htkeycontrol54-1.interop.com,htkeycontrol54-2.interop.com
       port: 5696
       clientCertificateFile: /opt/mongodb/security/MONGODB.pem
       serverCAFile: /opt/mongodb/security/cacert.pem

5. Clean up the data directory /var/lib/mongodb and remove all files and directories.

   % cd /var/lib
   % cp -rp mongodb mongodb.backup
   % rm -rf mongodb/*

6. Restart the mongod service.

   % sudo systemctl start mongod
   % sudo systemctl status mongod
   
   mongod.service - MongoDB Database Server
        Loaded: loaded (/lib/systemd/system/mongod.service; disabled; vendor preset: enabled)
        Active: active (running) since Wed 2021-07-21 14:15:57 EDT; 5s ago
          Docs: https://docs.mongodb.org/manual
      Main PID: 17502 (mongod)
        Memory: 60.8M
        CGroup: /system.slice/mongod.service
                └─17502 /usr/bin/mongod --config /etc/mongod.conf
   
   Jul 21 14:15:57 mongodb-ubuntu-20 systemd[1]: Started MongoDB Database Server.

7. Restore the backup.

   % sudo mongorestore /data/backup
   
   2021-07-21T14:25:14.479-0400    preparing collections to restore from
   2021-07-21T14:25:14.479-0400    reading metadata for mydb1.movie from /data/backup/mydb1/movie.metadata.json
   2021-07-21T14:25:14.490-0400    restoring mydb1.movie from /data/backup/mydb1/movie.bson
   2021-07-21T14:25:14.501-0400    finished restoring mydb1.movie (1 document, 0 failures)
   2021-07-21T14:25:14.501-0400    no indexes to restore for collection mydb1.movie
   2021-07-21T14:25:14.501-0400    1 document(s) restored successfully. 0 document(s) failed to restore.

The existing data should be now protected by encryption.