core: New API functions gpgme_set_sender, gpgme_get_sender.

* src/context.h (struct gpgme_context): Add field 'sender'.
* src/gpgme.c: Include mbox-util.h.
(gpgme_release): Free SENDER.
(gpgme_set_sender): New.
(gpgme_get_sender): New.
* src/gpgme.def, src/libgpgme.vers: Add new functions.

* src/engine-gpg.c (append_args_from_sender): New.
(gpg_encrypt_sign, gpg_sign): Call append_args_from_sender.
(gpg_verify): Add arg CTX.  Call append_args_from_sender/
* src/engine-gpgsm.c (gpgsm_verify): Add dummy arg CTX.
* src/engine-uiserver.c (uiserver_verify): Ditto.
* src/engine.c (_gpgme_engine_op_verify): Add arg CTX.
* src/verify.c (verify_start): Pass CTX to engine function.

* tests/gpg/t-verify.c (main): Add some checks for new functions.
* tests/run-sign.c (main): Add option --sender.
* tests/run-verify.c (main): Ditto.

Signed-off-by: Werner Koch <[email protected]>

1 files changed, 43 insertions, 0 deletions

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index cc598887..9fae9aaf 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -186,6 +186,7 @@ Context Attributes
 
 * Protocol Selection::            Selecting the protocol used by a context.
 * Crypto Engine::                 Configuring the crypto engine.
+* Setting the Sender::            How to tell the engine the sender.
 * ASCII Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
 * Offline Mode::                  Choosing offline mode.
@@ -2366,6 +2367,7 @@ started.  In fact, these references are accessed through the
 @menu
 * Protocol Selection::            Selecting the protocol used by a context.
 * Crypto Engine::                 Configuring the crypto engine.
+* Setting the Sender::            How to tell the engine the sender.
 * ASCII Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
 * Offline Mode::                  Choosing offline mode.
@@ -2448,6 +2450,47 @@ successful, or an eror code on failure.
 @end deftypefun
 
 
+@node Setting the Sender
+@subsection How to tell the engine the sender.
+@cindex context, sender
+@cindex sender
+@cindex From:
+
+Some engines can make use of the sender’s address, for example to
+figure out the best user id in certain trust models.  For verification
+and signing of mails, it is thus suggested to let the engine know the
+sender ("From:") address.  @acronym{GPGME} provides two functions to
+accomplish that.  Note that the esoteric use of multiple "From:"
+addresses is not supported.
+
+@deftypefun gpgme_error_t gpgme_set_sender @
+      (@w{gpgme_ctx_t @var{ctx}}, @
+       @w{int @var{address}})
+
+The function @code{gpgme_set_sender} specifies the sender address for
+use in sign and verify operations.  @var{address} is expected to be
+the ``addr-spec'' part of an address but my also be a complete mailbox
+address, in which case this function extracts the ``addr-spec'' from
+it.  Using @code{NULL} for @var{address} clears the sender address.
+
+The function returns 0 on success or an error code on failure.  The
+most likely failure is that no valid ``addr-spec'' was found in
+@var{address}.
+
+@end deftypefun
+
+@deftypefun @w{const char *} gpgme_get_sender @
+      (@w{gpgme_ctx_t @var{ctx}})
+
+The function @code{gpgme_get_sender} returns the current sender
+address from the context, or NULL if none was set.  The returned
+value is valid as long as the @var{ctx} is valid and
+@code{gpgme_set_sender} has not been called again.
+
+@end deftypefun
+
+
+
 @c FIXME: Unfortunately, using @acronym here breaks texi2dvi.
 @node ASCII Armor
 @subsection @acronym{ASCII} Armor