Directory Server Documentation Index
Command-Line Tool Reference Home

encryption-settings

↓Description
↓Examples
↓Subcommands
↓Arguments

Description

Manage the server encryption settings database.

More information about the cipher algorithms and transformations available for use may be found in the Java Cryptography Architecture Reference Guide, as well as the Standard Algorithm Name Documentation for your chosen JDK implementation used by this server.

Examples

Interactively supply the passphrase needed to access the encryption settings database: 
encryption-settings supply-passphrase


List all of the available encryption settings definitions: 
encryption-settings list


Create a new encryption settings definition that will encrypt data using a 128-bit AES cipher with a key generated from an interactively provided password. It will be made the preferred settings definition for subsequent encryption operations: 
encryption-settings create --cipher-algorithm AES --key-length-bits 128 \
     --prompt-for-passphrase --set-preferred


Remove the encryption settings definition with the specified ID from the server: 
encryption-settings delete --id DA39A3EE5E6B4B0D3255BFEF95601890AFD80709


Export the encryption settings definition with the given ID to output file /tmp/exported-key using the passphrase in file /tmp/export-passphrase.txt to encrypt its contents: 
encryption-settings export --id DA39A3EE5E6B4B0D3255BFEF95601890AFD80709 \
     --output-file /tmp/exported-key \
     --passphrase-file /tmp/export-passphrase.txt


Export all encryption settings definitions to output file /tmp/exported-key using the passphrase in file /tmp/exported-passphrase.txt to encrypt their contents: 
encryption-settings export --output-file /tmp/exported-key \
     --passphrase-file /tmp/export-passphrase.txt


Import the encryption settings data from file /tmp/exported-key using the passphrase from file /tmp/export-passphrase.txt to decrypt its contents. It will be used to set the preferred definition for subsequent encryption operations: 
encryption-settings import --input-file /tmp/exported-key \
     --passphrase-file /tmp/export-passphrase.txt --set-preferred


Sets the encryption settings definition with the specified ID to be preferred for subsequent encryption performed by the server: 
encryption-settings set-preferred --id DA39A3EE5E6B4B0D3255BFEF95601890AFD80709


Display a list of the data encryption restrictions that are currently in effect (as well as a list of those that are not in effect) for the server: 
encryption-settings get-data-encryption-restrictions


Add a specified set of data encryption restrictions for the server: 
encryption-settings set-data-encryption-restrictions \
     --add-restriction prevent-disabling-data-encryption \
     --add-restriction prevent-changing-cipher-stream-provider


Remove a data encryption restriction from the server: 
encryption-settings set-data-encryption-restrictions \
     --remove-restriction prevent-changing-cipher-stream-provider


Adds all defined data encryption restrictions for the server: 
encryption-settings set-data-encryption-restrictions --add-all-restrictions


Indicate whether the encryption settings database is currently frozen: 
encryption-settings is-frozen


Freeze the encryption settings database with a passphrase that is provided at an interactive prompt: 
encryption-settings freeze


Freeze the encryption settings database with a passphrase that is read from the specified file: 
encryption-settings freeze --passphrase-file /tmp/freeze-passphrase.txt


Unfreeze the encryption settings database with a passphrase that is provided at an interactive prompt: 
encryption-settings unfreeze


Unfreeze the encryption settings database with a passphrase that is read from the specified file: 
encryption-settings unfreeze --passphrase-file /tmp/freeze-passphrase.txt

Subcommands

↓create
↓delete
↓export
↓freeze
↓get-data-encryption-restrictions
↓import
↓is-frozen
↓list
↓set-data-encryption-restrictions
↓set-preferred
↓supply-passphrase
↓unfreeze

create

Create a new encryption settings definition for use by the server. A new random key will be generated based on the provided settings


create Examples

Create a new encryption settings definition that will encrypt data using a 128-bit AES cipher with a key generated from an interactively provided password. It will be made the preferred settings definition for subsequent encryption operations: 
encryption-settings create --cipher-algorithm AES --key-length-bits 128 \
     --prompt-for-passphrase --set-preferred


Create a new encryption settings definition that will encrypt data using a 128-bit AES cipher with the CBC cipher mode and PKCS #5 padding. It will use an encryption key generated from a password read from a file, and it will include a description: 
encryption-settings create --cipher-algorithm AES \
     --cipher-transformation AES/CBC/PKCS5Padding --key-length-bits 128 \
     --passphrase-file passphrase-file.txt \
     --description "An encryption settings definition created from a known passphrase" \
     --set-preferred

create Arguments

-a {algorithm}
--cipher-algorithm {algorithm}

Description The cipher algorithm to use for encryption and decryption. This must be provided
Required Yes
Multi-Valued No

-t {transformation}
--cipher-transformation {transformation}

Description The full cipher transformation that will be used for encryption and decryption. If this is not provided, then a default transformation will be used based on the specified cipher algorithm
Required No
Multi-Valued No

