Next: Agent CLEAR_PASSPHRASE, Previous: Agent ISTRUSTED, Up: Agent Protocol

#### 2.6.7 Ask for a passphrase

This function is usually used to ask for a passphrase to be used for symmetric encryption, but may also be used by programs which need special handling of passphrases. This command uses a syntax which helps clients to use the agent with minimum effort.

           GET_PASSPHRASE [--data] [--check] [--no-ask] [--repeat[=N]] [--qualitybar] cache_id [error_message prompt description]

cache_id is expected to be a string used to identify a cached passphrase. Use a `X` to bypass the cache. With no other arguments the agent returns a cached passphrase or an error. By convention either the hexified fingerprint of the key shall be used for cache_id or an arbitrary string prefixed with the name of the calling application and a colon: Like `gpg:somestring`.

error_message is either a single `X` for no error message or a string to be shown as an error message like (e.g. "invalid passphrase"). Blanks must be percent escaped or replaced by `+`'.

prompt is either a single `X` for a default prompt or the text to be shown as the prompt. Blanks must be percent escaped or replaced by `+`.

description is a text shown above the entry field. Blanks must be percent escaped or replaced by `+`.

The agent either returns with an error or with a OK followed by the hex encoded passphrase. Note that the length of the strings is implicitly limited by the maximum length of a command. If the option `--data` is used, the passphrase is not returned on the OK line but by regular data lines; this is the preferred method.

If the option `--check` is used, the standard passphrase constraints checks are applied. A check is not done if the passphrase has been found in the cache.

If the option `--no-ask` is used and the passphrase is not in the cache the user will not be asked to enter a passphrase but the error code `GPG_ERR_NO_DATA` is returned.

If the option `--qualitybar` is used and a minimum passphrase length has been configured, a visual indication of the entered passphrase quality is shown.

           CLEAR_PASSPHRASE cache_id

may be used to invalidate the cache entry for a passphrase. The function returns with OK even when there is no cached passphrase.