> ## Documentation Index
> Fetch the complete documentation index at: https://docs.futurex.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure KMES Series 3
> Step-by-step instructions to configure KMES Series 3 for mutual TLS authentication with MongoDB before KMIP connections.
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.
Go to **PKI** > **Certificate** **Authorities** and select **\[ Add CA ]** at the bottom of the page.
Specify a name for the certificate container, such as `Externally Issued`, and select **\[ OK ]**\*.
The new certificate container displays in the Certificate Authorities menu.
Right-click the certificate container and select **Import** > **Certificate(s)**.
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.
Select **\[ OK ]** to save.
The external CA certificates now display in tree form under the Externally Issued certificate container.
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**.
On the **Subject DN** tab of the **Create X.509 Certificate** window, set a **Common** **Name** for the certificate, such as `MongoDB`.
Leave all other fields set to the default values and select **\[ OK ]**\*.
The MongoDB placeholder certificate now displays under the external CA certificate(s).
Right-click the placeholder MongoDB certificate and select **Export** > **Signing** **Request**.
On the **Subject DN** tab of the **Create PKCS #10 Request** window, leave all fields set to the default values.
On the **V3** **Extensions** tab, select the **TLS Client Certificate** profile.
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.
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.
In the **PKI** > **Certificate** **Authorities** menu on the KMES, right-click the placeholder MongoDB certificate and select **Replace** > **With** **Signed** **Certificate**.
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.
Select **\[ OK ]** to save.
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 ]**.
Right-click the MongoDB certificate and select **Export** > **PKCS12**.
In the **Export PKCS12** window, set a password for the PKCS #12 file and set **Export Options** to **Export Selected Certificate**, then select **\[ Next ]**.
In the file browser, specify a name for the file, select a save location, and select **\[ Open ]**.
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:
Go to **PKI** > **Certificate** **Authorities** and select **\[ Add CA]** at the bottom of the page.
Specify a name for the certificate container, such as `KMES Issued`, and select **\[ OK ]**.
The new Certificate Container displays in the Certificate Authorities menu.
Right-click the newly created certificate container and select **Add** **Certificate** > **New** **Certificate**.
On the **Subject DN** tab, select the **Classic** Preset and set a **Common Name** for the certificate, such as `Root`.
On the **Basic Info** tab, leave all fields set to the default values.
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.
Right-click the **Root** CA certificate you just created and select **Add Certificate** > **New Certificate**.
On the **Subject DN** tab, set a **Common Name** for the certificate, such as `MongoDB`.
On the **Basic Info** tab, leave all fields set to the default values.
On the **V3** **Extensions** tab, change the profile to **TLS Client Certificate** and select **\[ OK ]** to finish generating the certificate.
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 ]**.
Right-click the MongoDB certificate and select **Export** > **PKCS12**.
In the **Export** **PKCS12** window, set a password for the PKCS #12 file, set **Export Options** to **Export** **Selected** **Certificate**, and select **\[ Next ]**.
In the file browser, specify a name for the file, select a save location, and select **\[ Open ]**.
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:
Go to **Administration** > **Configuration** > **Network** **Options** and go to the **TLS/SSL Settings** tab.
Select the **Connection** drop-down option and select the **KMIP** connection pair. **Enable** the KMIP connection pair if it is not already enabled.
Uncheck **Use System/Host API SSL Parameters** if it is selected.
In the **User** **Certificates** section, uncheck **Use** **Futurex** **certificates** if it is selected and select **\[ Edit ]** next to **PKI** **keys**.
In the **Application Public Keys** window, select **\[ Generate ]**.
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.
Select **\[ Request ]**.
On the **Subject DN** tab of the **Create PKCS #10 Request** window, change the **Common** **Name** value to the IP address of the KMES.
On the **V3 Extensions** tab, set the profile to **TLS Server Certificate**.
On the **PKCS #10 Info** tab, specify a save location and name for the CSR file and select **\[ OK ]**.
When prompted that the certificate signing request was successfully written to the specified location, select **\[ OK ]**\*.
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:
Go to **PKI** > **Certificate** **Authorities**.
Right-click the root CA certificate that issued the MongoDB TLS certificate and select **Add** **Certificate** > **From** **Request**.
In the file browser, select the KMIP connection pair CSR.
Certificate information should populate in the Create X.509 From CSR window.
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:
Right-click the certificate and select **Export** > **Certificate(s)**.
In the **Export** **Certificate** window for each, change the encoding to **PEM**, then specify a save location for the file.
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:
Go to **Administration** > **Configuration** > **Network** **Options** and select the **TLS/SSL Settings** tab.
Select the **Connection** drop-down option and select the **KMIP** connection pair.
Select **\[ Edit ]** next to **Certificates** in the **User** **Certificate** section.
In the **Certificate** **Authority** window, right-click the **KMIP SSL CA** X.509 certificate container and select **\[ Import ]**.
Select **\[ Add ]** at the bottom of the **Import** **Certificates** window.
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.
Select **\[ OK ]** to save.
It now shows Signed loaded next to Certificates in the User Certificates section for the KMIP connection pair.
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.
Go to **Identity** **Management** > **Identity** **Providers**.
Right-click anywhere in the window and select **Add** > **Provider** > **PKI**.
On the **Info** tab of the **Identity Provider Editor** window, specify a name for the identity provider and uncheck the **Enforce** **Dual** **Factor** checkbox.
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 ]**.
Select **\[ OK ]** to finish creating the **PKI** **Identity** **Provider**.
Right-click the identity provider you just created and select **Add** > **Mechanism** > **TLS**.
On the **Info** tab, specify a name for the authentication mechanism.
On the **PKI** tab, leave all fields set to the default values.
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:
Log in to the KMES Series 3 application interface with the default Admin identities.
Go to **Identity** **Management** > **Roles** and select **\[ Add ]**.
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`.
On the **Permissions** tab, enable the following permissions:
Permissions
Subpermissions
CryptographicOperations
Sign, Verify, Encrypt, Decrypt
Keys
Add, Export, Delete, Modify
Secure Key Functions
Clear Export
On the **Advanced** tab, set the **Allowed** **Ports** to **KMIP** only.
Select **\[ OK ]** to finish creating the role.
#### Create an identity
Perform the following steps to create an identity:
Go to **Identity** **Management** > **Identities**, right-click anywhere in the window, and select **Add** > **Client** **Application**.
On the **Info** tab of the **Identity** **Editor** window, select **Application** for the storage location and specify a **name** for the identity.
Under **Assigned** **Roles**, select the role you created for MongoDB.
Under **Authentication**, remove the default API Key mechanism and select **\[ Add ]** to add a new credential.
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:
Go to **Identity** **Management** > **Identity** **Providers**.
Right-click the PKI identity provider created for this integration and select **\[ Permission ]**.
Check the **Show all roles and permissions** box located at the bottom of the **Set Object-Group Permissions** window.
Set the **Use** permission for the **MongoDB** role and select \*\*\[ OK ]\*\*\*to save.
Go to **PKI** > **Certificate** **Authorities**.
Right-click the certificate container created for this integration and select **\[ Permission ]**.
Check the **Show all roles and permissions** box located at the bottom of the **Set Object-Group Permissions** window.
Set the **Use** permission for the **MongoDB** role and select **\[ OK ]** to save.