NAME¶
kwalletcli_getpin
—
command line interface to pinentry
SYNOPSIS¶
kwalletcli_getpin |
[ -q ]
[-b |
-m |
-p
prompt ]
[-E |
-e
errortext ]
[-N
NoText ]
[-t
desctext ]
[-Y
YesText ] |
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 programme,
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 passphrase input was cancelled by the user, or >1 if an
error occurred. Confirmation (boolean) error codes are 0 for Yes, 1 for No, or
>1 if an error occurred. Messages return >0 if an error occurred, 0
otherwise.
A summary of the error codes 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.
LC_CTYPE
- Passed to
pinentry
. Default:
“en_US.UTF-8”
LC_MESSAGES
- Passed to
pinentry
. Unset by
default.
PINENTRY
- The
pinentry
programme to use. Default:
“pinentry”
SEE ALSO¶
gpg-agent(1),
kwalletcli(1),
pinentry(1),
stty(1),
tset(1),
tty(1)
AUTHORS¶
kwalletcli_getpin
was written by
Thorsten Glaser
⟨tg@mirbsd.org⟩ mostly for tarent GmbH.
CAVEATS¶
Some newer pinentry features, such as three-button operation or setting the
window title, are not supported yet.
BUGS¶
Some
pinentry
programmes 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.