-l {bits}
--key-length-bits {bits}

Description The length in bits of the encryption key that should be used for the encryption settings definition
Lower Bound 1
Required Yes
Multi-Valued No

--key-factory-iteration-count {count}

Description The number of PBKDF2 iterations to use when deriving the encryption key from the encryption settings definition. If this is not specified, a default iteration count will be used (which may be relatively low for the purpose of legacy backward compatibility)
Lower Bound 1
Upper Bound 2147483647
Required No
Multi-Valued No

--prompt-for-passphrase

Description Interactively prompt for a passphrase that will be used to generate the encryption key. If neither the --prompt-for-passphrase nor the --passphrase-file argument is provided, then the key will be generated from a random passphrase

--passphrase-file {path}

Description The path to a file containing a passphrase that will be used to generate the encryption key. If neither the --prompt-for-passphrase nor the --passphrase-file argument is provided, then the key will be generated from a random passphrase
Required No
Multi-Valued No

--description {description}

Description A description for the encryption settings definition
Required No
Multi-Valued No

-p
--set-preferred

Description Make the new encryption settings definition preferred for subsequent encryption operations. If the new definition is the first definition, then it will automatically be set preferred

delete

Delete an encryption settings definition from the server. Note that the preferred encryption settings definition may not be deleted. To delete the preferred definition, you must first set another definition as the preferred definition, and you will then be allowed to remove the previously-preferred definition. Also note that if you delete an encryption settings definition from the server, any data encrypted with that definition will become unreadable


delete Examples

Remove the encryption settings definition with the specified ID from the server: 
encryption-settings delete --id DA39A3EE5E6B4B0D3255BFEF95601890AFD80709

delete Arguments

-i {id}
--id {id}

Description The identifier for the encryption settings definition to remove
Required Yes
Multi-Valued No

-n
--no-prompt

Description Do not prompt the user for any confirmations while running

export

Export an encryption settings definition from the server so that it can be imported into another server


export Examples

Export the encryption settings definition with the given ID to output file /tmp/exported-key using the passphrase in file /tmp/export-passphrase.txt to encrypt its contents: 
encryption-settings export --id DA39A3EE5E6B4B0D3255BFEF95601890AFD80709 \
     --output-file /tmp/exported-key \
     --passphrase-file /tmp/export-passphrase.txt


Export all encryption settings definitions to output file /tmp/exported-key using the passphrase in file /tmp/exported-passphrase.txt to encrypt their contents: 
encryption-settings export --output-file /tmp/exported-key \
     --passphrase-file /tmp/export-passphrase.txt

export Arguments

-i {id}
--id {id}

Description The identifier for the encryption settings definition to export. This may be provided multiple times to export multiple specific encryption settings definitions, or it may be omitted to indicate that all definitions should be exported
Required No
Multi-Valued Yes

-o {path}
--output-file {path}

Description The path of the output file to which the exported encryption settings should be written
Required Yes
Multi-Valued No

-W {path}
--passphrase-file {path}

Description The path of the file containing the passphrase that should be used to encrypt the exported encryption settings. If this is not provided, it will be interactively requested from the user
Required No
Multi-Valued No

--use-legacy-export-format

Description Use a legacy export format that is compatible with pre-7.0 server versions. If this argument is provided, then the --id argument must also be provided to specify exactly one encryption settings definition to export. Note that in general, it is better to import settings from an older server into a newer one rather than the other way around, and settings exported using the legacy format will have a different identifier than the setting has in this encryption settings database

freeze

Freeze the encryption settings database so that no changes (including creating new definitions, removing existing definitions, changing the preferred definition, updating data encryption restrictions) can be made to it. A passphrase must be provided when freezing the database (whether obtained interactively or read from a file), and the same passphrase will be required to unfreeze the database


freeze Examples

Freeze the encryption settings database with a passphrase that is provided at an interactive prompt: 
encryption-settings freeze


Freeze the encryption settings database with a passphrase that is read from the specified file: 
encryption-settings freeze --passphrase-file /tmp/freeze-passphrase.txt

freeze Arguments

--passphrase-file {path}

Description The path to a file containing the passphrase that will be used to freeze the database. If this is provided, the file must exist and must contain exactly one line that is comprised entirely of the passphrase to use to freeze the database. If this is not provided, then the tool will interactively prompt for the passphrase
Required No
Multi-Valued No

get-data-encryption-restrictions

Displays a list of the data encryption restrictions that are currently in effect (as well as a list of those that are not in effect) for the server


get-data-encryption-restrictions Examples

Display a list of the data encryption restrictions that are currently in effect (as well as a list of those that are not in effect) for the server: 
encryption-settings get-data-encryption-restrictions

import

Import one or more encryption settings definitions into the server


import Examples

Import the encryption settings data from file /tmp/exported-key using the passphrase from file /tmp/export-passphrase.txt to decrypt its contents. It will be used to set the preferred definition for subsequent encryption operations: 
encryption-settings import --input-file /tmp/exported-key \
     --passphrase-file /tmp/export-passphrase.txt --set-preferred

