PingDirectory

Configuring cipher stream providers

Cipher stream providers are used to protect the keys stored in the encryption settings database.

By default, setup generates a strong, random passphrase and writes it to a file. The server then uses a file-based cipher stream provider to read the passphrase and generate a key for encrypting the contents of the encryption settings database. However, the server supports additional cipher stream providers that use alternative means for unlocking the encryption settings database. Options include:

  • Require a passphrase to be interactively provided when the server is started, or any time an external process needs access to the encryption settings database.

  • Use a key stored in the Amazon Key Management Service (KMS).

  • Use a key stored in a HashiCorp Vault instance.

  • Use a key generated from a passphrase stored in the Amazon Secrets Manager service.

  • Use a key generated from a passphrase stored in the Azure Key Vault service.

  • Use a key generated from a passphrase stored in a CyberArk Conjur instance.

  • Use a key generated from a certificate stored in a PKCS #11 token.

It is also possible to use the Server SDK to create cipher stream providers that use custom logic to protect the contents of the encryption settings database.

If you want to configure the server to use a different cipher stream provider, first ensure that the desired cipher stream provider is defined and enabled in the configuration and then update the global configuration to use that cipher stream provider to protect the encryption settings database. You should do this with the server online so that it can automatically re-encrypt the encryption settings database with the new key.

For example, to configure the server to use the Amazon KMS cipher stream provider, first create an Amazon AWS external server configuration definition that provides information needed to interact with the AWS service, including which region to use, the type of authentication to use, and whether to access AWS through an HTTP proxy server:

$ bin/dsconfig create-external-server \
  --server-name AWS \
  --type amazon-aws \
  --set authentication-method:access-key \
  --set aws-access-key-id:[KMS_ACCESS_KEY_ID] \
  --set aws-secret-access-key:[KMS_SECRET_ACCESS_KEY] \
  --set region-name:us-east-1

Then, create a cipher stream provider with the configured external server and specify which key to use to protect the encryption settings database:

dsconfig create-cipher-stream-provider \
     --provider-name "Amazon KMS" \
     --type amazon-key-management-service \
     --set enabled:true \
     --set "aws-access-key-id:[KMS_ACCESS_KEY_ID]" \
     --set "aws-secret-access-key:[KMS_SECRET_ACCESS_KEY]" \
     --set "kms-encryption-key-arn:[KMS_KEY_ARN]"

Finally, update the global configuration to use the new cipher stream provider. This should be done with the server online to ensure that the existing encryption settings database is re-encrypted with the cipher stream provider:

dsconfig set-global-configuration-prop \
     --set "encryption-settings-cipher-stream-provider:Amazon KMS"

See the use-the-amazon-kms-cipher-stream-provider.dsconfig and use-the-vault-cipher-stream-provider.dsconfig batch files in the config/sample-dsconfig-batch-files directory for more information about the KMS and Vault cipher stream providers.