Because the encryption-settings database contains the encryption keys used to protect server data, the contents of the encryption-settings database is itself encrypted. By default, the server will derive a key to use for this purpose, but it is recommended that you customize the logic used to access the encryption-settings database with a cipher stream provider. The Server SDK provides an API that can be used to create custom cipher stream provider implementations, but the server also comes with one that will obtain the key from a PIN file that you create (see the example procedure below).

  1. Use dsconfig to configure the server so that the encryption-settings database is encrypted with a PIN contained in the file config/encryption-settings.pin.
    $ 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. Use dsconfig to set the global configuration property for the cipher stream provider, which sets the on-disk encryption.
    $ bin/dsconfig set-global-configuration-prop \ 
      --set "encryption-settings-cipher-stream-provider:Encryption Settings PIN File"
  3. Use the encryption-settings tool to create a new encryption-settings definition. This command automatically generates a new 256-bit encryption key for use with AES encryption, and mark it as the preferred definition for future encryption operations in the server. Note that this command will fail if you do not have the unlimited encryption strength policy installed as described in the previous section (if you do not have that policy installed, then you are restricted to a 128-bit key for AES encryption).
    $ bin/encryption-settings create \                      
      --cipher-algorithm AES \
      --key-length-bits 256 \                      
      --set-preferred 
  4. Obtain a list of the definitions in the encryption-settings database.
    $ bin/encryption-settings list 
  5. You can export an encryption-settings definition from the database using a command like the following where the encryption-settings ID should be changed as necessary to suit your deployment:
    $ bin/encryption-settings export \                      
      --id DA39A3EE5E6B4B0D3255BFEF95601890AFD80709 \                      
      --output-file /tmp/exported-key \ 
      --pin-file /tmp/exported-key.pin 
  6. If no PIN file is specified, then you will be interactively prompted to provide it. To import an encryption-settings definition into the database on another server.
    $ bin/encryption-settings import \                      
      --input-file /tmp/exported-key \
      --pin-file /tmp/exported-key.pin \                      
      --set-preferred