core: Implement context flag "override-session-key".

* src/gpgme.c (gpgme_set_ctx_flag): Add flags "export-session-key" and
"override-session-key".
(gpgme_get_ctx_flag): Ditto.
(gpgme_set_export_session_keys): Remove.
(gpgme_get_export_session_keys): Remove.
* src/gpgme.def, src/libgpgme.vers: Remove them.
* src/context.h (struct gpgme_context): Add field
override_session_key.
* src/decrypt-verify.c (decrypt_verify_start): Pass
override_session_key value to the engine.
* src/decrypt.c (decrypt_start): Ditto.
* src/engine.c (_gpgme_engine_op_decrypt): Ditto.
(_gpgme_engine_op_decrypt_verify): Ditto.
* src/engine-backend.h (struct engine_ops): Extend DECRYPT and
DECRYPT_VERIFY_START with override_session_key.
* src/engine-uiserver.c (_uiserver_decrypt): Add stub arg
override_session_key.
(uiserver_decrypt): Ditto.
(uiserver_decrypt_verify): Ditto.
* src/engine-gpgsm.c (gpgsm_decrypt): Ditto.
* src/engine-gpg.c (gpg_decrypt): Add arg override_session_key and set
corresponding gpg option.

* tests/run-decrypt.c (print_result): Print the session key if
available.
(main): Add options --export-session-key and --override-session-key.

--

To keep the number of context manipulation functions at bay, this
patches removes the just added gpgme_set_export_session_keys and
gpgme_get_export_session_keys by flags for the generic context
function.

The patch also implements the --override-session-key feature.

GnuPG-bug-id: 2754
Signed-off-by: Werner Koch <[email protected]>

1 files changed, 27 insertions, 41 deletions

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index e47979c5..eb06c20a 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -191,7 +191,6 @@ Context Attributes
 * Text Mode::                     Choosing canonical text mode.
 * Offline Mode::                  Choosing offline mode.
 * Included Certificates::         Including a number of certificates.
-* Exporting Session Keys::        Requesting session keys upon decryption.
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
@@ -2314,10 +2313,12 @@ The function @code{gpgme_release} destroys the context with the handle
 The detailed result of an operation is returned in operation-specific
 structures such as @code{gpgme_decrypt_result_t}.  The corresponding
 retrieval functions such as @code{gpgme_op_decrypt_result} provide
-static access to the results after an operation completes.  The
-following interfaces make it possible to detach a result structure
-from its associated context and give it a lifetime beyond that of the
-current operation or context.
+static access to the results after an operation completes.  Those
+structures shall be considered read-only and an application must not
+allocated such a strucure on its own.  The following interfaces make
+it possible to detach a result structure from its associated context
+and give it a lifetime beyond that of the current operation or
+context.
 
 @deftypefun void gpgme_result_ref (@w{void *@var{result}})
 The function @code{gpgme_result_ref} acquires an additional reference
@@ -2352,7 +2353,6 @@ started.  In fact, these references are accessed through the
 * Offline Mode::                  Choosing offline mode.
 * Pinentry Mode::                 Choosing the pinentry mode.
 * Included Certificates::         Including a number of certificates.
-* Exporting Session Keys::        Requesting session keys upon decryption.
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
@@ -2643,29 +2643,6 @@ certificates to include into an S/MIME signed message.
 @end deftypefun
 
 
-@node Exporting Session Keys
-@subsection Exporting Session Keys
-@cindex context, exporting session keys
-@cindex Exporting Session Keys
-@cindex exporting session keys
-
-@deftypefun void gpgme_set_export_session_keys (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
-The function @code{gpgme_set_export_session_keys} specifies whether
-the context should try to export the symmetric session key when
-decrypting data.  By default, session keys are not exported.
-
-Session keys are not exported if @var{yes} is zero, and
-enabled otherwise.
-@end deftypefun
-
-@deftypefun int gpgme_get_export_session_keys (@w{gpgme_ctx_t @var{ctx}})
-The function @code{gpgme_get_export_session_keys} returns @code{1} if
-the context will try to export the symmetric session key when
-decrypting, and @code{0} if not, or if @var{ctx} is not a valid
-pointer.
-@end deftypefun
-
-
 @node Key Listing Mode
 @subsection Key Listing Mode
 @cindex key listing mode
@@ -2923,6 +2900,18 @@ format.  For example the non breaking space characters ("~") will not
 be removed from the @code{description} field of the
 @code{gpgme_tofu_info_t} object.
 
+@item "export-session-key"
+Using a @var{value} of "1" specifies that the context should try to
+export the symmetric session key when decrypting data.  By default, or
+when using an empty string or "0" for @var{value}, session keys are
+not exported.
+
+@item "override-session-key"
+The string given in @var{value} is passed to the GnuPG engine to override
+the session key for decryption.  The format of that session key is
+specific to GnuPG and can be retrieved during a decrypt operation when
+the context flag "export-session-key" is enabled.
+
 @end table
 
 This function returns @code{0} on success.
@@ -4798,8 +4787,10 @@ secret key for this recipient is not available, and 0 otherwise.
 This is a pointer to a structure used to store the result of a
 @code{gpgme_op_decrypt} operation.  After successfully decrypting
 data, you can retrieve the pointer to the result with
-@code{gpgme_op_decrypt_result}.  The structure contains the following
-members:
+@code{gpgme_op_decrypt_result}.  As with all result structures, it
+this structure shall be considered read-only and an application must
+not allocated such a strucure on its own.  The structure contains the
+following members:
 
 @table @code
 @item char *unsupported_algorithm
@@ -4817,17 +4808,12 @@ This is the filename of the original plaintext message file if it is
 known, otherwise this is a null pointer.
 
 @item char *session_key
-A textual representation (null-terminated string) of the session key
+A textual representation (nul-terminated string) of the session key
 used in symmetric encryption of the message, if the context has been
-set to export session keys (see @code{gpgme_get_export_session_keys}
-and @code{gpgme_set_export_session_keys}), and a session key was
-available for the most recent decryption operation.  Otherwise, this
-is a null pointer.
-
-You should never access this member of a
-@code{gpgme_op_decrypt_result_t} without first ensuring that
-@code{gpgme_get_export_session_keys} returns non-zero for the
-reporting context.
+set to export session keys (see @code{gpgme_set_ctx_flag,
+"export-session-key"}), and a session key was available for the most
+recent decryption operation.  Otherwise, this is a null pointer.
+
 @end table
 @end deftp