Skip to main content
Before KMIP connections can occur, the MongoDB instance and KMES Series 3 must establish a mutual trust relationship by validating their respective digitally signed certificates. The following sections outline how to generate TLS certificates for MongoDB and the KMIP server connection pair on the KMES Series 3. In addition to securing TLS communication, MongoDB also uses certificates to authenticate to the KMES, and you create a role and identity on the KMES to give MongoDB the permissions it needs to generate the master key and use it for encryption operations.

​
Configure TLS communication

Perform the following tasks to configure TLS communication between the KMES Series 3 and the MongoDB:
  1. Generate and sign a MongoDB certificate.
  2. Configure TLS certificates for the KMIP server connection pair.
The following sections describe how to perform these tasks.

​
Generate and sign the certificate

Perform one of the following optional methods to generate and sign the MongoDB client certificate:
  • Use an external CA
  • Use the KMES Series 3 as the CA

​
Method 1: Use an external CA

For this method, you must import the external CA certificates into an empty certificate container on the KMES. Then, generate a Certificate Signing Request (CSR), which the external CA uses to issue a TLS certificate for the MongoDB instance. Finally, import the certificate into the certificate container on the KMES that contains the external CA certificate.
1
Go to PKI > Certificate Authorities and select [ Add CA ] at the bottom of the page.
2
Specify a name for the certificate container, such as Externally Issued, and select [ OK ]*.
The new certificate container displays in the Certificate Authorities menu.
3
Right-click the certificate container and select Import > Certificate(s).
4
In the Import Certificates window, select [ Add ] and select the external CA certificates that issue the MongoDB TLS certificate.
The CA certificates display in the Verified section of the Import Certificates window.
5
Select [ OK ] to save.
The external CA certificates now display in tree form under the Externally Issued certificate container.
6
To create a placeholder code signing certificate, from which you can generate a CSR, right-click the lowest level CA certificate in the tree and select Add Certificate > Pending.
7
On the Subject DN tab of the Create X.509 Certificate window, set a Common Name for the certificate, such as MongoDB.
8
Leave all other fields set to the default values and select [ OK ]*.
The MongoDB placeholder certificate now displays under the external CA certificate(s).
9
Right-click the placeholder MongoDB certificate and select Export > Signing Request.
10
On the Subject DN tab of the Create PKCS #10 Request window, leave all fields set to the default values.
11
On the V3 Extensions tab, select the TLS Client Certificate profile.
12
On the PKCS #10 Info tab, specify a save location for the CSR and select [ OK ].
A message box states that the certificate signing request was successfully written to the location you specified.
13
Send the CSR file to an external certificate authority. After the external CA uses the CSR to issue a TLS certificate, copy the certificate to the storage medium configured on the KMES.
14
In the PKI > Certificate Authorities menu on the KMES, right-click the placeholder MongoDB certificate and select Replace > With Signed Certificate.
15
In the Import Certificates window, select [ Add ] and select the externally signed TLS certificate.
The certificate displays under the CA certificates in the Verified section.
16
Select [ OK ] to save.
17
To enable exporting the MongoDB certificate as a PKCS #12 file, go to Administration > Configuration > Options and select the checkbox next to the menu option Allow export of certificates using passwords. Then select [ Save ].
18
Right-click the MongoDB certificate and select Export > PKCS12.
19
In the Export PKCS12 window, set a password for the PKCS #12 file and set Export Options to Export Selected Certificate, then select [ Next ].
20
In the file browser, specify a name for the file, select a save location, and select [ Open ].
21
Copy the PKCS #12 file (which contains the signed MongoDB certificate and its associated private key, encrypted under the password set for the file) and the external CA certificate chain that signed it to the MongoDB server.

​
Method 2: Use the KMES Series 3 as the CA

