NAME¶

kwalletcli_getpin — command line interface to pinentry

SYNOPSIS¶

DESCRIPTION¶

The kwalletcli_getpin utility is a shell wrapper speaking to pinentry using the Assuan protocol. It will ask the user for a passphrase and print it, without any trailing newline, to standard output. There are options for asking a boolean question or displaying a message.

If PINENTRY is not empty but points to a non-existing or failing program, pinentry is not called. Instead, xmessage(1) is used for boolean queries and messages if DISPLAY is set; otherwise, kwalletcli_getpin uses simple terminal I/O on GPG_TTY using stty(1) to disable echo of terminal input for passphrase queries.

The options are as follows:

-b

Ask for a confirmation (boolean) instead of a passphrase.

-E

Unset a previously set error text.

-E errtxt

Set the error text to errtxt, displaying a dialogue box with a red X icon indicating that this is a retry question.

-m

Display a message (one-button query) instead of asking.

-N NoText

Use NoText instead of Cancel for the text of the abort button, if any.

-p prompt

Set the small descriptive text shown in front of the input field (“the Prompt”) to prompt.

-q

Be more quiet.

-t desctxt

Set the descriptive text (the input challenge) to desctxt.

-Y YesText

Use YesText instead of OK for the text of the confirm button.

All input and output is assumed to be in UTF-8.

RETURN VALUES¶

The kwalletcli_getpin utility exits 0 on success, 1 if the password input was cancelled by the user, or >1 if an error occurred. Exit status for confirmation (boolean) queries are 0 for Yes, 1 for No, or >1 if an error occurred. Messages return >0 if an error occurred, 0 otherwise.

The errorlevels are as follows:

0

Read password successfully. Boolean question returned Yes/OK.

1

Boolean question returned No/Cancel.

2

Wrong command line syntax.

3

The process reading user input unexpectedly terminated or errored out.

4

Unexpected result reading from pinentry.

5

Unable to determine controlling tty, caller must set GPG_TTY.

6

Caught SIGHUP, SIGINT, SIGQUIT, SIGTRAP, SIGPIPE, or SIGTERM.

ENVIRONMENT¶

DISPLAY

If not set, pass current terminal information to pinentry.

GPG_TERM

Terminal type of the current tty. Defaults to the value of the environment variable TERM, or “vt100” if unset.

GPG_TTY

The current terminal, determined by tty(1) if unset.

PINENTRY

The pinentry program to use. Default: “pinentry”

kwalletcli_getpin requires a UTF-8 locale; if such is not set, it will forcibly switch the locale (LC_CTYPE, possibly LC_ALL) to “C.UTF-8”. When kwalletcli_getpin calls xmessage(1), it will change the locale (LC_ALL) to “C” and convert the prompt to Latin-1.

SEE ALSO¶

gpg-agent(1), kwalletcli(1), pinentry(1), stty(1), tset(1), tty(1)

AUTHORS¶

kwalletcli_getpin was written by mirabilos ⟨m$(date$IFS+%Y)@mirbsd.de⟩ initially for tarent GmbH, but is now developed independently.

CAVEATS¶

Some newer pinentry features, such as three-button operation or setting the window title, are not supported yet.

BUGS¶

Some pinentry programs may not support messages correctly and display them as boolean queries instead.

Some implementations display labels with the wrong charset.

Neither of these two problems is an issue in kwalletcli_getpin but a bug of the backend implementation.