* doc/ChangeLog: Removed and merged with this file.
authorWerner Koch <wk@gnupg.org>
Mon, 22 Dec 2003 17:01:08 +0000 (17:01 +0000)
committerWerner Koch <wk@gnupg.org>
Mon, 22 Dec 2003 17:01:08 +0000 (17:01 +0000)
* doc/pinentry.texi: Cleaned up.
* doc/fdl.texi: Removed.

* pinentry/pinentry.c (pinentry_parse_opts): Make short options work.
(pinentry_utf8_to_local): Pass nl_langinfo to iconv_open.

ChangeLog
TODO
doc/Makefile.am
doc/fdl.texi [deleted file]
doc/pinentry.texi
pinentry/pinentry.c
pinentry/pinentry.h

index b980989..9f7b4e5 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,12 +1,18 @@
 2003-12-22  Werner Koch  <wk@gnupg.org>
 
+       * doc/ChangeLog: Removed and merged with this file.
+       * doc/pinentry.texi: Cleaned up.
+       * doc/fdl.texi: Removed.
+
        * pinentry/pinentry.h (struct pinentry): Added LOCALE_ERR.
        * gtk/pinentry-gtk.c (button_clicked): Set the LOCAE_ERR flag.
        * pinentry/pinentry-curses.c (dialog_run): Ditto.
-       * pinentry/pinentry.c (cmd_getpin, cms_confirm): Check this flag.
+       * pinentry/pinentry.c (cmd_getpin, cmd_confirm): Check this flag.
        (pinentry_local_to_utf8): Release the correct buffer in the error
        case. Print diagnostics.
        (pinentry_utf8_to_local): Print diagnostics.
+       (pinentry_parse_opts): Make short options work.
+       (pinentry_utf8_to_local): Pass nl_langinfo to iconv_open.
 
        * gtk/pinentry-gtk.c (button_clicked): Use the right value as
        input for the conversion.
 
        * configure.ac, Makefile.am: Added doc/ and tests for makeinfo
 
+       * doc/pinentry.texi, doc/Makefile.am: New.
+       * doc/gpl.texi, doc/fdl.texi: Added these standard files.
+
 2002-09-30  Werner Koch  <wk@gnupg.org>
 
         Released 0.6.5.
        (TESTS): Added client-test.
        (AUTOMAKE_OPTIONS): Added gnits. 
 
+       
+ Copyright 2002, 2003 g10 Code GmbH
+
+ This file is free software; as a special exception the author gives
+ unlimited permission to copy and/or distribute it, with or without
+ modifications, as long as this notice is preserved.
+
+ This file is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
+ implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
diff --git a/TODO b/TODO
index fe719d4..53b3ebe 100644 (file)
--- a/TODO
+++ b/TODO
@@ -4,10 +4,8 @@
   (This is not so important, as pinentry is always restarted.)
 
 * The Qt and curses PIN entry should support enhanced mode (when it is
-  implemented in gpg-agent).
-
-* The GTK+ PIN entry needs to convert the text of the button label
-  from UTF-8 to the local encoding.
+  implemented in gpg-agent).  We need to agree on a protocol to use
+  anyway.
 
 * Set the max length of password globally (dynamically in protocol?).
 
index e9c9314..5cffc5a 100644 (file)
@@ -20,7 +20,7 @@
 
 info_TEXINFOS = pinentry.texi
 
-pinentry_TEXINFOS = gpl.texi fdl.texi
+pinentry_TEXINFOS = gpl.texi
 
 DISTCLEANFILES = pinentry.tmp pinentry.ops
 