Perform the following steps to use the KMES Series 3 as the CA:
1
Go to PKI > Certificate Authorities and select [ Add CA] at the bottom of the page.
2
Specify a name for the certificate container, such as KMES Issued, and select [ OK ].
The new Certificate Container displays in the Certificate Authorities menu.
3
Right-click the newly created certificate container and select Add Certificate > New Certificate.
4
On the Subject DN tab, select the Classic Preset and set a Common Name for the certificate, such as Root.
5
On the Basic Info tab, leave all fields set to the default values.
6
On the V3 Extensions tab, select the Certificate Authority profile and select [ OK ].
The Root CA certificate now displays in the KMES Issued certificate container.
7
Right-click the Root CA certificate you just created and select Add Certificate > New Certificate.
8
On the Subject DN tab, set a Common Name for the certificate, such as MongoDB.
9
On the Basic Info tab, leave all fields set to the default values.
10
On the V3 Extensions tab, change the profile to TLS Client Certificate and select [ OK ] to finish generating the certificate.
11
To enable exporting the MongoDB certificate as a PKCS #12 file, go to Administration > Configuration > Options and select the checkbox next to the menu option: Allow export of certificates using passwords. Then, select [ Save ].
12
Right-click the MongoDB certificate and select Export > PKCS12.
13
In the Export PKCS12 window, set a password for the PKCS #12 file, set Export Options to Export Selected Certificate, and select [ Next ].
14
In the file browser, specify a name for the file, select a save location, and select [ Open ].
15
Copy the PKCS #12 file (which contains the signed MongoDB certificate and its associated private key, encrypted under the password set for the file) and the external CA certificate chain that signed it to the MongoDB server.

​
Configure TLS certificates

To configure TLS certificates for the KMIP server connection pair, perform the following tasks, as shown in the following sections:
  1. Generate a new PKI key pair and CSR.
  2. Issue a certificate from the KMIP connection pair CSR.
  3. Export the root CA and KMIP certificates as PEM files.
  4. Import the signed KMIP connection pair certificate.

​
Generate a key pair and CSR

Perform the following steps to generate a new PKI key pair and CSR for the KMIP connection pair:
1
Go to Administration > Configuration > Network Options and go to the TLS/SSL Settings tab.
2
Select the Connection drop-down option and select the KMIP connection pair. Enable the KMIP connection pair if it is not already enabled.
3
Uncheck Use System/Host API SSL Parameters if it is selected.
4
In the User Certificates section, uncheck Use Futurex certificates if it is selected and select [ Edit ] next to PKI keys.
5
In the Application Public Keys window, select [ Generate ].
6
In the PKI Parameters window, leave all fields set to the defaults and select [ OK ]*.
The Application Public Keys window now shows that a PKI Key Pair is Loaded.
7
Select [ Request ].
8
On the Subject DN tab of the Create PKCS #10 Request window, change the Common Name value to the IP address of the KMES.
9
On the V3 Extensions tab, set the profile to TLS Server Certificate.
10
On the PKCS #10 Info tab, specify a save location and name for the CSR file and select [ OK ].
11
When prompted that the certificate signing request was successfully written to the specified location, select [ OK ]*.
12
Select [ OK ] in the Application Public Keys window, then select [ OK ] in the main Network Options window.

​
Issue a certificate

Perform the following steps to issue a certificate from the KMIP connection pair CSR:
1
Go to PKI > Certificate Authorities.
2
Right-click the root CA certificate that issued the MongoDB TLS certificate and select Add Certificate > From Request.
3
In the file browser, select the KMIP connection pair CSR.
Certificate information should populate in the Create X.509 From CSR window.
4
Leave all settings exactly as they are and select [ OK ] to save.
The signed KMIP server certificate now displays under the root CA certificate that issued it.

​
Export the root CA and KMIP certificates

Perform the following steps to export both the root CA certificate and the signed KMIP connection pair certificate as PEM files:
1
Right-click the certificate and select Export > Certificate(s).
2
In the Export Certificate window for each, change the encoding to PEM, then specify a save location for the file.
3
You must copy the root CA certificate to the machine that is running MongoDB.

​
Import the certificate

