MongoDB Enterprise version supports the 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 are required for the true security of data at rest encrypted by MongoDB. Fortanix Self-Defending KMS 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 a client certificate. Fortanix Self-Defending KMS supports clients/apps to authenticate using API Key, App Id, and certificate or just certificate. In this article, we will describe how to set up an app in Self-Defending KMS for MongoDB to integrate with Self-Defending KMS.
Adding App in Fortanix Self-Defending KMS
Start by adding an App in Fortanix Self-Defending KMS 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 the App table view by clicking the icon for “Copy UUID” as shown below. You will need this App-Id for the certificate.
If an App / Client needs to authenticate to Fortanix Self-Defending KMS using the only certificate, then the App Id needs to be embedded in the certificate in one of the following ways:
- Provided as the value of a custom OID in certificate
Standard human-readable UUID encoding:
- Provided as the value of CN
We will explain how to generate a client certificate to use with MongoDB for each of these methods.
Creating a 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 the 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=126.96.36.199.4.1.496188.8.131.52
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 a 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 the certificate to verify it contains the custom OID. A correctly generated certificate should look as follows (note the value of custom OID in the 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/emailAddressfirstname.lastname@example.org/184.108.40.206.4.1.496220.127.116.11=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/emailAddressemail@example.com/18.104.22.168.4.1.49622.214.171.124=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 a client certificate with App Id as CN
You can generate a self-signed certificate such that the CN contains the App Id.
Generate a 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 the 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/emailAddressfirstname.lastname@example.org 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/emailAddressemail@example.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 Fortanix Self-Defending KMS to use a certificate instead of an 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 the 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 Fortanix Self-Defending KMS as the key manager. MongoDB will use the certificate you created in the earlier step to authenticate to Fortanix Self-Defending KMS.
- If you already have data in MongoDB then starting MongoDB with encryption enabled will not work.
- The 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 a 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 <SDKMS Host name> --kmipPort 5696 --kmipServerCAFile SDKMS_CA.pem --kmipClientCertificateFile client.pem
Explanation of parameters
|--enableEncryption||Enable encryption at rest|
|--kmipServerName arg||Fortanix Self-Defending KMS hostname|
|--kmipPort arg||KMIP server port (defaults to 5696)|
|--kmipClientCertificateFile arg||Client certificate for authenticating to Fortanix Self-Defending KMS server|
|--kmipServerCAFile arg||CA File for validating connection to the Fortanix Self-Defending KMS server. This is optional and only required if your Fortanix Self-Defending KMS server (On-Prem) 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 Fortanix Self-Defending KMS successfully, it will request Self-Defending KMS to generate a master key (AES-256). You can check this in Fortanix Self-Defending KMS WebUI under the Security Objects page. Every time, MongoDB is restarted it will retrieve the value of Master Key from Fortanix Self-Defending KMS after authenticating with it. With Fortanix Self-Defending KMS you will see a complete audit trail if every time this master key is retrieved. You will also have complete control over 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.
The following screenshot shows the activity logs for the MongoDB application and an audit trail of the master key usage.