From 7659d42468b604db2936b021425683f407eba4a7 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Tue, 15 Nov 2016 10:29:48 +0100 Subject: 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 --- doc/gpgme.texi | 68 +++++++++++++++++++++++----------------------------------- 1 file changed, 27 insertions(+), 41 deletions(-) (limited to 'doc/gpgme.texi') 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 -- cgit v1.2.3