Perform the following steps to import the signed KMIP connection pair certificate:
1
Go to Administration > Configuration > Network Options and select the TLS/SSL Settings tab.
2
Select the Connection drop-down option and select the KMIP connection pair.
3
Select [ Edit ] next to Certificates in the User Certificate section.
4
In the Certificate Authority window, right-click the KMIP SSL CA X.509 certificate container and select [ Import ].
5
Select [ Add ] at the bottom of the Import Certificates window.
6
In the file browser, select both the root CA certificate and the signed KMIP server certificate and select [ Open ].
The certificates should now display in the Verified section of the Import Certificates window.
7
Select [ OK ] to save.
It now shows Signed loaded next to Certificates in the User Certificates section for the KMIP connection pair.
8
Select [ OK ] to save.

​
Configure general KMES settings

Perform the following tasks to configure the KMES Series 3 for communication with MongoDB:
  1. Add a PKI identity provider.
  2. Create a MongoDB role and identity with the required permissions.
  3. Grant the MongoDB role the Use permission.
The following sections show you how to complete these tasks.

​
Add a PKI identity provider

Perform the following steps to create a new PKI identity provider, assign it a TLS authentication mechanism, and add it to an identity as a credential. This enables MongoDB to authenticate with the KMES by using its TLS certificate.
1
Go to Identity Management > Identity Providers.
2
Right-click anywhere in the window and select Add > Provider > PKI.
3
On the Info tab of the Identity Provider Editor window, specify a name for the identity provider and uncheck the Enforce Dual Factor checkbox.
4
On the PKI Options tab, select [ Select ] to open the Certificate Selector window. Expand the certificate tree you created, select the CA certificate that signed the MongoDB and KMIP connection pair certificates, and select [ OK ].
5
Select [ OK ] to finish creating the PKI Identity Provider.
6
Right-click the identity provider you just created and select Add > Mechanism > TLS.
7
On the Info tab, specify a name for the authentication mechanism.
8
On the PKI tab, leave all fields set to the default values.
9
Select [ OK ] to save.

​
Create a role and identity

Perform the following steps to create a new role and identity for MongoDB with the required permissions on the KMES Series 3, which MongoDB uses for authentication during KMIP connections. The name of this identity must match exactly what you set later as the Common Name for the signed MongoDB certificate. The KMES Series 3 uses the role and identity to authenticate the MongoDB device connecting through KMIP.

​
Create a role

Perform the following steps to create a role:
1
Log in to the KMES Series 3 application interface with the default Admin identities.
2
Go to Identity Management > Roles and select [ Add ].
3
On the Info tab of the Role Editor window, set the Type to Application, set a name for the role, such as MongoDB, and set the Logins Required to 1.
4
On the Permissions tab, enable the following permissions:
PermissionsSubpermissions
Cryptographic OperationsSign, Verify, Encrypt, Decrypt
KeysAdd, Export, Delete, Modify
Secure Key FunctionsClear Export
5
On the Advanced tab, set the Allowed Ports to KMIP only.
6
Select [ OK ] to finish creating the role.

​
Create an identity

Perform the following steps to create an identity:
1
Go to Identity Management > Identities, right-click anywhere in the window, and select Add > Client Application.
2
On the Info tab of the Identity Editor window, select Application for the storage location and specify a name for the identity.
3
Under Assigned Roles, select the role you created for MongoDB.
4
Under Authentication, remove the default API Key mechanism and select [ Add ] to add a new credential.
5
In the Configure Credential window, select TLS Certificate in the Type drop-down menu and select the Provider and Mechanism you created for this integration. Select [ OK ] to finish configuring the credential.

​
Grant the permissions

Grant the MongoDB role Use permissions on the PKI identity provider and the certificate container:
1
Go to Identity Management > Identity Providers.
2
Right-click the PKI identity provider created for this integration and select [ Permission ].
3
Check the Show all roles and permissions box located at the bottom of the Set Object-Group Permissions window.
4
Set the Use permission for the MongoDB role and select **[ OK ]***to save.
5
Go to PKI > Certificate Authorities.
6
Right-click the certificate container created for this integration and select [ Permission ].
7
Check the Show all roles and permissions box located at the bottom of the Set Object-Group Permissions window.
8
Set the Use permission for the MongoDB role and select [ OK ] to save.