PingDirectory

Configuring the encryption-settings database

Configure the encryption-settings database to protect server data.

About this task

The encryption-settings database contains encryption keys to protect server data, which automatically encrypts the contents of the encryption-settings database. By default, the server derives a key to use for this purpose. Because of this, customize the logic used to access the encryption-settings database with a cipher stream provider. To create custom cipher stream provider implementations, the Server SDK provides an API. The server contains an API you can use to obtain the key from a PIN file that you create. See the following example procedure.

Steps

  1. To configure the server so that the encryption-settings database is encrypted with a PIN contained in the file config/encryption-settings.pin, use the dsconfig tool.

    Example:

    $ bin/dsconfig create-cipher-stream-provider \
  --provider-name "Encryption Settings PIN File" \
  --type file-based \
  --set enabled:true \
  --set password-file:config/encryption-settings.pin

  2. To set the global configuration property and the on-disk encryption for the cipher stream provider, use the dsconfigtool.

    Example:

    $ bin/dsconfig set-global-configuration-prop \
  --set "encryption-settings-cipher-stream-provider:Encryption Settings PIN File"

  3. To create a new encryption-settings definition, use the encryption-settings tool.

    This command fails if you do not have the unlimited encryption strength policy installed as described in the previous section. Without this policy installed, you are restricted to a 128-bit key for AES encryption.

    Example:

    $ bin/encryption-settings create \
  --cipher-algorithm AES \
  --key-length-bits 256 \
  --set-preferred

    Result:

    This command automatically generates a new 256-bit encryption key for use with AES encryption and marks it as the preferred definition for future encryption operations in the server.

  4. To obtain a list of the definitions in the encryption-settings database, use the encryption-settings tool with the list subcommand.

    Example:

    $ bin/encryption-settings list

  5. Export an encryption-settings definition from the database using the encryption-settings tool with the export subcommand.

    Change the encryption-settings ID as necessary to suit your deployment.

    Example:

    $ bin/encryption-settings export \
  --id DA39A3EE5E6B4B0D3255BFEF95601890AFD80709 \
  --output-file /tmp/exported-key \
  --pin-file /tmp/exported-key.pin

  6. To import an encryption-settings definition into the database on another server, use the encryption-settings tool with the import subcommand.

    If you do not specify a PIN file, the tool interactively prompts you to provide it.

    Example:

    $ bin/encryption-settings import \
  --input-file /tmp/exported-key \
  --pin-file /tmp/exported-key.pin \
  --set-preferred