PingDirectory

Creating encryption settings definitions

The encryption-settings tool with the create subcommand provides a mechanism for creating a new encryption settings definition.

Steps

  • To create an encryption settings definition, use the encryption-settings tool with the create subcommand.

    This subcommand takes the following arguments.

    Argument Description

    --cipher-algorithm <algorithm> (required)

    Specifies the base cipher algorithm to use. Make sure the <algorithm> input is the name of the algorithm, such as AES.

    --cipher-transformation <transformation> (optional)

    Specifies the full cipher transformation to use including the cipher mode and padding algorithms, such as AES, CBC, and PKCS5Padding.

    If you do not provide this argument, a default transformation is used for the specified cipher algorithm.

    --key-length-bits <length> (required)

    Specifies the length of the encryption key in bits, such as 128.

    --set-preferred

    Indicates that the new encryption-settings definition is made the preferred definition and used for subsequent encryption operations in the server.

    By default, the first definition you create in the encryption settings database is the preferred definition.

    --key-factory-iteration-count <count>

    Specifies the PBKDF2 iteration count to be used when deriving the encryption key for the resulting definition.

    --prompt-for-passphrase

    Indicates that the tool should prompt the user for a passphrase to use in generating the encryption settings definition.

    --passphrase-file <path>

    Specifies the file path containing the passphrase to be used in generating the encryption settings definition.

    --description <description>

    Provides a readable string describing the purpose of the encryption settings definition.

    Each encryption settings definition is backed by a passphrase that generates an associated encryption key. You can specify the passphrase when creating the definition by typing it into an interactive prompt or providing it in a file. If you do not specify a passphrase, then the encryption-settings tool will generate a strong random passphrase.

    The created encryption settings definition has an identifier that the server uses to indicate the definition used in encrypting a given block of data. That way, the correct definition can be used to decrypt that data. This identifier is generated from several elements, including:

    • The passphrase backing the definition

    • The iteration count used to derive the encryption key from the passphrase

    • The derived key length

    • The cipher algorithm and cipher transformation used to perform the encryption

      If you create an encryption settings definition with the same passphrase, iteration count, key length, cipher algorithm, and cipher transformation across multiple servers, then each of the servers will have an identical encryption settings definition. To create a definition without specifying a passphrase, use the encryption-settings export command to export that definition from its native server instance. Then, use the encryption-settings import command to import the definition into other instances of the topology.

      Although the --key-factory-iteration-count argument is optional, you should provide this argument whenever generating a new encryption settings definition because the default iteration count is lower than the minimum count of 600,000 recommended by OWASP.

      Example:

      $ bin/encryption-settings create --cipher-algorithm AES \
--cipher-transformation AES/GCM/NoPadding \
--key-factory-iteration-count 600000 \
--key-length-bits 256 \
--set-preferred \
--description "Example encryption settings definition with a randomly generated key"

      Result:

      Successfully created a new encryption settings definition with ID
F635E109A8549651025D01D9A6A90F7C9017C66D