import Arguments

-i {path}
--input-file {path}

Description The path of the input file containing the encryption settings definitions to import
Required Yes
Multi-Valued No

-W {path}
--passphrase-file {path}

Description The path of the file containing the passphrase that should be used to decrypt the exported encryption settings. If this is not provided, it will be interactively requested from the user
Required No
Multi-Valued No

-p
--set-preferred

Description Update the preferred encryption settings definition based on the information contained in the input file. If the input file contains only a single definition, then that definition will be the new preferred definition. If the input file contains multiple definitions, then the new preferred definition will be the one that is marked as preferred in the export, or the last definition in the input file if none of the definitions are marked preferred

is-frozen

Indicates whether the encryption settings database is currently frozen


is-frozen Examples

Indicate whether the encryption settings database is currently frozen: 
encryption-settings is-frozen

list

List all of the encryption settings definitions available to the server


list Examples

List all of the available encryption settings definitions: 
encryption-settings list

list Arguments

-v
--verbose

Description Display verbose output

set-data-encryption-restrictions

Add or remove a set of data encryption restrictions for the server. Supported data encryption restrictions include: prevent-disabling-data-encryption, prevent-changing-cipher-stream-provider, prevent-encryption-settings-export, prevent-unencrypted-ldif-export, prevent-passphrase-encrypted-ldif-export, prevent-unencrypted-backup, prevent-passphrase-encrypted-backup, and prevent-decrypt-file


set-data-encryption-restrictions Examples

Add a specified set of data encryption restrictions for the server: 
encryption-settings set-data-encryption-restrictions \
     --add-restriction prevent-disabling-data-encryption \
     --add-restriction prevent-changing-cipher-stream-provider


Remove a data encryption restriction from the server: 
encryption-settings set-data-encryption-restrictions \
     --remove-restriction prevent-changing-cipher-stream-provider


Adds all defined data encryption restrictions for the server: 
encryption-settings set-data-encryption-restrictions --add-all-restrictions

set-data-encryption-restrictions Arguments

--add-restriction {name}

Description Adds a data encryption restriction to the server. This argument may be provided multiple times to add multiple restrictions. Supported values include: prevent-disabling-data-encryption, prevent-changing-cipher-stream-provider, prevent-encryption-settings-export, prevent-unencrypted-ldif-export, prevent-passphrase-encrypted-ldif-export, prevent-unencrypted-backup, prevent-passphrase-encrypted-backup, and prevent-decrypt-file
Required No
Multi-Valued Yes

--remove-restriction {name}

Description Removes a data encryption restriction from the server. This argument may be provided multiple times to remove multiple restrictions. Supported values include: prevent-disabling-data-encryption, prevent-changing-cipher-stream-provider, prevent-encryption-settings-export, prevent-unencrypted-ldif-export, prevent-passphrase-encrypted-ldif-export, prevent-unencrypted-backup, prevent-passphrase-encrypted-backup, and prevent-decrypt-file
Required No
Multi-Valued Yes

--add-all-restrictions

Description Adds all defined restrictions that aren't currently set to the server

--remove-all-restrictions

Description Removes all active restrictions from the server

set-preferred

Specify the preferred settings to use for encryption in the server


set-preferred Examples

Sets the encryption settings definition with the specified ID to be preferred for subsequent encryption performed by the server: 
encryption-settings set-preferred --id DA39A3EE5E6B4B0D3255BFEF95601890AFD80709

set-preferred Arguments

-i {id}
--id {id}

Description The identifier for the encryption settings definition to set as preferred
Required Yes
Multi-Valued No

supply-passphrase

Interactively supply the passphrase needed to access the contents of the encryption settings database. This is only applicable if the server is configured to use a 'Wait for Passphrase' cipher stream provider


supply-passphrase Examples

Interactively supply the passphrase needed to access the encryption settings database: 
encryption-settings supply-passphrase

unfreeze

Unfreeze the encryption settings database so that it may be updated. A passphrase must be provided (whether obtained interactively or read from a file), which must match the passphrase used when freezing the database


unfreeze Examples

Unfreeze the encryption settings database with a passphrase that is provided at an interactive prompt: 
encryption-settings unfreeze


Unfreeze the encryption settings database with a passphrase that is read from the specified file: 
encryption-settings unfreeze --passphrase-file /tmp/freeze-passphrase.txt

unfreeze Arguments

--passphrase-file {path}

Description The path to a file containing the passphrase that will be used to unfreeze the database. If this is provided, the file must exist and must contain exactly one line that is comprised entirely of the passphrase to use to unfreeze the database. If this is not provided, then the tool will interactively prompt for the passphrase
Required No
Multi-Valued No

Arguments

-V
--version

Description Display Directory Server version information

-H
--help

Description Display general usage information

--help-debug

Description Display help for using debug options
Advanced Yes