The encrypt-file tool

The PingDirectory server includes a command-line tool that can be used to encrypt and decrypt files using keys from the server’s encryption settings database or using a passphrase that you provide interactively or in a file.

This tool offers the following arguments.

Argument Description

Argument	Description
`--input-file`	Specifies the path to the file containing the data to be encrypted or decrypted. If this is not provided, then the data can be read from standard input, such as entered interactively or piped from another command.
`--output-file`	Specifies the path to the file to which the encrypted or decrypted data is written. If this is not provided, the data is written to standard output.
`--decrypt`	Indicates that input is expected to be encrypted, and the tool should decrypt it. If this argument is not provided, then the tool encrypts the input data.
`--prompt-for-passphrase`	Indicates that the tool should interactively prompt for the passphrase to use to encrypt or decrypt the input data. If this is provided, then the `--input-file` argument must also be provided because the tool does not support both prompting for a passphrase and reading the data to process from standard input.
`--passphrase-file`	Specifies the path to a file containing the passphrase to use to encrypt or decrypt the input data.
`--encryption-settings-id`	Specifies the identifier for an encryption settings definition that is used to encrypt or decrypt the input data.
`--use-topology-key`	Indicates that the data should be encrypted or decrypted using a key that is generated by and shared among servers in the replication topology. This is a legacy encryption mechanism that is no longer used by modern versions of the server, and it is only needed when encrypting data that might need to be decrypted by older instances in the same topology.
`--compress-output`	Indicates that the output should be gzip-compressed as it is written. When the tool is operating in encrypt mode, the data is compressed before it is encrypted.
`--decompress-input`	Indicates that the input data is gzip-compressed. When operating in decrypt mode, the data is decompressed after it has been decrypted.
`max-megabytes-per-second`	The maximum rate at which the tool should write the encrypted or decrypted data. This can be helpful when operating on large files as a way of avoiding excessive disk I/O that might impact the performance of other I/O operations on a busy server.

--input-file

Specifies the path to the file containing the data to be encrypted or decrypted. If this is not provided, then the data can be read from standard input, such as entered interactively or piped from another command.

--output-file

Specifies the path to the file to which the encrypted or decrypted data is written. If this is not provided, the data is written to standard output.

--decrypt

Indicates that input is expected to be encrypted, and the tool should decrypt it. If this argument is not provided, then the tool encrypts the input data.

--prompt-for-passphrase

Indicates that the tool should interactively prompt for the passphrase to use to encrypt or decrypt the input data. If this is provided, then the --input-file argument must also be provided because the tool does not support both prompting for a passphrase and reading the data to process from standard input.

--passphrase-file

Specifies the path to a file containing the passphrase to use to encrypt or decrypt the input data.

--encryption-settings-id

Specifies the identifier for an encryption settings definition that is used to encrypt or decrypt the input data.

--use-topology-key

Indicates that the data should be encrypted or decrypted using a key that is generated by and shared among servers in the replication topology. This is a legacy encryption mechanism that is no longer used by modern versions of the server, and it is only needed when encrypting data that might need to be decrypted by older instances in the same topology.

--compress-output

Indicates that the output should be gzip-compressed as it is written. When the tool is operating in encrypt mode, the data is compressed before it is encrypted.

--decompress-input

Indicates that the input data is gzip-compressed. When operating in decrypt mode, the data is decompressed after it has been decrypted.

max-megabytes-per-second

The maximum rate at which the tool should write the encrypted or decrypted data. This can be helpful when operating on large files as a way of avoiding excessive disk I/O that might impact the performance of other I/O operations on a busy server.

The --prompt-for-passphrase, --passphrase-file, --encryption-settings-id, and --use-topology-key arguments are all mutually exclusive and cannot be used together. If none of these arguments is provided, then the tool uses a key from the encryption settings database. When encrypting data, it uses the preferred definition. When decrypting data that was encrypted with an encryption settings definition, the encryption header at the beginning of the file should contain the identifier for the appropriate definition.