Using SmartKey™ for MongoDB Encryption at Rest

Updated: Aug 28, 2018

Overview

MongoDB Enterprise version supports encryption of data at rest. The data encryption process involves generating a master key which is the root of the key hierarchy of various keys used by MongoDB.

Cryptographically secure generation and secure management of this master key is required for true security of data at rest encrypted by MongoDB. SmartKey with its KMIP support provides a secure and flexible solution for this.

MongoDB supports KMIP and it authenticates to a KMIP enabled key management server using client certificate. SmartKey supports clients / apps to authenticate using API Key, App Id and certificate or just certificate. In this article we will describe how to setup an app in SmartKey for MongoDB to integrate with SmartKey.

Adding App in SmartKey

Start by adding an App in SmartKey in an appropriate group or a new group. For instructions of how to add a group or app please use Getting Started Guide

Once you have added the application, note down its App-Id by copying App UUID from App table view by clicking on icon for “Copy UUID” as show below. You will need this App-Id for the certificate.

ec-created

If an App / Client needs to authenticate to SmartKey using only certificate, then the App Id needs to be embedded in the certificate in one of the following ways:

  • Provided as value of a custom OID in certificate 1.3.6.1.4.1.49690.1.2.1

Standard human-readable UUID encoding: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

  • Provided as value of CN

We will explain how to generate a client certificate to use with MongoDB for each of these methods.

Creating client certificate with custom OID value

You can generate a self-signed certificate such that the custom OID is part of the certificate. To achieve this edit file /etc/ssl/openssl.cnf and add the custom oid in “new_oids” section. These sections in the file should look as follows

oid_section             = new_oids

# To use this configuration file with the "-extfile" option of the
# "openssl x509" utility, name here the section containing the
# X.509v3 extensions to use:
# extensions            = 
# (Alternatively, use a configuration file that has only
# X.509v3 extensions in its main [= default] section.)

[ new_oids ]
my_app_id=1.3.6.1.4.1.49690.1.2.1

Now add a description in “req_distinguished_name” section. In this section add a line as follows

my_app_id = custom attribute for app id

Save the file and generate self-signed certificate as usual. This will prompt for the value of custom attribute where you should enter the App Id you noted earlier.

Generated certificate will have the value of custom OID populated.

Examine the subject in certificate to verify it contains the custom OID. A correctly generated certificate should look as follows (note the value of custom OID in subject)

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 18122652583846371291 (0xfb809881cffa5fdb)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=US, ST=California, L=Mountain View, O=Fortanix Inc, OU=Engineering, CN=test.kmip.fortanix.com/emailAddress=test@fortanix.com/1.3.6.1.4.1.49690.1.2.1=acc15bf3-e626-47aa-9373-7b08b3f26ee8
        Validity
            Not Before: Aug  8 23:19:45 2018 GMT
            Not After : Aug  8 23:19:45 2019 GMT
        Subject: C=US, ST=California, L=Mountain View, O=Fortanix Inc, OU=Engineering, CN=test.kmip.fortanix.com/emailAddress=test@fortanix.com/1.3.6.1.4.1.49690.1.2.1=acc15bf3-e626-47aa-9373-7b08b3f26ee8
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:97:a4:5b:d4:11:ee:c6:89:e1:f8:44:39:f9:69:
                    43:be:ee:69:78:5b:32:26:53:9d:a7:46:f4:17:0e:
                    5a:dc:b4:58:23:af:69:a1:86:de:2e:c5:46:14:98:
                    b6:6a:fc:f5:26:73:f7:56:6f:60:d8:2c:52:69:c9:
                    58:2a:d6:fd:4e:6e:22:0d:8c:e5:99:01:10:70:59:
                    6c:68:a2:a8:ee:e6:37:f7:08:8a:8a:75:bb:91:2b:
                    db:ad:1c:03:56:5f:01:ae:55:ff:3a:8b:40:91:e7:
                    04:4d:49:31:76:dc:ec:9e:d5:cb:d5:73:00:4f:13:
                    f2:12:f3:45:9f:df:fc:aa:2d:5f:d4:95:b2:e9:fa:
                    ad:38:d8:36:a5:f3:99:92:e5:b4:0a:39:99:85:ee:
                    13:39:fb:8d:1c:7a:52:03:e3:86:8a:d8:24:e9:28:
                    70:18:72:e0:b5:e6:f2:66:6f:1c:1a:be:f7:23:2c:
                    e0:9f:79:2b:2e:6e:be:c6:b1:31:65:00:cb:9c:8b:
                    bd:c0:56:dc:bd:0c:24:6a:d2:20:91:5f:14:84:63:
                    ef:18:b2:de:33:a8:ec:dd:4e:a5:3f:11:7b:7d:eb:
                    a1:e1:49:fc:d7:9e:26:98:6f:cb:3b:7e:5d:7e:2d:
                    1e:34:ca:3a:f9:12:95:b2:aa:ff:40:95:e1:5e:b9:
                    a5:a3
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Key Identifier: 
                9C:74:2E:5B:16:76:F9:59:9F:E0:B5:53:C9:26:45:45:F7:4C:8D:99
            X509v3 Authority Key Identifier: 
                keyid:9C:74:2E:5B:16:76:F9:59:9F:E0:B5:53:C9:26:45:45:F7:4C:8D:99

            X509v3 Basic Constraints: 
                CA:TRUE
    Signature Algorithm: sha256WithRSAEncryption
         72:95:6a:8a:4c:18:53:e9:f6:3d:87:e9:97:d2:48:fe:2b:60:
         ea:e2:ca:81:cb:9b:15:48:38:30:62:16:6b:b0:54:f6:91:2d:
         b0:72:af:36:36:39:8e:78:1f:8c:17:19:df:5c:e5:ae:4d:f4:
         ae:41:39:04:f2:95:d1:0a:99:ef:ef:63:72:5e:83:96:c1:c7:
         f1:d7:f6:45:58:23:76:3d:1a:ba:a3:08:e4:4a:a0:6a:33:8f:
         e5:50:04:b1:08:74:b3:37:9c:fd:f9:9c:5d:27:7d:63:a8:7d:
         40:3e:d5:aa:7d:a7:9e:70:79:38:91:45:68:29:0d:a8:80:42:
         f8:9b:e0:17:bb:93:9f:71:89:04:0f:39:d0:2e:3c:10:62:44:
         6b:41:5d:e5:78:42:50:c5:f7:ee:bc:a8:5e:90:01:ad:3c:f2:
         27:f2:81:16:ba:1e:79:d8:c4:09:cb:01:fd:71:11:9f:91:14:
         72:71:0f:f1:d3:b0:4d:91:78:dd:12:fb:fd:d6:22:93:15:67:
         df:4e:da:df:74:de:68:95:d7:d8:70:48:e2:5f:bc:ec:b2:0f:
         bb:14:83:ad:c9:f9:a0:81:0d:a8:68:64:77:db:5a:71:4a:8b:
         8f:91:d6:ce:e1:33:42:ba:98:76:a1:cd:89:8e:3a:cb:aa:b1:
         8e:ca:42:af

