Skip to content

Commit

Permalink
PSMDB-1441 Documented the key loss prevention (#924)
Browse files Browse the repository at this point in the history
PSMDB-1441 Documented the key loss prevention

	modified:   docs/vault.md
  • Loading branch information
nastena1606 authored Sep 26, 2024
1 parent 095b751 commit 4841632
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 5 deletions.
1 change: 0 additions & 1 deletion .cache/plugin/git-committers/page-authors.json

This file was deleted.

47 changes: 43 additions & 4 deletions docs/vault.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,18 @@ with versioning enabled.

HashiCorp Vault Documentation: [How to configure the KV Engine](https://www.vaultproject.io/api/secret/kv/kv-v2.html)

## HashiCorp Vault Parameters
??? admonition "Version changes"

The following table lists the changes in the implementation of HashiCorp Vault integration with Percona Server for MongoDB and the versions that introduced those changes:

| Version | Description |
|-----------------|-------------|
| [5.0.15-13](release_notes/5.0.15-13.md) | Key rotation in replica sets |
| [5.0.29-25](release_notes/5.0.29-25.md) | Master key loss prevention |



## HashiCorp Vault parameters

| Command line | Configuration file | Type | Description |
| -------------------- | ------------------------- | ------ | ------------ |
Expand All @@ -22,8 +33,10 @@ with versioning enabled.
| vaultRotateMasterKey | security.vault.<br>rotateMasterKey| switch | When enabled, rotates the master key and exits |
| vaultServerCAFile | security.vault.<br>serverCAFile | string | The path to the TLS certificate file |
| vaultDisableTLSForTesting | security.vault.<br>disableTLSForTesting | switch | Disables secure connection to Vault using SSL/TLS client certificates|
| vaultCheckMaxVersions | security.vault.<br>checkMaxVersions| boolean | Verifies that the current number of secret versions has not reached the maximum, defined by the `max_versions` parameter for the secret or the secrets engine on the Vault server. If the number of versions has reached the maximum, the server logs an error and exits. Enabled by default. Available starting with version 5.0.29-25.|


**Config file example**
### Config file example

```yaml
security:
Expand All @@ -35,6 +48,23 @@ security:
secret: secret/data/hello
```
Starting with 5.0.29-25, Percona Server for MongoDB checks the number of the secrets on the Vault server before adding a new one thus [preventing the loss of the old master key](#master-key-loss-prevention). For these checks, Percona Server for MongoDB requires read permissions for the secret’s metadata and the secrets engine configuration. You configure these permissions within the access policy on the Vault server.
Find the sample policy configuration below:
```json
path "secret/data/*" {
capabilities = ["create","read","update","delete"]
}
path "secret/metadata/*" {
capabilities = ["read"]
}
path "secret/config" {
capabilities = ["read"]
}
```


During the first run of the Percona Server for MongoDB, the process generates a secure key and writes the key to the vault.

During the subsequent start, the server tries to read the master key from the vault. If the configured secret does not exist, vault responds with HTTP 404 error.
Expand All @@ -60,7 +90,7 @@ You have the following options of how to target a particular namespace when conf
```{.bash data-prompt="$"}
$ export VAULT_NAMESPACE=test
```
2. Provide the namespace with the `-namespace` flag in commands
2. Provide the namespace with the `--namespace` flag in commands

!!! admonition "See also"

Expand Down Expand Up @@ -98,4 +128,13 @@ The key rotation steps are the following:

1. Rotate the master key for the secondary nodes one by one.
2. Step down the primary and wait for another primary to be elected.
3. Rotate the master key for the previous primary node.
3. Rotate the master key for the previous primary node.

### Master key loss prevention

Starting with version 5.0.29-25, Percona Server for MongoDB checks if the number of secret versions has reached the maximum (10 by default) before adding a new master key to the Vault server as a versioned secret. You configure this number using the `max_versions` parameter on the Vault server.

If the number of secrets reaches the maximum, Percona Server for MongoDB logs an error and exits. This prevents the Vault server from dropping the oldest secret version and the encryption key it stores.

To continue, increase the maximum versions for the secret or the entire secrets engine on the Vault server, then restart Percona Server for MongoDB. To check the number of secrets on the Vault server, ensure Percona Server for MongoDB has [read permissions for the secret’s metadata and the secrets engine configuration](#config-file-example).

0 comments on commit 4841632

Please sign in to comment.