ssl_passphrase_command

Definition PG 18 manual

Sets an external command to be invoked when a passphrase for decrypting an SSL file such as a private key needs to be obtained. By default, this parameter is empty, which means the built-in prompting mechanism is used.

The command must print the passphrase to the standard output and exit with code 0. In the parameter value, %p is replaced by a prompt string. (Write %% for a literal %.) Note that the prompt string will probably contain whitespace, so be sure to quote adequately. A single newline is stripped from the end of the output if present.

The command does not actually have to prompt the user for a passphrase. It can read it from a file, obtain it from a keychain facility, or similar. It is up to the user to make sure the chosen mechanism is adequately secure.

This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

ssl_passphrase_command is an external helper invoked when PostgreSQL must decrypt an SSL file such as an encrypted private key. The helper must write the passphrase to standard output and exit with status zero; PostgreSQL strips one trailing newline from the output.

Within the configured command, %p is replaced by a prompt string that can contain whitespace and therefore must be quoted safely; %% emits a literal percent. The command runs as the PostgreSQL service account, and its environment, path, arguments, output, and error logging must not expose the secret.

It has SIGHUP context, but whether an encrypted key can be replaced during reload also depends on ssl_passphrase_command_supports_reload. A noninteractive keychain/file helper can support reload; a TTY prompt is normally suitable only for controlled startup, and Windows has additional reload requirements.

Operational considerations

Printing anything except the passphrase to standard output or returning a nonzero status.

Failing to quote %p even though the substituted prompt can contain whitespace, or forgetting that %% is required for a literal percent.

Exposing the passphrase through command arguments, process listings, environment variables, shell tracing, stderr, or server logs.

Deploying a helper that works interactively on one primary but fails during unattended restart, reload, or failover.

Workload guidance

OLAP: Use the identical helper and secret source on analytical nodes; workload class does not change the private-key trust requirement. Test unattended restart before scheduling certificate rotation.

OLTP: Use an absolute-path, minimal, noninteractive helper backed by a protected keychain or file descriptor. Test exact stdout, exit status, %p quoting, timeout/failure, startup, reload, and failover-node availability without logging the passphrase.

SMALL: Prefer the simplest auditable helper that can restart unattended. If a TTY prompt is retained, document that reload cannot replace an encrypted key unless supports_reload is safely enabled.