diff --git a/doc/fdl.texi b/doc/fdl.texi
deleted file mode 100644 (file)
index 6e40e6d..0000000
+++ /dev/null
@@ -1,401 +0,0 @@
-@node GNU Free Documentation License
-@appendix GNU Free Documentation License
-
-@cindex FDL, GNU Free Documentation License
-@center Version 1.1, March 2000
-
-@display
-Copyright @copyright{} 2000 Free Software Foundation, Inc.
-59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-@end display
-
-@enumerate 0
-@item
-PREAMBLE
-
-The purpose of this License is to make a manual, textbook, or other
-written document @dfn{free} in the sense of freedom: to assure everyone
-the effective freedom to copy and redistribute it, with or without
-modifying it, either commercially or noncommercially.  Secondarily,
-this License preserves for the author and publisher a way to get
-credit for their work, while not being considered responsible for
-modifications made by others.
-
-This License is a kind of ``copyleft'', which means that derivative
-works of the document must themselves be free in the same sense.  It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does.  But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book.  We recommend this License
-principally for works whose purpose is instruction or reference.
-
-@item
-APPLICABILITY AND DEFINITIONS
-
-This License applies to any manual or other work that contains a
-notice placed by the copyright holder saying it can be distributed
-under the terms of this License.  The ``Document'', below, refers to any
-such manual or work.  Any member of the public is a licensee, and is
-addressed as ``you''.
-
-A ``Modified Version'' of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A ``Secondary Section'' is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject.  (For example, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.)  The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The ``Invariant Sections'' are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License.
-
-The ``Cover Texts'' are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License.
-
-A ``Transparent'' copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, whose contents can be viewed and edited directly and
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters.  A copy made in an otherwise Transparent file
-format whose markup has been designed to thwart or discourage
-subsequent modification by readers is not Transparent.  A copy that is
-not ``Transparent'' is called ``Opaque''.
-
-Examples of suitable formats for Transparent copies include plain
-@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
-@acronym{SGML} or @acronym{XML} using a publicly available
-@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
-for human modification.  Opaque formats include PostScript,
-@acronym{PDF}, proprietary formats that can be read and edited only by
-proprietary word processors, @acronym{SGML} or @acronym{XML} for which
-the @acronym{DTD} and/or processing tools are not generally available,
-and the machine-generated @acronym{HTML} produced by some word
-processors for output purposes only.
-
-The ``Title Page'' means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page.  For works in
-formats which do not have any title page as such, ``Title Page'' means
-the text near the most prominent appearance of the work's title,
-preceding the beginning of the body of the text.
-
-@item
-VERBATIM COPYING
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License.  You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute.  However, you may accept
-compensation in exchange for copies.  If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
-@item
-COPYING IN QUANTITY
-
-If you publish printed copies of the Document numbering more than 100,
-and the Document's license notice requires Cover Texts, you must enclose
-the copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover.  Both covers must also clearly and legibly identify
-you as the publisher of these copies.  The front cover must present
-the full title with all words of the title equally prominent and
-visible.  You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a publicly-accessible computer-network location containing a complete
-Transparent copy of the Document, free of added material, which the
-general network-using public has access to download anonymously at no
-charge using public-standard network protocols.  If you use the latter
-option, you must take reasonably prudent steps, when you begin
-distribution of Opaque copies in quantity, to ensure that this
-Transparent copy will remain thus accessible at the stated location
-until at least one year after the last time you distribute an Opaque
-copy (directly or through your agents or retailers) of that edition to
-the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
-@item
-MODIFICATIONS
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it.  In addition, you must do these things in the Modified Version:
-
-@enumerate A
-@item
-Use in the Title Page (and on the covers, if any) a title distinct
-from that of the Document, and from those of previous versions
-(which should, if there were any, be listed in the History section
-of the Document).  You may use the same title as a previous version
-if the original publisher of that version gives permission.
-
-@item
-List on the Title Page, as authors, one or more persons or entities
-responsible for authorship of the modifications in the Modified
-Version, together with at least five of the principal authors of the
-Document (all of its principal authors, if it has less than five).
-
-@item
-State on the Title page the name of the publisher of the
-Modified Version, as the publisher.
-
-@item
-Preserve all the copyright notices of the Document.
-
-@item
-Add an appropriate copyright notice for your modifications
-adjacent to the other copyright notices.
-
-@item
-Include, immediately after the copyright notices, a license notice
-giving the public permission to use the Modified Version under the
-terms of this License, in the form shown in the Addendum below.
-
-@item
-Preserve in that license notice the full lists of Invariant Sections
-and required Cover Texts given in the Document's license notice.
-
-@item
-Include an unaltered copy of this License.
-
-@item
-Preserve the section entitled ``History'', and its title, and add to
-it an item stating at least the title, year, new authors, and
-publisher of the Modified Version as given on the Title Page.  If
-there is no section entitled ``History'' in the Document, create one
-stating the title, year, authors, and publisher of the Document as
-given on its Title Page, then add an item describing the Modified
-Version as stated in the previous sentence.
-
-@item
-Preserve the network location, if any, given in the Document for
-public access to a Transparent copy of the Document, and likewise
-the network locations given in the Document for previous versions
-it was based on.  These may be placed in the ``History'' section.
-You may omit a network location for a work that was published at
-least four years before the Document itself, or if the original
-publisher of the version it refers to gives permission.
-
-@item
-In any section entitled ``Acknowledgments'' or ``Dedications'',
-preserve the section's title, and preserve in the section all the
-substance and tone of each of the contributor acknowledgments
-and/or dedications given therein.
-
-@item
-Preserve all the Invariant Sections of the Document,
-unaltered in their text and in their titles.  Section numbers
-or the equivalent are not considered part of the section titles.
-
-@item
-Delete any section entitled ``Endorsements''.  Such a section
-may not be included in the Modified Version.
-
-@item
-Do not retitle any existing section as ``Endorsements''
-or to conflict in title with any Invariant Section.
-@end enumerate
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant.  To do this, add their titles to the
-list of Invariant Sections in the Modified Version's license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section entitled ``Endorsements'', provided it contains
-nothing but endorsements of your Modified Version by various
-parties---for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version.  Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity.  If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
-@item
-COMBINING DOCUMENTS
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy.  If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections entitled ``History''
-in the various original documents, forming one section entitled
-``History''; likewise combine any sections entitled ``Acknowledgments'',
-and any sections entitled ``Dedications''.  You must delete all sections
-entitled ``Endorsements.''
-
-@item
-COLLECTIONS OF DOCUMENTS
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
-@item
-AGGREGATION WITH INDEPENDENT WORKS
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, does not as a whole count as a Modified Version
-of the Document, provided no compilation copyright is claimed for the
-compilation.  Such a compilation is called an ``aggregate'', and this
-License does not apply to the other self-contained works thus compiled
-with the Document, on account of their being thus compiled, if they
-are not themselves derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one quarter
-of the entire aggregate, the Document's Cover Texts may be placed on
-covers that surround only the Document within the aggregate.
-Otherwise they must appear on covers around the whole aggregate.
-
-@item
-TRANSLATION
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections.  You may include a
-translation of this License provided that you also include the
-original English version of this License.  In case of a disagreement
-between the translation and the original English version of this
-License, the original English version will prevail.
-
-@item
-TERMINATION
-
-You may not copy, modify, sublicense, or distribute the Document except
-as expressly provided for under this License.  Any other attempt to
-copy, modify, sublicense or distribute the Document is void, and will
-automatically terminate your rights under this License.  However,
-parties who have received copies, or rights, from you under this
-License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
-@item
-FUTURE REVISIONS OF THIS LICENSE
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time.  Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.  See
-@uref{http://www.gnu.org/copyleft/}.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License ``or any later version'' applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation.  If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation.
-@end enumerate
-
-@page
-@appendixsubsec ADDENDUM: How to use this License for your documents
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
-@smallexample
-@group
-  Copyright (C)  @var{year}  @var{your name}.
-  Permission is granted to copy, distribute and/or modify this document
-  under the terms of the GNU Free Documentation License, Version 1.1
-  or any later version published by the Free Software Foundation;
-  with the Invariant Sections being @var{list their titles}, with the
-  Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
-  A copy of the license is included in the section entitled ``GNU
-  Free Documentation License''.
-@end group
-@end smallexample
-
-If you have no Invariant Sections, write ``with no Invariant Sections''
-instead of saying which ones are invariant.  If you have no
-Front-Cover Texts, write ``no Front-Cover Texts'' instead of
-``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
-
-@c Local Variables:
-@c ispell-local-pdict: "ispell-dict"
-@c End:
index f62d726..8d62f15 100644 (file)
@@ -9,15 +9,17 @@ Copyright @copyright{} 2002 g10 Code GmbH
 @end macro
 @macro permissionnotice
 Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover texts, and with no Back-Cover
-Texts.  A copy of the license is included in the section entitled ``GNU
-Free Documentation License''.
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2 of the License, or (at your
+option) any later version. The text of the license can be found in the
+section entitled ``Copying''.
 @end macro
 
+@macro pinentry
+@sc{pinentry}
+@end macro
 
-@settitle Using the PINEntry
+@settitle Using the PIN-Entry
 
 @c Create a separate index for command line options.
 @defcodeindex op
@@ -60,17 +62,16 @@ Free Documentation License''.
 @ifnottex
 @dircategory GNU Utilities
 @direntry
-* gpg: (gnupg).            OpenPGP encryption and signing tool.
-* gpgsm: (gnupg).          S/MIME encryption and signing tool.
+* pinentry::               Ask securely for a passphrase or PIN.
 @end direntry
-This file documents the use and the internals of the PINEnrty.
+This file documents the use and the internals of the @pinentry{}.
 
 This is edition @value{EDITION}, last updated @value{UPDATED}, of
 @cite{The `PINEnrty' Manual}, for version @value{VERSION}.
 @sp 1
 Published by g10 Code GmbH@*
-Remscheider Str. 22@*
-40215 Düsseldorf, Germany
+Hüttenstr. 61@*
+40699 Erkrath, Germany
 @sp 1
 @copyrightnotice{}
 @sp 1
@@ -80,7 +81,7 @@ Remscheider Str. 22@*
 @setchapternewpage odd
 
 @titlepage
-@title Using the PINEntry
+@title Using the PIN-Entry
 @subtitle Version @value{VERSION}
 @subtitle @value{UPDATED}
 @author Werner Koch @code{(wk@@gnupg.org)}
@@ -100,14 +101,14 @@ Remscheider Str. 22@*
 @top Introduction
 @cindex introduction
 
-This manual documents how to use the PINEntry and the protocol implemented.
+This manual documents how to use the @pinentry{} and its protocol.
 
-The @sc{pinentry} is a small GUI application used to enter PINs or
-Passphrases. It is usually invoked by @sc{gpg-agent}
+The @pinentry{} is a small GUI application used to enter PINs or
+passphrases. It is usually invoked by @sc{gpg-agent}
 (@pxref{Invoking GPG-AGENT, ,Invoking the gpg-agent, gnupg,
     The `GNU Privacy Guard' Manual}, for details).       
 
-@sc{pinentry} comes in 3 flavors to fit the look and feel of the used
+@pinentry{} comes in 3 flavors to fit the look and feel of the used
 GUI toolkit:  A @sc{GTK+} based one named @code{pinentry-gtk}, a
 @sc{Qt} based one named @code{pinentry-qt} and a non-graphical one based
 on curser and named @code{pinentry-curses}.  Not all of them might be
@@ -126,8 +127,8 @@ Developer information
 Miscellaneous
 
 * Copying::             GNU General Public License says
-                        how you can copy and share GnuPG
-* GNU Free Documentation License:: How you can copy and share this manual.
+                        how you can copy and share PIN-Entry
+                        as well as this manulal.
 
 Indices
 
@@ -136,12 +137,12 @@ Indices
 @end menu
 
 @node Using pinentry
-@chapter How to use the pinentry
+@chapter How to use the @pinentry{}
 
 @c man begin DESCRIPTION
 
-You may run it directly from the commandline and pass the commands
-according to the Assuan protocol via stdin/stdout.
+You may run @pinentry{} directly from the commandline and pass the
+commands according to the Assuan protocol via stdin/stdout.
 
 
 @c man end
@@ -163,23 +164,45 @@ Print a usage message summarizing the most usefule command-line options.
 @itemx -d
 @opindex debug
 @opindex d
-Trun on some debugging.  Mostly useful for the mainatiners.  Note that
+Turn on some debugging.  Mostly useful for the maintainers.  Note that
 this may reveal sensitive information like the entered passphrase.
 
 @item --enhanced
-@itemx -x
+@itemx -e
 @opindex enhanced
 @opindex e
-Ask for timeouts and insurance, too.
-
+Ask for timeouts and insurance, too.  Note that this is currently not
+fully supported.
 
 @item --no-global-grab
 @itemx -g
 @opindex no-global-grab
 @opindex g
-Grab the keyboard only when the window is focused.
-
-
+Grab the keyboard only when the window is focused.  Use this option if
+you are debugging software using the @pinentry{}; otherwise you may
+not be able to to access your X session anymore (unless you have other
+means to connect to the machine to kill the @pinentry{}).
+
+@item --parent-wid @var{n}
+@opindex parent-wid
+Use window ID @var{n} as the parent window for positioning the window.
+Note, that this is not fully supported by all flavors of @pinentry{}.
+
+@item --display @var{string}
+@itemx --ttyname @var{string}
+@itemx --ttytype @var{string}
+@itemx --lc-type @var{string}
+@itemx --lc-messages @var{string}
+@opindex display 
+@opindex ttyname 
+@opindex ttytype 
+@opindex lc-type 
+@opindex lc-messa
+These options are used to pass localization information to
+@pinentry{}.  They are required because @pinentry{} is usally called
+by some background process which does not have any information on the
+locale and terminal to use.  Assuan protocol options are an
+alternative way to pass these information.
 
 @end table
 
@@ -192,17 +215,24 @@ Grab the keyboard only when the window is focused.
 The PIN-Entry should never service more than one connection at once.
 It is reasonable to exec the PIN-Entry prior to a request.
 
-The PIN-Entry does not need to stay in memory because the gpg-agent has
-the ability to cache passphrases.  The usual way to run the PIN-Entry is
-by setting up a pipe (and not a socket) and then fork/exec the
-PIN-Entry.  The communication is then done by means of the protocol
-described here until the client is satisfied with the result.
+The PIN-Entry does not need to stay in memory because the
+@sc{gpg-agent} has the ability to cache passphrases.  The usual way to
+run the PIN-Entry is by setting up a pipe (and not a socket) and then
+fork/exec the PIN-Entry.  The communication is then done by means of
+the protocol described here until the client is satisfied with the
+result.
 
 Although it is called a PIN-Entry, it does allow to enter reasonably
 long strings (at least 2048 characters are supported by every
 pinentry).  The client using the PIN-Entry has to check for
 correctness.
 
+Note that all strings are expected to be encoded as UTF-8; @pinentry{}
+takes care of converting it to the locally used codeset.  To include
+lienfeeds or other special characters, you may percent-escape them
+(i.e. a line feed is encoded as @code{%0A}, the percent sign itself
+is encoded as @code{%25}).
+
 Here is the list of supported commands:
 
 @table @gnupgtabopt
@@ -269,8 +299,9 @@ The value returned is either OK for YES or the error code
 @code{ASSUAN_Not_Confirmed}.
 
 @item Set the output device
-When using X, the pinentry program must be invoked with an
-appropriate DISPLAY environment variable or --display option.
+When using X, the @pinentry{} program must be invoked with an
+appropriate @code{DISPLAY} environment variable or the
+@code{--display} option.
 
 When using a text terminal:
 @example
@@ -281,10 +312,10 @@ When using a text terminal:
   C: OPTION lc-ctype=de_DE.UTF-8
   S: OK
 @end example
-The client should set the ttyname option to set the output tty file
-name, the ttytype option to the TERM variable appropriate for this
-tty and lc-ctype to the locale which defines the character set to
-use for this terminal.
+The client should use the @code{ttyname} option to set the output TTY
+file name, the @code{ttytype} option to the @code{TERM} variable
+appropriate for this tty and @code{lc-ctype} to the locale which
+defines the character set to use for this terminal.
 
 @end table
 
@@ -293,7 +324,6 @@ use for this terminal.
 @c ---------------------------------------------------------------------
 
 @include gpl.texi
-@include fdl.texi
 
 @c ---------------------------------------------------------------------
 @c Indexes
index 5526131..4f50ba8 100644 (file)
@@ -75,6 +75,8 @@ pinentry_utf8_to_local (char *lc_ctype, char *text)
   size_t output_len;
   char *output_buf;
   size_t processed;
+  char *old_ctype;
+  char *target_encoding;
 
   /* If no locale setting could be determined, simply copy the
      string.  */
@@ -85,17 +87,27 @@ pinentry_utf8_to_local (char *lc_ctype, char *text)
       return strdup (text);
     }
 
+  old_ctype = strdup (setlocale (LC_CTYPE, NULL));
+  if (!old_ctype)
+    return NULL;
+  setlocale (LC_CTYPE, lc_ctype);
+  target_encoding = nl_langinfo (CODESET);
+  if (!target_encoding)
+    target_encoding = "?";
+  setlocale (LC_CTYPE, old_ctype);
+  free (old_ctype);
+
   /* This is overkill, but simplifies the iconv invocation greatly.  */
   output_len = input_len * MB_LEN_MAX;
   output_buf = output = malloc (output_len);
   if (!output)
     return NULL;
 
-  cd = iconv_open (lc_ctype, "UTF-8");
+  cd = iconv_open (target_encoding, "UTF-8");
   if (cd == (iconv_t) -1)
     {
-      fprintf (stderr, "%s: can't convert from UTF-8 to local code set: %s\n",
-               this_pgmname, strerror (errno));
+      fprintf (stderr, "%s: can't convert from UTF-8 to %s: %s\n",
+               this_pgmname, target_encoding, strerror (errno));
       free (output_buf);
       return NULL;
     }
@@ -103,8 +115,8 @@ pinentry_utf8_to_local (char *lc_ctype, char *text)
   iconv_close (cd);
   if (processed == (size_t) -1 || input_len)
     {
-      fprintf (stderr, "%s: error converting from UTF-8 to local code set: %s\n"
-               , this_pgmname, strerror (errno));
+      fprintf (stderr, "%s: error converting from UTF-8 to %s: %s\n",
+               this_pgmname, target_encoding, strerror (errno));
       free (output_buf);
       return NULL;
     }
@@ -248,20 +260,20 @@ pinentry_have_display (int argc, char **argv)
 static void 
 usage (void)
 {
-  fprintf (stderr, "Usage: %s [OPTION]...\n\
-Ask securely for a secret and print it to stdout.\n\
-\n\
-      --display DISPLAY Set the X display\n\
-      --ttyname PATH    Set the tty terminal node name\n\
-      --ttytype NAME    Set the tty terminal type\n\
-      --lc-ctype        Set the tty LC_CTYPE value\n\
-      --lc-messages     Set the tty LC_MESSAGES value\n\
-  -e, --enhanced        Ask for timeout and insurance, too\n\
-  -g, --no-global-grab  Grab keyboard only while window is focused\n\
-      --parent-wid     Parent window ID (for positioning)\n\
-  -d, --debug           Turn on debugging output\n\
-      --help            Display this help and exit\n\
-      --version         Output version information and exit\n", this_pgmname);
+  fprintf (stderr, "Usage: %s [OPTION]...\n"
+"Ask securely for a secret and print it to stdout.\n"
+"\n"
+"      --display DISPLAY Set the X display\n"
+"      --ttyname PATH    Set the tty terminal node name\n"
+"      --ttytype NAME    Set the tty terminal type\n"
+"      --lc-ctype        Set the tty LC_CTYPE value\n"
+"      --lc-messages     Set the tty LC_MESSAGES value\n"
+"  -e, --enhanced        Ask for timeout and insurance, too\n"
+"  -g, --no-global-grab  Grab keyboard only while window is focused\n"
+"      --parent-wid     Parent window ID (for positioning)\n"
+"  -d, --debug           Turn on debugging output\n"
+"  -h, --help            Display this help and exit\n"
+"      --version         Output version information and exit\n", this_pgmname);
 }
 
 
@@ -275,26 +287,39 @@ pinentry_parse_opts (int argc, char *argv[])
   int opt_help = 0;
   int opt_version = 0;
   struct option opts[] =
-    {{ "debug", no_argument, &pinentry.debug, 1 },
-     { "display", required_argument, 0, 'D' },
-     { "ttyname", required_argument, 0, 'T' },
-     { "ttytype", required_argument, 0, 'N' },
-     { "lc-ctype", required_argument, 0, 'C' },
+    {{ "debug", no_argument,             0, 'd' },
+     { "display", required_argument,     0, 'D' },
+     { "ttyname", required_argument,     0, 'T' },
+     { "ttytype", required_argument,     0, 'N' },
+     { "lc-ctype", required_argument,    0, 'C' },
      { "lc-messages", required_argument, 0, 'M' },
-     { "enhanced", no_argument, &pinentry.enhanced, 1 },
-     { "no-global-grab", no_argument, &pinentry.grab, 0 },
-     { "parent-wid", required_argument, 0, 'W' },
-     { "help", no_argument, &opt_help, 1 },
+     { "enhanced", no_argument,          0, 'e' },
+     { "no-global-grab", no_argument,    0, 'g' },
+     { "parent-wid", required_argument,  0, 'W' },
+     { "help", no_argument,              0, 'h' },
      { "version", no_argument, &opt_version, 1 },
      { NULL, 0, NULL, 0 }};
   
-  while ((opt = getopt_long (argc, argv, "deg", opts, NULL)) != -1)
+  while ((opt = getopt_long (argc, argv, "degh", opts, NULL)) != -1)
     {
       switch (opt)
         {
         case 0:
         case '?':
           break;
+        case 'd':
+          pinentry.debug = 1;
+          break;
+        case 'e':
+          pinentry.enhanced = 1;
+          break;
+        case 'g':
+          pinentry.grab = 0;
+          break;
+        case 'h':
+          opt_help = 1;
+          break;
+
        case 'D':
          pinentry.display = strdup (optarg);
          if (!pinentry.display)
@@ -339,8 +364,9 @@ pinentry_parse_opts (int argc, char *argv[])
          pinentry.parent_wid = atoi (optarg);
          /* FIXME: Add some error handling.  Use strtol.  */
          break;
+
         default:
-          /* XXX Should never happen.  */
+          fprintf (stderr, "%s: oops: option not handled\n", this_pgmname);
          break;
         }
     }
index b5d4228..7b72c58 100644 (file)
@@ -93,7 +93,7 @@ int pinentry_loop (void);
    LC_CTYPE.  Return NULL on error. */
 char *pinentry_utf8_to_local (char *lc_ctype, char *text);
 
-/* Convert TEXT whcih is encoded according to LC_CTYPE to UTF-8.  With
+/* Convert TEXT which is encoded according to LC_CTYPE to UTF-8.  With
    SECURE set to true, use secure memory for the returned buffer.
    Return NULL on error. */
 char *pinentry_local_to_utf8 (char *lc_ctype, char *text, int secure);