From b8159eadb5636cd9d93ee60c41e75d5978927870 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Tue, 25 Oct 2016 17:27:49 +0200 Subject: 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 --- doc/gpgme.texi | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) (limited to 'doc/gpgme.texi') 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 -- cgit v1.2.3