Creating encryption settings definitions

To create a new encryption settings definition, use the encryption-settings create command, which takes the following arguments.

Argument Description

Argument	Description
`--cipher-algorithm`	A required argument that specifies the base cipher that should be used for encryption and decryption. The value for this argument must be the name of a valid symmetric encryption algorithm that is supported by the Java Virtual Machine (JVM). We recommend using AES.
`--cipher-transformation`	An optional argument that allows you to specify the complete cipher transformation for encryption performed using this definition. If provided, the cipher transformation should consist of three components separated by forward slashes: the cipher algorithm, the cipher mode, and the padding algorithm, such as “AES/CBC/PKCS5Padding”. If this is not provided, the server automatically selects the transformation based on the specified cipher algorithm.
`--key-factory-iteration-count <count>`	Specifies the PBKDF2iteration count to use in deriving the encryption key for the encryption settings definition. You should use this argument when creating a new encryption settings definition. The current OWASP recommendation is to use a PBKDF2 iteration count value of at least 600,000.
`--key-length-bits`	The length, in bits, to use for the encryption key. When using the AES cipher, this should generally be either 128 or 256.
`--prompt-for-passphrase`	An optional argument that indicates that the tool should interactively prompt for the passphrase to use when generating the encryption key.
`--passphrase-file-path`	An optional argument that provides the path to a file containing the passphrase that should be used when generating the encryption key.
`--description`	An optional argument that can be used to provide a human-readable description for the new encryption settings definition.
`--set-preferred`	An optional argument that indicates that the new definition should be the preferred definition used for subsequent encryption operations.

--cipher-algorithm

A required argument that specifies the base cipher that should be used for encryption and decryption. The value for this argument must be the name of a valid symmetric encryption algorithm that is supported by the Java Virtual Machine (JVM). We recommend using AES.

--cipher-transformation

An optional argument that allows you to specify the complete cipher transformation for encryption performed using this definition. If provided, the cipher transformation should consist of three components separated by forward slashes: the cipher algorithm, the cipher mode, and the padding algorithm, such as “AES/CBC/PKCS5Padding”. If this is not provided, the server automatically selects the transformation based on the specified cipher algorithm.

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

Specifies the PBKDF2iteration count to use in deriving the encryption key for the encryption settings definition. You should use this argument when creating a new encryption settings definition. The current OWASP recommendation is to use a PBKDF2 iteration count value of at least 600,000.

--key-length-bits

The length, in bits, to use for the encryption key. When using the AES cipher, this should generally be either 128 or 256.

--prompt-for-passphrase

An optional argument that indicates that the tool should interactively prompt for the passphrase to use when generating the encryption key.

--passphrase-file-path

An optional argument that provides the path to a file containing the passphrase that should be used when generating the encryption key.

--description

An optional argument that can be used to provide a human-readable description for the new encryption settings definition.

--set-preferred

An optional argument that indicates that the new definition should be the preferred definition used for subsequent encryption operations.

The following is an example of the command with some of the arguments included.

$ bin/encryption-settings create \
     --cipher-algorithm AES \
     --cipher-transformation AES/GCM/PKCS5Padding \
     --key-factory-iteration-count 60000 \
     --key-length-bits 256 \
     --prompt-for-passphrase \
     --description "An example encryption settings definition"
Enter the encryption passphrase:
Confirm the encryption passphrase:

Successfully created a new encryption settings definition with ID
494DCE52DE58D0A44E56B9E80FC62B257870F2FC7CEEDCA150F4EF51829D7B20.

Each encryption settings definition has an underlying passphrase that is used to generate the encryption key. If you provide the --prompt-for-passphrase argument, then the tool interactively prompts you for that passphrase. If you provide the --passphrase-file-path argument, then it reads the passphrase from a file. If you do not provide either argument, then the tool generates a strong random passphrase for use by that definition.

We generally recommend that you explicitly specify the passphrase for new encryption settings definitions rather than allowing the tool to generate a random passphrase. If you want to create the encryption settings definition across multiple instances, then providing the same passphrase for each instance ensures that the same definition is created everywhere. Further, if you need to decrypt a file that was encrypted with a key from the encryption settings database, like a backup, LDIF export, or log file, then you can decrypt the file (using the encrypt-file tool or using the PassphraseEncryptedInputStream class provided in the UnboundID LDAP SDK for Java) if you know the passphrase, even if you’re on a system that doesn’t have access to the server’s encryption settings database.

PingDirectory

Creating encryption settings definitions