Encryption
Data is encrypted at three levels:
- Inside Vault all data is stored encrypted at field level, preventing even the database's administrator from decrypting the data.
- Data in transit between an application and Vault is protected using TLS.
- The Vault database is encrypted at rest (aka disk-level encryption). This is enforced as part of the deployment.
From the application's perspective, accessing and querying encrypted properties and handling encryption is fully transparent.
Vault manages key provisioning and rotation for the encryption keys.
Key management service
Vault relies on a master key to generate encryption keys for property encryption, decryption, data signing, and verification. To ensure secure property encryption when implementing Vault in a cloud environment, it is highly recommended that you use the Amazon Web Services (AWS), Google Cloud Platform (GCP) KMS, or Azure Key Vault. However, if you prefer to manage the keys independently or do not want to rely on a cloud provider, you can provide a seed for generating a secure master key.
AWS KMS and GCP Cloud Key Management use a Hardware Security Module (HSM) to increase the security of your key and to comply with PCI HSM requirements. Azure Key Vault uses HSM if you select the premium tier.
All instances of a Vault system should use the same KMS configuration, as they all work on the same database and rely on the keys being identical. When using multiple Vaults, use separate KMS and avoid sharing KMS keys between systems.
To configure a cloud provider KMS, set the PVAULT_KMS_URI
environment variable to the KMS key URI using these patterns:
KMS | KMS identifier prefix | Key URI format |
---|---|---|
AWS KMS | aws-kms:// | aws-kms://arn:aws:kms:<region>:<account-id>:key/<key-id> |
GCP KMS | gcp-kms:// | gcp-kms://projects/*/locations/*/keyRings/*/cryptoKeys/* |
Azure Key Vault | az-kms:// | az-kms://<vault-base-url>/keys/<key-name>/<key-version> |
Vault must have these permissions to be able to use the KMS:
- Sign keys with the KMS
- Verify keys with the KMS
- Get the KMS public key
These high-level permissions have equivalent policies in AWS and GCP that need to be granted to the AWS or GCP authenticated identity where Vault is running.
AWS
For Vault to use AWS KMS, the following IAM policy is required (change the Resource
field to the ARN of your CMK or alias):
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"kms:Encrypt",
"kms:Decrypt"
],
"Effect": "Allow",
"Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
]
}
It is recommended that you follow the principle of least privilege and limit access to kms:Encrypt
and kms:Decrypt
actions on the CMK to only the Vault instances to keep the encrypted data secure. This policy should not be granted to any other principals.
GCP
For Vault to use GCP KMS, grant the roles/cloudkms.cryptoKeyEncrypterDecrypter
role to the service account running Vault.
It is recommended that you follow the principle of least privilege and limit access to this role only to the Vault instances to keep the encrypted data secure. This role should not be granted to any other principals.
The Vault roadmap includes support for controlling rotation parameters, complex queries over encrypted data, bring your own key (BYOK) for multi-tenant applications, and more.
Azure
For Vault to use Azure Key Vault, grant the Microsoft.KeyVault/vaults/keys/wrap/action
and Microsoft.KeyVault/vaults/keys/unwrap/action
Data Actions to your managed identity. For ease of use, you can assign the Key Vault Crypto Service Encryption User role to your managed identity.
Local (Seed)
To use a local KMS, leave the environment variable PVAULT_KMS_URI
empty, and set the PVAULT_KMS_SEED
to a random string. This seed is used to generate a master key for encryption purposes. The seed is not stored anywhere and is only used to generate the keys. Starting Vault with the same seed generates the same keys, so using a strong seed and treating it as a secret is important. You should use at least a 256-bit, high-entropy random string.
When the environment variable PVAULT_DEVMODE
is false
(default), Vault does not start without a KMS URI. This is to prevent someone from starting Vault accidentally in production without a KMS. To start Vault in a production-ready state without the use of a cloud-based KMS, set PVAULT_KMS_ALLOW_LOCAL
to true
.
When Vault is started without an external KMS or seed, it uses a built-in hard-coded master encryption key. This is convenient for development and testing purposes but is insecure and must not be used in a production environment that requires property encryption.