Skip to content
logo
Percona Server for MongoDB 5.0
Using the Key Management Interoperability Protocol (KMIP)
Initializing search
    percona/psmdb-docs
    percona/psmdb-docs
    • Home
    • Percona Server for MongoDB feature comparison
      • Overview
      • Installing Percona Server for MongoDB on Debian and Ubuntu
      • Installing Percona Server for MongoDB on Red Hat Enterprise Linux and CentOS
      • Installing Percona Server for MongoDB from binary tarball
      • Running Percona Server for MongoDB in a Docker Container
        • Percona Memory Engine
        • Hot Backup
        • $backupCursor and $backupCursorExtend aggregation stages
        • Authentication overview
        • Enable SCRAM authentication
        • Set up LDAP authentication with SASL
        • Set up x.509 authentication and LDAP authorization
        • Set up Kerberos authentication
        • AWS IAM authentication
        • Setting up AWS IAM authentication
        • LDAP authorization
        • Set up LDAP authentication and authorization using NativeLDAP
        • Data at rest encryption
        • HashiCorp Vault integration
        • Using the Key Management Interoperability Protocol (KMIP)
          • KMIP parameters
        • Local key management using a keyfile
        • Migrating from key file encryption to HashiCorp Vault encryption
      • Auditing
      • Profiling Rate Limit
      • Log Redaction
      • Additional text search algorithm - ngram
      • Tune parameters
        • Upgrade from 4.4 to 5.0
        • Upgrading Percona Server for MongoDB
      • Uninstall Percona Server for MongoDB
      • Percona Server for MongoDB 5.0 Release Notes
      • Percona Server for MongoDB 5.0.15-13 (2023-03-16)
      • Percona Server for MongoDB 5.0.14-12 (2022-12-08)
      • Percona Server for MongoDB 5.0.13-11 (2022-10-12)
      • Percona Server for MongoDB 5.0.11-10 (2022-09-01)
      • Percona Server for MongoDB 5.0.10-9 (2022-08-09)
      • Percona Server for MongoDB 5.0.9-8 (2022-06-20)
      • Percona Server for MongoDB 5.0.8-7 (2022-05-10)
      • Percona Server for MongoDB 5.0.7-6 (2022-04-20)
      • Percona Server for MongoDB 5.0.6-5 (2022-02-10)
      • Percona Server for MongoDB 5.0.5-4 (2021-12-28)
      • Percona Server for MongoDB 5.0.4-3 (Release Candidate) (2021-12-08)
      • Percona Server for MongoDB 5.0.3-2 (Release Candidate) (2021-10-14)
      • Percona Server for MongoDB 5.0.2-1 (Release Candidate) (2021-08-16)
    • Glossary
    • Copyright and licensing information
    • Trademark policy

    • KMIP parameters

    Using the Key Management Interoperability Protocol (KMIP)¶

    Version added: 5.0.7-6

    Percona Server for MongoDB adds support for secure transfer of keys using the OASIS Key Management Interoperability Protocol (KMIP). The KMIP implementation was tested with the PyKMIP server and the HashiCorp Vault Enterprise KMIP Secrets Engine.

    KMIP enables the communication between key management systems and the database server. KMIP provides the following benefits:

    • Streamlines encryption key management
    • Eliminates redundant key management processes

    Starting with version 5.0.9-8, you can specify multiple KMIP servers for failover. On startup, Percona Server for MongoDB connects to the servers in the order listed and selects the one with which the connection is successful.

    Starting with version 5.0.11-10, the kmipKeyIdentifier option is no longer mandatory. When left blank, the database server creates a key on the KMIP server and uses that for encryption. When you specify the identifier, the key with such an ID must exist on the key storage.

    KMIP parameters¶

    Option Type Description
    --kmipServerName string The hostname or IP address of the KMIP server. As of version 4.2.21-21, multiple KMIP servers are supported as the comma-separated list, e.g. kmip1.example.com,kmip2.example.com
    --kmipPort number The port used to communicate with the KMIP server. When undefined, the default port 5696 will be used
    --kmipServerCAFile string The path to the CA certificate file. CA file is used to validate secure client connection to the KMIP server
    --kmipClientCertificateFile string The path to the PEM file with the KMIP client private key and the certificate chain. The database server uses this PEM file to authenticate the KMIP server
    --kmipKeyIdentifier string Optional starting with version 5.0.11-10. The identifier of the KMIP key. If the key does not exist, the database server creates a key on the KMIP server with the specified identifier. When you specify the identifier, the key with such an ID must exist on the key storage. You can only use this setting for the first time you enable encryption.
    --kmipRotateMasterKey boolean Controls master keys rotation. When enabled, generates the new master key version and re-encrypts the keystore. Available as of version 5.0.8-7. Requires the unique --kmipKeyIdentifier for every mongod node.
    --kmipClientCertificatePassword string The password for the KMIP client private key or certificate. Use this parameter only if the KMIP client private key or certificate is encrypted. Available starting with version 5.0.9-8.

    Key rotation¶

    Starting with release 5.0.8-7, the support for master key rotation is added. This enables users to comply with data security regulations when using KMIP.

    Configuration¶

    Considerations¶

    Make sure you have obtained the root certificate, and the keypair for the KMIP server and the mongod client. For testing purposes you can use the OpenSSL to issue self-signed certificates. For production use we recommend you use the valid certificates issued by the key management appliance.

    To enable data-at-rest encryption in Percona Server for MongoDB using KMIP, edit the /etc/mongod.conf configuration file as follows:

    security:
      enableEncryption: true
      kmip:
        serverName: <kmip_server_name>
        port: <kmip_port>
        clientCertificateFile: </path/client_certificate.pem>
        clientKeyFile: </path/client_key.pem>
        serverCAFile: </path/ca.pem>
        keyIdentifier: <key_name>
    

    Alternatively, you can start Percona Server for MongoDB using the command line as follows:

    $ mongod --enableEncryption \
      --kmipServerName <kmip_servername> \
      --kmipPort <kmip_port> \
      --kmipServerCAFile <path_to_ca_file> \
      --kmipClientCertificateFile <path_to_client_certificate> \
      --kmipClientKeyFile <path_to_client_private_key> \
      --kmipKeyIdentifier <kmip_identifier>
    

    Minor upgrade of Percona Server for MongoDB to version 5.0.11-10 and higher¶

    With the kmipKeyIdentifier option becoming optional in version 5.0.11-10, the standard upgrade procedure doesn’t work if you are upgrading from version 5.0.10-9 and earlier.

    For Percona Server for MongoDB 5.0.13-11 and higher, follow the standard upgrade procedure

    This section provides upgrade instructions from Percona Server for MongoDB 5.0.10-9 or lower to Percona Server for MongoDB version 5.0.11-10 and higher.

    For a single-node deployment, use the mongodump / mongorestore tools to make a backup before the update and to restore from it after binaries are updated.

    For replica sets, data must be re-encrypted with the new key during the upgrade. Go through the encrypting existing data steps but perform the minor upgrade between steps 1 and 2 to replace the mongod binary.

    Contact Us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.


    Last update: December 8, 2022
    Created: December 8, 2022
    Percona LLC and/or its affiliates, © 2023
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.