[git] Pinentry - branch, master, updated. pinentry-0.9.2-5-g14b95bd
by Neal H. Walfield
cvs at cvs.gnupg.org
Tue May 12 15:48:37 CEST 2015
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "The standard pinentry collection".
The branch, master has been updated
via 14b95bd6d92ba699c3d263ac1f9140973d8c9156 (commit)
via 831782b3b625ca81624fae0ee184da0d2fc46d96 (commit)
via 29236f84aca64be72c97a9b5513457a4e45afbc6 (commit)
via aa04dac66f2ee949e8789a3c91090b01646f2e57 (commit)
from 72939ea63564deec029e8e43743762fdb48cb6e8 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 14b95bd6d92ba699c3d263ac1f9140973d8c9156
Author: Neal H. Walfield <neal at gnu.org>
Date: Tue May 12 15:47:27 2015 +0200
Add new chapter to documentation describing implementation details.
* doc/pinentry.texi: Add new chapter describing some implementation
details.
diff --git a/doc/pinentry.texi b/doc/pinentry.texi
index ec6cc4f..1c47535 100644
--- a/doc/pinentry.texi
+++ b/doc/pinentry.texi
@@ -5,7 +5,7 @@
@include version.texi
@macro copyrightnotice
-Copyright @copyright{} 2002, 2005 g10 Code GmbH
+Copyright @copyright{} 2002, 2005, 2015 g10 Code GmbH
@end macro
@macro permissionnotice
Permission is granted to copy, distribute and/or modify this document
@@ -119,6 +119,7 @@ set.
Developer information
* Protocol:: The Assuan protocol description.
+* Implementation Details:: For those extending or writing a new pinentry.
Miscellaneous
@@ -465,6 +466,180 @@ options can also be used with gpgsm.
@end table
+ at node Implementation Details
+ at chapter Implementation Details
+
+The pinentry source code can be divided into three categories. There
+is a backend module, which lives in @code{pinentry/}, there are
+utility functions, e.g., in @code{secmem/}, and there are various
+frontends.
+
+All of the low-level logic lives in the backend. This frees the
+frontends from having to implement, e.g., the Assuan protocol. When
+the backend receives an option, it updates the state in a
+ at code{pinentry_t} struct. The frontend is called when the client
+either calls @code{GETPIN}, @code{CONFIRM} or @code{MESSAGE}. In
+these cases, the backend invokes the @code{pinentry_cmd_handler},
+which is passed the @code{pinentry_t} struct.
+
+When the callback is invoked, the frontend should create a window
+based on the state in the @code{pinentry_t} struct. For instance, the
+title to use for the dialog's window (if any) is stored in the
+ at code{title} field. If the is @code{NULL}, the frontend should choose
+a reasonable default value. (Default is not always provided, because
+different tool kits and environments have different reasonable
+defaults.)
+
+The widget needs to support a number of different interactions with
+the user. Each of them is described below.
+
+ at table @gnupgtabopt
+ at item Passphrase Confirmation
+
+When creating a new key, the passphrase should be entered twice. The
+client (typically GPG Agent) indicates this to the @pinentry{} by
+invoking @code{SETREPEAT}. In this case, the backend sets the
+ at code{repeat_passphrase} field to a copy of the passed string. The
+value of this field should be used to label a second text input.
+
+It is the frontend's responsibility to check that the passwords match.
+If they don't match, the frontend should display an error message and
+continue to prompt the user.
+
+If the passwords do match, then, when the user presses the okay
+button, the @code{repeat_okay} field should be set to @code{1} (this
+causes the backend to emit the @code{S PIN_REPEATED} status message).
+
+ at item Message Box
+
+Sometimes GPG Agent needs to display a message. In this case, the
+ at code{pin} variable is @code{NULL}.
+
+At the Assuan level, this mode is selected by using either the
+ at code{MESSAGE} or the @code{CONFIRM} command instead of the
+ at code{GETPIN} command. The @code{MESSAGE} command never shows the
+cancel or an other button. The same holds for @code{CONFIRM} if it
+was passed the ``--one-button'' argument. If @code{CONFIRM} was not
+passed this argument, the dialog for @code{CONFIRM} should show both
+the @code{ok} and the @code{cancel} buttons and optionally the
+ at code{notok} button. The frontend can determine whether the dialog is
+a one-button dialog by inspecting the @code{one_button} variable.
+
+ at item Passphrase Entry
+
+If neither of the above cases holds, then GPG Agent is simply
+requesting the passphrase. In this case, the @code{ok} and
+ at code{cancel} buttons should be displayed.
+
+ at end table
+
+The layout of the three variants is quite similar. Here are the
+relevant elements that describe the layout:
+
+ at table @gnupgtabopt
+ at item @code{title}
+The window's title.
+
+ at item @code{description}
+The reason for the dialog. When requesting a passphrase, this
+describes the key. When showing a message box, this is the message to
+show.
+
+ at item @code{error}
+If GPG Agent determines that the passphrase was incorrect, it will
+call @code{GETPIN} again (up to a configurable number of times) to
+again prompt the user. In this case, this variable contains a
+description of the error message. This text should typically be
+highlighted in someway.
+
+ at item @code{prompt}
+The string to associate with the passphrase entry box.
+
+ at item @code{repeat_passphrase}
+The string to associate with the second passphrase entry box. The
+second passphrase entry box should only be shown if this is not
+ at code{NULL}.
+
+ at item @code{ok}, @code{default-ok}
+The string to show in the @code{ok} button.
+
+If there are any @code{_} characters, the following character should
+be used as an accelerator. (A double underscore means a plain
+underscore should be shown.) If the frontend does not support
+accelerators, then the underscores should be removed manually.
+
+There is a subtle difference between @code{ok} and @code{default-ok}.
+ at code{default-ok} means that a stylized OK button should be used. For
+instance, it could include a check mark. @code{ok} means that the
+button's meaning is not consistent with such an icon and, as such, no
+icon should be used. Thus, if the @code{ok} button should have the
+text ``No password required'' then @code{ok} should be used because a
+check mark icon doesn't make sense.
+
+If this variable is @code{NULL}, the frontend should choose a
+reasonable default.
+
+If both variables are set, the @code{ok} variant takes precedence.
+
+ at item @code{cancel}, @code{default-cancel}
+Like the @code{ok} and @code{default-ok} buttons except these strings
+are used for the cancel button.
+
+This button should not be shown if @code{one_button} is set.
+
+ at item @code{notok}, @code{default-notok}
+Like the @code{ok} and @code{default-ok} buttons except these strings
+are used for the other button.
+
+This button should only be display when showing a message box. If
+these variables are @code{NULL} or @code{one_button} is set, this
+button should not be displayed.
+
+ at item @code{quality_bar}
+If this is set, a widget should be used to show the password's
+quality. The value of this field is a label for the widget.
+
+Note: to update the password quality, whenever the password changes,
+call the @code{pinentry_inq_quality} function and then update the
+password quality widget correspondingly.
+
+ at item @code{quality_bar_tt}
+A tooltip for the quality bar.
+
+ at item @code{default_pwmngr}
+If @code{may_cache_password} and @code{keyinfo} are set and the user
+consents, then the @pinentry{} may cache the password with an external
+manager. Note: getting the user's consent is essential, because
+password managers often provide a different level of security. If the
+above condition is true and @code{tried_password_cache} is false, then
+a check box with the specified string should be displayed. The check
+box must default to off.
+
+ at end table
+
+When the handler is done, it should store the passphrase in
+ at code{pin}, if appropriate. This variable is allocated in secure
+memory. Use @code{pinentry_setbufferlen} to size the buffer.
+
+If an error occured, the handler should return @code{-1} and the error
+code should be stored in @code{specific_err} or @code{locale_err}
+should be set to @code{1} (for locale specific errors).
+
+If the dialog was canceled, then the handler should return @code{1}
+and set the @code{canceled} variable to @code{1}.
+
+If the user pressed the not ok button, then the handler should return
+ at code{1}.
+
+If no error occured and the user pressed the ok button, then the
+handler should return @code{0}.
+
+If the window was closed, then the handler should set the
+ at code{close_button} variable and otherwise act as if the cancel button
+was pressed.
+
+
+
@c ---------------------------------------------------------------------
@c Legal Blurbs
@c ---------------------------------------------------------------------
commit 831782b3b625ca81624fae0ee184da0d2fc46d96
Author: Neal H. Walfield <neal at gnu.org>
Date: Mon May 11 16:35:12 2015 +0200
Simplify code.
* pinentry/pinentry.c (cmd_confirm): Don't use nested ternary
expressions.
diff --git a/pinentry/pinentry.c b/pinentry/pinentry.c
index 11a8027..3a44851 100644
--- a/pinentry/pinentry.c
+++ b/pinentry/pinentry.c
@@ -1132,14 +1132,21 @@ cmd_confirm (ASSUAN_CONTEXT ctx, char *line)
if (pinentry.close_button)
assuan_write_status (ctx, "BUTTON_INFO", "close");
- return result ? 0
- : (pinentry.specific_err? pinentry.specific_err :
- pinentry.locale_err? ASSUAN_Locale_Problem
- : (pinentry.one_button
- ? 0
- : (pinentry.canceled
- ? ASSUAN_Canceled
- : ASSUAN_Not_Confirmed)));
+ if (result)
+ return 0;
+
+ if (pinentry.specific_err)
+ return pinentry.specific_err;
+
+ if (pinentry.locale_err)
+ return ASSUAN_Locale_Problem;
+
+ if (pinentry.one_button)
+ return 0;
+
+ if (pinentry.canceled)
+ return ASSUAN_Canceled;
+ return ASSUAN_Not_Confirmed;
}
commit 29236f84aca64be72c97a9b5513457a4e45afbc6
Author: Neal H. Walfield <neal at gnu.org>
Date: Mon May 11 16:14:58 2015 +0200
Implement cmd_confirm in terms of cmd_message.
* pinentry/pinentry.c (cmd_confirm): Implement cmd_confirm in terms of
cmd_message.
diff --git a/pinentry/pinentry.c b/pinentry/pinentry.c
index f28c576..11a8027 100644
--- a/pinentry/pinentry.c
+++ b/pinentry/pinentry.c
@@ -1146,27 +1146,7 @@ cmd_confirm (ASSUAN_CONTEXT ctx, char *line)
static int
cmd_message (ASSUAN_CONTEXT ctx, char *line)
{
- int result;
-
- pinentry.one_button = 1;
- pinentry.quality_bar = 0;
- pinentry.close_button = 0;
- pinentry.locale_err = 0;
- pinentry.specific_err = 0;
- result = (*pinentry_cmd_handler) (&pinentry);
- if (pinentry.error)
- {
- free (pinentry.error);
- pinentry.error = NULL;
- }
-
- if (pinentry.close_button)
- assuan_write_status (ctx, "BUTTON_INFO", "close");
-
- return result ? 0
- : (pinentry.specific_err? pinentry.specific_err :
- pinentry.locale_err? ASSUAN_Locale_Problem
- : 0);
+ return cmd_confirm (ctx, "--one-button");
}
/* GETINFO <what>
commit aa04dac66f2ee949e8789a3c91090b01646f2e57
Author: Neal H. Walfield <neal at gnu.org>
Date: Mon May 11 16:14:18 2015 +0200
Fix memory allocation in pinentry_setbufferlen.
* pinentry/pinentry.c (pinentry_setbufferlen): Set PIN->PIN to a
buffer that is LEN bytes large, not 2 * PIN->PIN_LENGTH.
diff --git a/pinentry/pinentry.c b/pinentry/pinentry.c
index 51c873c..f28c576 100644
--- a/pinentry/pinentry.c
+++ b/pinentry/pinentry.c
@@ -356,11 +356,11 @@ pinentry_setbufferlen (pinentry_t pin, int len)
char *newp;
if (len < pinentry.pin_len)
return NULL;
- newp = secmem_realloc (pin->pin, 2 * pin->pin_len);
+ newp = secmem_realloc (pin->pin, len);
if (newp)
{
pin->pin = newp;
- pin->pin_len *= 2;
+ pin->pin_len = len;
}
else
{
-----------------------------------------------------------------------
Summary of changes:
doc/pinentry.texi | 177 +++++++++++++++++++++++++++++++++++++++++++++++++++-
pinentry/pinentry.c | 49 ++++++---------
2 files changed, 194 insertions(+), 32 deletions(-)
hooks/post-receive
--
The standard pinentry collection
http://git.gnupg.org
More information about the Gnupg-commits
mailing list