Creating client certificate with App Id as CN

You can generate a self-signed certificate such that the CN contains the App Id.

Generate self-signed certificate as usual. When prompted for Common Name, you should enter the App Id you noted earlier.

Generated certificate will have App Id as CN.

Examine the subject in certificate to verify it contains the App Id as CN. A correctly generated certificate should look as follows (note the value of CN)

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 11285796284824083476 (0x9c9f33ed245cdc14)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=US, ST=CA, L=Mountain View, O=Fortanix, OU=Test, CN=da7f2800-4122-4681-aebf-90beb779b73f/emailAddress=test@fortanix.com
        Validity
            Not Before: Aug  8 23:31:20 2018 GMT
            Not After : Aug  8 23:31:20 2019 GMT
        Subject: C=US, ST=CA, L=Mountain View, O=Fortanix, OU=Test, CN=da7f2800-4122-4681-aebf-90beb779b73f/emailAddress=test@fortanix.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:d2:ae:15:66:bf:78:d4:98:f4:4d:a5:57:bf:04:
                    08:76:83:1f:40:e8:8b:c4:da:8a:a0:71:22:43:84:
                    6d:c9:05:f2:81:91:83:04:75:bd:c9:83:86:92:bf:
                    ff:a0:e4:b4:e4:ee:56:09:10:2a:dc:e2:f4:0c:65:
                    43:96:a1:31:0d:15:92:49:87:ee:46:91:5d:f1:8c:
                    61:b3:ca:4a:9f:be:01:00:d5:30:5f:ee:56:35:75:
                    3c:e1:0d:a6:34:66:7f:3b:26:69:97:33:6d:2e:c7:
                    fd:c9:42:7d:14:f7:12:18:4a:5b:a6:90:52:7a:4b:
                    1b:45:b3:79:33:31:99:03:1d:a4:ed:51:dc:7b:43:
                    20:02:bb:08:22:27:27:8c:51:6a:5f:59:87:45:95:
                    d7:f3:ca:fa:30:3d:d5:a6:50:77:03:e3:de:eb:30:
                    17:45:48:fe:5b:76:d4:c1:03:3f:b8:99:73:ae:ad:
                    ae:e2:69:95:e2:14:1e:42:b1:ac:72:cd:0b:c6:01:
                    e3:20:8d:5a:6a:5d:19:79:17:f0:80:5f:75:fc:d5:
                    da:9c:af:07:d8:c7:96:02:a5:94:19:64:d7:9a:e4:
                    56:f1:cf:54:b9:a7:29:28:22:52:f2:c4:8a:97:04:
                    45:b1:9b:b5:4f:c0:18:53:ff:08:3f:3b:81:bd:f1:
                    d1:e9
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Key Identifier: 
                87:65:C6:B6:B6:3A:0A:A6:30:BA:CB:D2:27:9E:C4:E6:2E:7F:2F:6D
            X509v3 Authority Key Identifier: 
                keyid:87:65:C6:B6:B6:3A:0A:A6:30:BA:CB:D2:27:9E:C4:E6:2E:7F:2F:6D

            X509v3 Basic Constraints: 
                CA:TRUE
    Signature Algorithm: sha256WithRSAEncryption
         71:da:8c:da:ab:9d:6d:8a:f1:9c:56:a9:7d:e2:e2:1b:fd:90:
         b7:5e:45:db:d4:69:47:ca:98:2f:b0:3b:2c:1f:49:3a:75:dd:
         1d:96:b3:bd:11:a6:d7:06:60:4f:18:11:e1:cf:db:5c:52:03:
         29:78:47:6e:36:c0:64:d8:4d:34:00:d9:94:55:48:a9:d4:b2:
         b2:ed:b8:13:fc:3d:c6:b4:61:a3:56:aa:9d:73:80:62:38:da:
         0c:94:b0:4a:e6:86:da:6a:f9:aa:f3:a4:3c:48:32:93:f7:d3:
         27:f9:2c:77:b4:91:9c:84:62:96:86:7d:d2:c8:20:79:d1:12:
         ef:f0:cc:15:31:ea:86:e9:b4:02:00:55:83:0f:6a:c6:5b:d2:
         19:67:9b:b2:44:f8:3b:36:f9:b0:02:b2:98:7d:1e:fa:95:58:
         92:92:57:68:f8:56:bb:43:db:01:08:bb:d6:ab:52:e6:c7:88:
         7a:1c:8d:f4:31:90:70:0a:dd:d2:96:7c:8b:93:8f:1f:4a:80:
         fe:3a:f8:df:82:a7:99:ac:2f:e8:02:e5:8b:fe:ec:3b:3b:0a:
         a3:c0:82:4d:f7:93:66:a1:76:6f:fa:c2:19:8e:d8:b6:b4:27:
         8c:57:22:a4:f7:e6:45:61:27:af:fc:5f:51:88:eb:32:

