pinentry-kwallet.1

.\" $MirOS: contrib/hosted/tg/code/kwalletcli/pinentry-kwallet.1,v 1.17 2024/01/05 02:08:52 tg Exp $
.\"-
.\" Copyright © 2009, 2010, 2011, 2016
.\"	mirabilos <m@mirbsd.org>
.\"
.\" Provided that these terms and disclaimer and all copyright notices
.\" are retained or reproduced in an accompanying document, permission
.\" is granted to deal in this work without restriction, including un‐
.\" limited rights to use, publicly perform, distribute, sell, modify,
.\" merge, give away, or sublicence.
.\"
.\" This work is provided “AS IS” and WITHOUT WARRANTY of any kind, to
.\" the utmost extent permitted by applicable law, neither express nor
.\" implied; without malicious intent or gross negligence. In no event
.\" may a licensor, author or contributor be held liable for indirect,
.\" direct, other damage, loss, or other issues arising in any way out
.\" of dealing in the work, even if advised of the possibility of such
.\" damage or existence of a defect, except proven that it results out
.\" of said person’s immediate fault when using the work as intended.
.\"-
.\" $miros: contrib/samples/portmdoc,v 1.23 2024/01/04 22:52:50 tg Exp $
.\"-
.\" Copyright © 2008, 2009, 2010, 2016, 2018, 2020, 2023
.\"	mirabilos <m@mirbsd.org>
.\"
.\" Glue GNU groff (BSD and GNU mdoc both) to AT&T nroff (UCB mdoc).
.\" * ` generates ‘ in gnroff, so use \`
.\" * ' generates ’ in gnroff, \' generates ´, so use \*(aq
.\" * - generates ‐ in gnroff, \- generates −, so .tr it to -
.\"   thus use - for hyphens and \- for minus signs and option dashes
.\" * ~ is size-reduced and placed atop in groff, so use \*(TI
.\" * ^ is size-reduced and placed atop in groff, so use \*(ha
.\" * \(en does not work in nroff, so use \*(en for a solo en dash
.\" *   and \*(EM for a correctly spaced em dash
.\" * <>| are problematic, so redefine and use \*(Lt\*(Gt\*(Ba
.\" Also make sure to use \& *before* a punctuation char that is to not
.\" be interpreted as punctuation, and especially with two-letter words
.\" but also (after) a period that does not end a sentence (“e.g.\&”).
.\"-
.\"
.\" Implement .Dd with the Mdocdate RCS keyword
.\"
.rn Dd xD
.de Dd
.ie \\$1$Mdocdate: \{\
.	xD \\$2 \\$3, \\$4
.\}
.el .xD \\$1 \\$2 \\$3
..
.\"
.\" .Dd must come before most everything, because when called
.\" with -mandoc it loads -mdoc via .so in .Dd (first macro).
.\"
.Dd $Mdocdate: January 5 2024 $
.\"
.\" Check which macro package we use, and do other -mdoc setup.
.\"
.ie \n(.g \{\
.	if n .ss \n[.ss] 0
.	if 
\*[.T]
ascii
 .tr \-\N'45'
.	if 
\*[.T]
latin1
 .tr \-\N'45'
.	if 
\*[.T]
utf8
 .tr \-\N'45'
.	if 
\*[.T]
utf8
 .tr \(la\*(Lt
.	if 
\*[.T]
utf8
 .tr \(ra\*(Gt
.	ds <= \(<=
.	ds >= \(>=
.	ds Rq \(rq
.	ds Lq \(lq
.	ds sL \(aq
.	ds sR \(aq
.	if 
\*[.T]
utf8
 .ds sL `
.	if 
\*[.T]
ps
 .ds sL `
.	if 
\*[.T]
utf8
 .ds sR '
.	if 
\*[.T]
ps
 .ds sR '
.	ds aq \(aq
.	ds TI \(ti
.	ds ha \(ha
.	ds en \(en
.	ie d volume-ds-1 .ds tT gnu
.	el .ie d doc-volume-ds-1 .ds tT gnp
.	el .ds tT bsd
.\}
.el \{\
.	ds aq '
.	ds TI ~
.	ds ha ^
.	ds en \(em
.	ds tT ucb
.\}
.ie n \{\
.	ds EM \ \(em\ \&
.\}
.el \{\
.	ds EM \f(TR\|\(em\|\fP
.\}
.\"
.\" Add UCB mdoc compatibility to GNU mdoc
.\" Implement .Mx (MirBSD)
.\"
.ie "\*(tT"gnu" \{\
.	ds sP \s0
.	ds tN \*[Tn-font-size]
.	eo
.	de Mx
.	nr curr-font \n[.f]
.	nr curr-size \n[.ps]
.	ds str-Mx \f[\n[curr-font]]\s[\n[curr-size]u]
.	ds str-Mx1 \*(tN\%MirBSD\*[str-Mx]
.	if !\n[arg-limit] \
.	if \n[.$] \{\
.	ds macro-name Mx
.	parse-args \$@
.	\}
.	if (\n[arg-limit] > \n[arg-ptr]) \{\
.	nr arg-ptr +1
.	ie (\n[type\n[arg-ptr]] == 2) \
.	ds str-Mx1 \*(tN\%MirBSD\~#\*[arg\n[arg-ptr]]\*[str-Mx]
.	el \
.	nr arg-ptr -1
.	\}
.	ds arg\n[arg-ptr] "\*[str-Mx1]
.	nr type\n[arg-ptr] 2
.	ds space\n[arg-ptr] "\*[space]
.	nr num-args (\n[arg-limit] - \n[arg-ptr])
.	nr arg-limit \n[arg-ptr]
.	if \n[num-args] \
.	parse-space-vector
.	print-recursive
..
.	de Aq
.	if !\n[arg-limit] \
.	ds macro-name Aq
.	ie \n[in-authors-section] \{\
.		ds quote-left \*(Lt
.		ds quote-right \*(Gt
.	\}
.	el \{\
.		ds quote-left \[la]
.		ds quote-right \[ra]
.	\}
.	enclose-string \$@
..
.	ec
.\}
.el .ie "\*(tT"gnp" \{\
.	ds sP \s0
.	ie t .ds tN \s[(\n[.ps]u-1z)]
.	el .ds tN
.	eo
.	de Mx
.	nr doc-curr-font \n[.f]
.	nr doc-curr-size \n[.ps]
.	ds doc-str-Mx \f[\n[doc-curr-font]]\s[\n[doc-curr-size]u]
.	ds doc-str-Mx1 \*(tN\%MirBSD\*[doc-str-Mx]
.	if !\n[doc-arg-limit] \
.	if \n[.$] \{\
.	ds doc-macro-name Mx
.	doc-parse-args \$@
.	\}
.	if (\n[doc-arg-limit] > \n[doc-arg-ptr]) \{\
.	nr doc-arg-ptr +1
.	ie (\n[doc-type\n[doc-arg-ptr]] == 2) \
.	ds doc-str-Mx1 \*(tN\%MirBSD\~#\*[doc-arg\n[doc-arg-ptr]]\*[doc-str-Mx]
.	el \
.	nr doc-arg-ptr -1
.	\}
.	ds doc-arg\n[doc-arg-ptr] "\*[doc-str-Mx1]
.	nr doc-type\n[doc-arg-ptr] 2
.	ds doc-space\n[doc-arg-ptr] "\*[doc-space]
.	nr doc-num-args (\n[doc-arg-limit] - \n[doc-arg-ptr])
.	nr doc-arg-limit \n[doc-arg-ptr]
.	if \n[doc-num-args] \
.	doc-parse-space-vector
.	doc-print-recursive
..
.	ec
.\}
.el \{\
.	de Mx
.	nr cF \\n(.f
.	nr cZ \\n(.s
.	ds aa \&\f\\n(cF\s\\n(cZ
.	if \\n(aC==0 \{\
.		ie \\n(.$==0 \&\\*(tNMirBSD\\*(aa
.		el .aV \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.	\}
.	if \\n(aC>\\n(aP \{\
.		nr aP \\n(aP+1
.		ie \\n(C\\n(aP==2 \{\
.			nr xX 0
.			nr xX 1+\\*(A\\n(aP
.			as b1 \&\\*(tNMirBSD\ \&
.			if \\n(xX>0 .as b1 #\&
.			as b1 \&\\*(A\\n(aP\\*(aa
.			rr xX
.			ie \\n(aC>\\n(aP \{\
.				nr aP \\n(aP+1
.				nR
.			\}
.			el .aZ
.		\}
.		el \{\
.			as b1 \&\\*(tNMirBSD\\*(aa
.			nR
.		\}
.	\}
..
.\}
.\" </MirCVS://contrib/samples/portmdoc>
.\"-
.Dt PINENTRY\-KWALLET 1
.Os
.Sh NAME
.Nm pinentry\-kwallet
.Nd kwallet-based pass-phrase dialog for use with GnuPG
.Sh SYNOPSIS
.Nm
.Op Fl q
.Op Ar options
.Sh DESCRIPTION
.Nm
is a kwallet- and pinentry-based pass-phrase dialog for use with GnuPG.
It is intended to be called from the
.Xr gpg\-agent 1
daemon and not invoked directly.
.Pp
.Nm
replaces the regular
.Ic pinentry\-program
stanza set in
.Pa \*(TI/.gnupg/gpg\-agent.conf
and looks up the passphrases requested in the KWallet first, falling back to
.Nm pinentry
only if not found.
The user is given the option to store it in the KWallet afterwards.
Negative answers to this are also stored in the KWallet to avoid
asking each time.
.Pp
.Nm
.Pq like other pinentry variants
talks a simplified subset of the regular Assuan protocol on stdio;
all commands, even unknown ones, are passed through to a
.Nm pinentry
co-process during run-time, even if the latter is never used.
It accepts the same options as
.Nm pinentry ,
even unknown ones, because it is designed to plug in.
As an exception,
.Fl q
makes
.Nm
more quiet (suppress warnings on stderr), and
.Fl V
displays the version on stderr (unless
.Fl q ) .
.Pp
.Nm
attempts sophisticated error handling:
if an error dialogue is displayed, an internal counter is increased.
If the counter reaches 2, the value stored in the KWallet is ignored,
and the user is asked anew.
The counter is stored in the KWallet, which is suboptimal but necessary,
because
.Xr gpg2 1
does not re-use the Assuan sessions, instead spawning a new
.Nm
each time a passphrase is required (rather stupid).
Error counters are valid for 15 seconds since their last increasement.
.Sh RETURN VALUES
.Nm
exits 1 if it is called recursively, 0 if help or version
information are requested, and return codes do not matter
in any other cases because errors are signalled in-band.
It will exit 0 after the Assuan session is terminated.
.Sh ENVIRONMENT
.Bl -tag -width PINENTRY
.It Ev DISPLAY
The X11 display to use for child processes.
If not set,
.Nm
will immediately replace itself with the slave
.Ev PINENTRY
program to use.
.It Ev GPG_TERM
Terminal type of the current tty.
.It Ev GPG_TTY
The current terminal.
.It Ev PINENTRY
The
.Nm pinentry
program to use.
Default:
.Dq pinentry
.El
.Sh SEE ALSO
.Xr date 1 ,
.Xr gpg\-agent 1 ,
.Xr gpg2 1 ,
.Xr kwalletcli 1 ,
.Xr kwalletcli_getpin 1 ,
.Xr mksh 1 ,
.Xr pinentry\-curses 1 ,
.Xr pinentry\-gtk\-2 1 ,
.Xr pinentry\-qt 1 ,
.Xr pinentry\-x11 1
.Sh AUTHORS
.Nm
was written by
.An mirabilos Aq m@mirbsd.org
mostly for tarent solutions GmbH.
.Sh CAVEATS
Some newer pinentry features, such as three-button operation,
are not supported yet.
.Pp
Some commands, such as version inquiry, as passed through to
the pinentry coprocess indiscriminately, which may lead to
strange results, should the protocol change or extend.