Navigation
This version of the documentation is archived and no longer supported. It will be removed on EOL_DATE. To learn how to upgrade your version of MongoDB Ops Manager, refer to the upgrade documentation.
You were redirected from a different version of the documentation. Click here to go back.
This version of the manual is no longer supported. It will be removed on EOL_DATE.

Backup Encryption Keys

Note

Groups and projects are synonymous terms. Your {GROUP-ID} is the same as your project id. For existing groups, your group/project id remains the same. This page uses the more familiar term group when referring to descriptions. The endpoint remains as stated in the document.

MongoDB 3.4 Enterprise enables administrators to encrypt backups. Administrators must integrate with a KMIP server to generate and manage a master key used to encrypt the head databases during a backup operation. MongoDB recommends periodically rotating the KMIP master key for increased security.

Base URL: https://{OPSMANAGER-HOST}:{PORT}/api/public/v1.0

Endpoints

Rotate the KMIP Master Key

Use the PUT HTTP method with the following endpoint to rotate the KMIP master key. Issue one PUT request for each shard and another PUT request for the config server replica set.

PUT /groups/GROUP-ID/backupConfigs/CLUSTER-ID/encryptionKey

Retrieve the KMIP Master Key ID

Use the GET HTTP method with the same endpoint to retrieve the ID of the current KMIP master key.

GET /groups/GROUP-ID/backupConfigs/CLUSTER-ID/encryptionKey

Sample Entity

{
  "clusterId": "yyy",
  "groupId": "xxx",
  "encryptionKeyUUID: "1234-3456-4567-abcd-def0",
}

Entity Fields

Name Type Description
groupId string Unique identifier of the group that the encryption key belong to.
clusterId string Unique identifier of the cluster that tthe encryption keys belong to.
encryptionKeyUUID string The Unique identifier of the KMIP master key. This key is used to encrypt and restore the head databases for an encrypted backup.

Examples

Rotate the KMIP Master Key

Request

curl --user '{USERNAME}:{APIKEY}' --digest \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --include \
 --request PUT "https://<ops-manager-host>/api/public/v1.0/groups/5196d3628d022db4cbc26d9e/backupConfigs/5196e5b0e4b0fca9cc88334a/encryptionKey"

Response

HTTP/1.1 201 Accepted

The new KMIP master key ID is not displayed in the response. Retrieve the new key with a GET request to the same endpoint, as shown in the next example.

Retrieve the KMIP Master Key ID

Request

curl --user '{USERNAME}:{APIKEY}' --digest \
 --header 'Accept: application/json' \
 --include \
 --request GET "https://<ops-manager-host>/api/public/v1.0/groups/5196d3628d022db4cbc26d9e/backupConfigs/5196e5b0e4b0fca9cc88334a/encryptionKey"

Response

Response Header

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=ISO-8859-1
Date: {dateInUnixFormat}
WWW-Authenticate: Digest realm="MMS Public API", domain="", nonce="{nonce}", algorithm=MD5, op="auth", stale=false
Content-Length: {requestLengthInBytes}
Connection: keep-alive
HTTP/1.1 200 OK
Vary: Accept-Encoding
Content-Type: application/json
Strict-Transport-Security: max-age=300
Date: {dateInUnixFormat}
Connection: keep-alive
Content-Length: {requestLengthInBytes}

Response Body

{
  "clusterId" : "5196e5b0e4b0fca9cc88334a",
  "groupId" : "5196d3628d022db4cbc26d9e",
  "encryptionKeyUUID": "1234-3456-4567-abcd-def0"
}
←   Checkpoints Restore Jobs  →