Setting App Authentication Method as certificate

Once you have the certificate, you will need to change the authentication method for your app in SmartKey to use certificate instead of API key. To change the authentication method, go to the application detail page of your app, navigate to the Info tab, and open the “Change authentication method” drop-down. Select method as “Certificate” and click Save. You will be prompted to upload a certificate. Upload your certificate and click on Update. Now your app is set to authenticate using the certificate you created.

Configuring Encryption in MongoDB

You need to start MongoDB with the options to configure encryption and point it to SmartKey as the key manager. MongoDB will use the certificate you created in the earlier step to authenticate to SmartKey.

NOTE:

  • If you already have data in MongoDB then starting MongoDB with encryption enabled will not work.
  • Certificate needs to be in PEM format.
  • It needs the private key and certificate to be concatenated together in one file.

Copy your private key followed by certificate in a file , say client.pem. It should look as follows

-----BEGIN PRIVATE KEY-----
MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC5/MzwY4GcIkyU
……………………………………………………………………………………………………………………………………………………………………….
9R9EpY5ob2xaorfyEDZR2A==
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIEUTCCAzmgAwIBAgIJAJxAy7ghYZjwMA0GCSqGSIb3DQEBCwUAMIG+MQswCQYD
……………………………………………………………………………………………………………………………………………………………………….
7Do/CpP2WqIk5uojq4SO5Z+/8zs0rzVNwYaKnyMSmxO+c3bC4guYB/vdEcT1wXzy
bDh/HRo=
-----END CERTIFICATE-----

To start MongoDB with encryption enabled and use a new master key, start with the following options

/usr/bin/mongod --config /etc/mongod.conf --enableEncryption --kmipServerName <SmartKey Host name>  --kmipPort 5696 --kmipServerCAFile SmartKey_CA.pem --kmipClientCertificateFile client.pem

Explanation of parameters

--enableEncryption Enable encryption at rest
--kmipServerName arg SmartKey host name
--kmipPort arg KMIP server port (defaults to 5696)
--kmipClientCertificateFile arg Client certificate for authenticating to SmartKey server
--kmipServerCAFile arg CA File for validating connection to SmartKey server. This is optional and only required if you are running an on-prem SDKMS server and it is using a certificate signed by a non-standard CA

For more details on MongoDB encryption at rest and other configuration options, please see MongoDB Manual

Once MongoDB starts and connects to SmartKey successfully, it will request SmartKey to generate a master key (AES-256). You can check this in SmartKey WebUI under Security Objects page. Every time, MongoDB is restarted it will retrieve the value of Master Key from SmartKey after authenticating with it. With SmartKey you will see a complete audit trail if every time this master key is retrieved. You will also have complete control on the master key and you can revoke access to the key or disable it, in case you want to lock down your data at rest.

Following screen shot shows the activity logs for the MongoDB application and an audit trail of master key usage.

ec-created